Getting the Most Out of the Geneziz MCP Server

So you ran geneziz mcp register and your assistant can now see your knowledge base. The connection is the easy part — the value comes from how you use it. This is the playbook we use ourselves, written for both sides of the session: the human prompting and the agent reaching for tools.

Rule 1: Orient before you search

A knowledge base is not a web index. Before searching, a good agent takes one round-trip to understand what's in there — using tools only:

get_recent(days=7, limit=10)   → what's been saved lately
list_categories()              → the shape of the archive (tools, articles, topics)
list_tags(limit=20)            → how it's organized
list_domains()                 → which sources you actually collect

This prevents the classic failure mode: searching for something the base simply doesn't have, then hallucinating around the empty result.

Note: overall counts live in the knowledge://stats resource, not a tool. Clients that surface MCP resources can read it; assistants that only list tools should orient with the four calls above instead.

Rule 2: Two search tools, two different jobs

Geneziz ships two search tools, and picking the right one first is the single biggest speed win:

Practical pattern for an agent: start with search_fulltext; escalate to search_knowledge only when the keyword results feel adjacent-but-wrong. Semantic search reads more but answers vaguer questions — don't pay for it when the exact string "FastMCP import error" is already in your notes.

Two behaviors worth knowing:

• search_knowledge degrades gracefully: if the vector index isn't built, it returns a degraded: true marker plus best-effort keyword results instead of failing. Agents should handle both shapes.
• The server rate-limits (~120 calls per minute). Batch your reads; don't loop queries in a tight cycle.

Both return highlighted snippets. When a result matters, don't stop at the snippet:

Rule 3: Snippets are for triage — read, then expand

search_* gives you a preview. When a hit is the real thing, pull the whole file with the slug the results already carry:

get_article(name="local-first-vs-cloud-bookmarks")
get_tool(name="ripgrep")

Then do what search can't: expand sideways.

find_related(filename="local-first-vs-cloud-bookmarks", limit=5)

find_related returns the nearest neighbors of a file you already trust — it's the fastest path from one good hit to the five articles that belong with it. And if your base is bookmark-heavy, get_bookmark(author="...") pulls rich X.com entries (text, engagement, folders) directly.

Rule 4: List with filters, not with huge limits

list_tools and list_articles paginate (limit caps at 100, use offset). Push your assistant toward filtered listings instead of "list everything":

list_tools(category="ai", limit=20)
list_articles(domain="github.com", tag="rust")

offset pagination means "give me the next 20 of the same query" — not "give me 400 items and I'll scroll". Your context window will thank you.

Rule 5: Save with intent — and know when it becomes searchable

Two capture tools, two purposes:

• add_note(title, body) — write a real note. Use it for decisions, learnings, snippets you want to find later. Tag it (tags=["rust", "perf"]) — tags are how future-you searches.
• save_url(url, note="...") — files the link with an optional annotation. It does not fetch the page. It's a stub: URL + your note, ~450 bytes. That's by design — full-page capture is the browser extension's job (it stores the complete snapshot), and hydrate/enrich can fill the body later.

The mistake to avoid: an agent "saving an article" with save_url and an empty note, then wondering why search can't find the article's content. If the content matters right now, it goes in the note — or gets captured via the extension.

When do saves show up in search? When the indexer next runs — the desktop app's pipeline does this automatically; from a terminal it's geneziz index. A file saved seconds ago isn't searchable yet, and that's expected. Tell your agent, or it will "verify" the save with a search and wrongly report failure.

Everything saved through MCP is stamped with its true provenance (via: MCP save / the mcp-note tag), so agent-saved items are always distinguishable from extension saves in your stats.

Rule 6: Clean up while you're in there

find_duplicates(threshold=0.92) surfaces near-duplicate articles by embedding similarity. It's report-only — it never merges or deletes anything. Running it occasionally and merging by hand what it flags keeps semantic search honest: duplicates don't just waste space; they split the "same" idea across vectors and dilute results.

A real session, start to finish

This isn't hypothetical — it's how the playbook above was validated. An agent finished a tooling setup, then closed the loop in three moves: save_url ×7 for the reference articles (each with a one-line why), add_note ×1 for the decision record (tags: best-practices, mcp, dogfooding), then one index run. Every future session — any MCP client, not just the one that did the saving — can now search the reasoning, not just the links.

A compact prompt for your assistant

If you use Claude Code, Cursor, ZCode, or any MCP client, drop this in your project instructions — it encodes everything above:

When working with the Geneziz knowledge base:
1. Orient first: get_recent(7), list_categories, list_tags — never search blind.
2. search_fulltext for exact names/errors; escalate to search_knowledge only
   for fuzzy concepts. Handle its "degraded" fallback shape.
3. Read full items with get_article/get_tool using the slug from results,
   then expand with find_related. Rate limit is ~120 calls/min — batch reads.
4. List with filters (category/domain/tag) + offset pagination; never request
   unbounded lists.
5. save_url files a URL + note ONLY (no fetch; put key content in the note).
   add_note for standalone learnings, always with tags. New saves become
   searchable only after the indexer runs — do not "verify" a save by
   searching for it immediately.
6. Run find_duplicates occasionally; merge its findings by hand.

The habit that compounds

Every tool above is read-mostly by design — the MCP surface is safe to let an agent explore. The compounding effect comes from Rule 5: every session that ends with add_note("what we decided", ...) or a well-annotated save_url makes the next session's Rules 1–4 smarter. That's the whole point of a second brain: it should get better at helping you simply because you used it.