Skip to content

Connecting an agent

How to put a corpus behind an MCP server and point an agent at it. Five minutes.

yidam serve --mcp is the surface that makes a corpus reachable by an agent. That is close to the point of the whole system. RFC-0005 specifies the tool contract: the names, the arguments, the response shapes. That is what someone implementing a second server needs. This is the other document. It covers what to put in a client configuration. It says which tool to reach for, and how to tell what you are connected to.


1. Check which binary carries serve

Any of them. serve --mcp is in the default build. The install script, the Homebrew tap, mise and cargo binstall all give you that one. It includes semantic retrieval and needs no C toolchain. Through mise, that is:

mise use -g "github:goedelsoup/yidam[version_prefix=cli/v]@latest"

version_prefix filters this repository's four tag prefixes down to the CLI's. Without it @latest resolves the editor release, which ships only a .vsix — so it fails rather than installing something stale. See installation.

The vector-read feature is in the default set. What it adds is not the server but the quality of one tool. With it, retrieve is semantic search over a vector index. Without it, retrieve falls back to keyword search and says so on every call. get_node, neighbors, list_nodes, open_questions and every resource are identical in both builds.

yidam --version
# 0.2.1 (a1b2c3d) [reports tonpa]          ← serves; retrieve is keyword
# 0.2.1 (a1b2c3d) [reports vector-read index tonpa]    ← serves; retrieve is semantic

A binary from before vector-read joined the default set prints the first form; reinstalling from any channel gives the second. On an Intel Mac, semantic retrieval also needs ONNX Runtime installed (brew install onnxruntime) — see Installation.

Inside a yidam checkout, mise install && mise run yidam-build provisions the toolchain and installs a --features full binary into .local/bin.

Worth knowing what the fallback is, because it is not a stub. Keyword retrieval spans installed dependencies, labels each result with its origin, and qualifies foreign ids — which the vector path does not do. See §4. It is lexical rather than semantic, and that is the whole of the difference.


2. Configure the client

Claude Desktop, as a bundle

The one route with no terminal in it. Download the .mcpb for your Mac from the latest CLI release . Drag it onto Claude Desktop's Extensions pane, or use a shell:

open yidam-0.25.0-aarch64-apple-darwin.mcpb    # Apple silicon
open yidam-0.25.0-x86_64-apple-darwin.mcpb     # Intel

An .mcpb is a zip holding a manifest and the yidam binary. The bundle installs nothing onto your PATH and writes no configuration file by hand. The installer asks which corpus to serve: a directory picker fills --root, replacing the cd incantation two sections below. That question is the whole reason this channel exists. It is the one thing every other route leaves to the working directory.

Two things to know. The bundle carries the default build, so retrieve is semantic once the corpus has an index (§1). On an Intel Mac that also needs brew install onnxruntime. Without it, retrieve over an index answers with an error that says so. It is also macOS only. Claude Desktop runs on macOS and Windows, and this repository cross-compiles no Windows target. A Linux user wants one of the routes below.

The version is the CLI's own: yidam-0.25.0-… carries yidam 0.25.0. A bundle installed six months ago runs a binary these docs may no longer describe. Reinstalling is dragging a newer file onto the same pane.

Claude Code, as a plugin

This is the one that gives you both halves. Four of the sixteen read tools the contract freezes exist for one reason. The practice is documented in the prelude. But an agent that has to hold that prose in context complies by having remembered. The plugin puts the prose and the tools in the same install.

/plugin marketplace add goedelsoup/yidam
/plugin install yidam@yidam

What arrives: the MCP server, registered, plus eight skills. Each fires at the point a decision is made. writing-a-corpus-commit fires before a commit subject and tagging-a-claim before an evidence tag. linking-a-node fires before a link, citing-a-dependency before a cites:. reading-a-corpus fires before answering from the corpus rather than the model. starting-a-session fires at the start of a session, where what to do next is the decision. running-a-round fires when the work is the loop itself. It takes the first act a tool can take, verifies it, records it, and repeats. starting-a-corpus fires where there is no corpus yet. It is the one that calls no tool, because there is no server to call. Each of the others names the tool, and points at the prelude for the reasoning. None restates a rule: a second copy of a closed vocabulary is a second thing to hold in step. About 800 tokens are always on; the rest is paid only when a skill fires.

The plugin carries no binary. Install yidam first — any channel in installation — and the plugin's launcher will find it. If it cannot, it prints the install line rather than failing as a dead server. If yidam lives off PATH, set YIDAM_BIN to it.

It refuses to serve a directory that is not a corpus. A plugin is installed once, and Claude Code starts its servers in every project you open. So the launcher checks for .yidam/ before spawning anything. serve itself refuses too. The launcher says it in the plugin's terms, and avoids starting a binary just to be told no.

The refusal now names a repair that works. It used to offer yidam clone and yidam overlay. Both derive from the checkout the shell is standing in. Neither did anything in the project the message was printed for. It names starting-a-corpus instead, and first-corpus-by-hand.md for doing it without an agent.

bootstrap.md does not travel. It is the prelude skill for an empty repository. Loading it into a corpus that already exists is wrong, and that is what the plugin installs into. starting-a-corpus is not a copy of it. It asks the ontology questions and writes the smallest corpus that passes the gates. Then it hands off to the dialogue for the growing.

Claude Code, by hand

Run this from inside the corpus repository:

claude mcp add yidam -- yidam serve --mcp

--scope project writes it to .mcp.json in the repository instead of your local settings. The server then becomes part of what a collaborator checks out, rather than something each of them rediscovers. You get the server and none of the skills.

Any client that takes an mcpServers block

{
  "mcpServers": {
    "yidam": {
      "command": "yidam",
      "args": ["serve", "--mcp"]
    }
  }
}

Transport is stdio. The server reads newline-delimited JSON-RPC on stdin and writes frames to stdout. The startup banner and every warning go to stderr. A client that merges the two streams corrupts the protocol.

The working directory is load-bearing

serve locates the corpus with git rev-parse --show-toplevel, from wherever the process was started. It falls back to the current directory when that fails.

It now refuses to serve a directory that is not a corpus. Started somewhere with no .yidam/, it fails at the command and names the repair. On the HTTP transport it fails before the socket is bound. It does not start.

That is a change, and worth knowing if you are upgrading. A client configuration pointing at the wrong directory used to produce a server that answered every tool with nothing. It now produces a server that does not come up. The second is the same misconfiguration, reported. The first was worse than it sounds. Its handshake matched a real corpus that was merely empty. It showed the same nodes: 0, and a domain field derived from the directory's own name. An agent had no way to know a folder was answering it.

A repository bootstrapped an hour ago with nothing written into it yet is still served. The test is .yidam/, not corpus content.

The two blocks above are correct for a client that starts its servers in the project directory. For one that does not, or when you are unsure, say which corpus you mean:

{
  "mcpServers": {
    "yidam": {
      "command": "yidam",
      "args": ["serve", "--mcp", "--root", "/abs/path/to/my-corpus"]
    }
  }
}

--root takes the corpus directory, or any directory inside one. The nearest .yidam/ at or above it wins — the same corpus cd-ing there would have found. This is not git rev-parse --show-toplevel, and the difference matters for a corpus inside another repository. Pointed at one of those, toplevel resolution answers with the outer repository, which is no corpus at all.

A --root that names no corpus is refused, like a working directory that is not one. A typo, or a path that moved, fails at startup. It is not served empty. Every other command that takes --root refuses the same way.

This replaces the shell form these docs used to prescribe:

{"command": "sh", "args": ["-c", "cd /abs/path/to/my-corpus && exec yidam serve --mcp"]}

That still works and there is no reason to keep it. It needed an absolute path and exec. The exec made signals reach the server rather than the shell. That detail has no bearing on corpora, and a reader had to get it right anyway.

The plugin resolves the directory for you and checks before it spawns. The Claude Desktop bundle asks at install time.

Over HTTP, for a client that cannot spawn a process

Every configuration above spawns yidam as a subprocess. A client can only do that on a machine it is running on. A hosted assistant reached through a browser cannot, and neither can the OpenAI Responses API: they take a URL.

yidam serve --mcp --http                       # http://127.0.0.1:8787/mcp
yidam serve --mcp --http --port 0              # any free port; the banner says which
yidam serve --mcp --http --bind 0.0.0.0 --port 8080

One endpoint, POST /mcp, carrying one JSON-RPC message per request. It answers with a single JSON object; a notification gets 202 and no body. GET returns 405. This server sends no messages a client did not ask for, so it opens no event stream. The MCP spec allows that in as many words.

It is the same server. The same code the stdio transport calls produces the tools, the capability block, and the absence and degraded fields. Only the framing differs.

Read-only, one corpus, and by default it authenticates nobody. The defaults reflect that:

--bind127.0.0.1. A server on 0.0.0.0 is reachable by anything on the network, and this one asks no one who they are. Any address off loopback prints a warning at startup, naming every tool it exposes. It takes an IP address, not a name: ::1 and :: work, and localhost is refused.
YIDAM_SERVE_TOKEN or --token-fileUnset. Set one, and every request must carry Authorization: Bearer <token>.
--allow-originEmpty. A request carrying an Origin header is refused unless you name it; one carrying none — curl, and every server-to-server client — passes.

The Origin rule is the MCP spec's defence against DNS rebinding. That is where a page on some other site drives a server bound to your loopback. A browser always sends the header. Naming the origins that may reach it is what makes the check mean something:

yidam serve --mcp --http --allow-origin https://chat.example

A bearer token

To require a token, generate one and give it to the server:

openssl rand -hex 32 > ~/.yidam-token
yidam serve --mcp --http --bind 0.0.0.0 --token-file ~/.yidam-token
# or: YIDAM_SERVE_TOKEN="$(cat ~/.yidam-token)" yidam serve --mcp --http --bind 0.0.0.0

A request without the token gets 401 and WWW-Authenticate: Bearer realm="yidam", on every path. The check runs after Origin and before everything else, so the caller learns nothing about the endpoint. The banner says auth: bearer token required and never prints the token.

There is no flag that takes the token itself. Argv shows in ps and in shell history. Set the variable or the file, not both: the server refuses to start with two. An empty token is refused too. It does not mean "no token".

Give the client the same header:

  • Claude Code: claude mcp add --transport http yidam https://host/mcp --header "Authorization: Bearer $TOKEN".
  • The OpenAI Responses API: the mcp tool's headers map.
  • claude.ai: a custom connector's request headers. That option is a beta, and not every organization has it.

What a token does not do:

  • It names nobody. Every caller shares one secret, so it cannot supply the author a write needs. [serve] act stays refused off loopback with a token set. #427 is where a real identity arrives.
  • It does not encrypt. The token crosses the network in the clear unless something in front of the server terminates TLS. Put one there.
  • It does not reach a browser. A browser sends a preflight OPTIONS before an Authorization header, and this server answers OPTIONS with 405.
  • It serves no OAuth metadata. A client that probes /.well-known/oauth-protected-resource gets 404 and should then use the header it was configured with.

Two probes

GET /healthz and GET /readyz answer without a token and without an Origin check. An orchestrator's probe carries neither. So neither reads anything from the corpus:

/healthz200 live once the port is bound. That is before the corpus is loaded.
/readyz503 until the corpus is loaded, then 200 ready. It is 503 again if the graph stops answering.

The server binds first and loads second. A large corpus takes a while to load, and /mcp answers 503 until it is done. A POST to either probe path is an ordinary request, checked like /mcp.

Serving a bundle, read-only by construction

A server need not run in a checkout. --bundle serves a .yiz that yidam bundle or a cluster run wrote:

yidam serve --mcp --http --bundle streamflow.yiz
yidam serve --mcp --http --bundle sha256:<digest> --vault-url file:///var/yidam/vault

A digest is fetched from the vault. Its bytes are hashed before anything is unpacked. A vault that answers with other bytes is refused, so the digest pins what is served. --vault-url, --vault-region, --vault-endpoint and --vault-path-style read as they do for yidam cluster step. A path needs no vault, and refuses one.

A bundle server is read-only by construction. The bundle is unpacked into scratch. Scratch is not a git repository and holds no .yidam/config.toml. So [serve] act cannot be declared, and no write tool is listed. A write would have no branch to land on. No flag turns that off.

The commit and the domain come from the bundle's manifest. initialize reports the commit the bundle was made at, not an unknown one.


3. Choose the right tool

ToolAnswersReach for it when
retrieveTop-k nodes for a natural-language query, with class, k, corpora and a where over declared date and number properties; an empty answer says which kind of emptyYou do not know which node holds the answer
get_nodeOne node's full YAML content and its outgoing linksYou know the id and need what it actually says
neighborsNodes linked to one node, both directions, to depth hopsYou want the argument around a node, not the node
list_nodesEvery node, optionally in one classYou want the shape of the corpus
open_questionsNodes flagged as unsettledYou are looking for what is not known
claimsAssertions with the standing each is made at, filterable by standingYou want what the corpus holds, not the documents holding it
check_subjectWhether a commit subject is in the closed vocabularyBefore you write the commit
check_citationWhether a cites: into a dependency would hold, and which of the four checks would fireBefore you write the citation
claim_tagsThe three tags, their meanings, and how each may be writtenBefore you tag a claim
licensed_edgesWhat a class declares it may link toBefore you write the link
queryA typed path over the graph — reach -measured-by-> gage, optionally across the dependency setYou know the shape of the answer, not the node
pathsThe typed paths between two nodes, each written as a query you can runYou hold two nodes and do not know how they are related
packThat path's answer as prose, filled to a token budget, with what did not fitYou are about to write from the corpus and have a budget
estimateWhat that would cost, in nodes and approximate tokens, before you pay for itYou have a budget and want to know what fits
cycleWhere this repository is in its loop: what is owed, in flight, blocked, and what the next act isYou are starting a session and do not know where to begin
search_sourcesThe identifiers a source pack's search endpoint answers for a name, each with what its describe would fillYou need a source and do not yet hold its identifier
resolve_sourceThe catalog entry yidam source add would write for one identifier, and what the server's environment lacks to fetch itYou hold an identifier and want the entry before anyone commits it
proposeDrafts the epistemic commits this corpus's findings license, onto a propose/<head> branchYou have been told a clock is due and can discharge it

claims returns assertions; every other tool returns documents. A node is 2–10 sentences by the model's own rule. Asking get_node what a corpus takes as verified pays node-sized tokens for a claim-sized answer. It also leaves you reading the tags out of prose. claims gives you the statement and its standing, and sources names the catalog entries its node cites. It serves the tag or serves nothing — an untagged sentence is prose, and prose is what get_node is for.

check_citation is the one that cannot be answered by reading. retrieve reaches a dependency, get_node reads a node out of one, and query --across walks them. None of them says whether leaning on what it returned would stand. The package may be installed at a different pin than the one you are about to write. A span: is a claim about text that no read-tool checks. It answers with the check ids the gate would report, the installed set, and the pin each dependency actually carries. That pin is the value a correct commit: must hold, and this surface reaches it no other way.

check_subject, claim_tags and licensed_edges are the practice, callable. The commit vocabulary, the evidence tags and the edges a class licenses are all documented in the prelude. An agent that has to hold that prose in context complies by having remembered. These make it cheap to ask instead, at the point in the loop where the decision is actually made. The prose stays: it carries the reasoning, which is what makes the rules arguable.

query walks by the types; neighbors floods. neighbors chains outbound and inbound edges unconditionally, filtering on neither relationship nor direction. It carries both out as labels on the result and reads neither as an input. query takes the relationship and the direction as the question. The difference matters most where it is least visible. A misspelled relationship comes back from a flood as a plausible neighbourhood. From query it comes back as a rejection naming the near miss.

paths finds the walk you did not know to ask for. query needs the path written out. neighbors gives you the nodes next to one node. Neither says how two nodes you already hold are related. paths answers with class paths in query's language, and the server has run each one. Send one to query unchanged and the target is in the answer. matched is the size of that answer. A path matching one node is close to a fact about the pair. An empty answer carries nearest, the shortest connection at any depth, so you can tell too far from not connected.

Both say why an empty answer is empty. Zero rows could otherwise be a bad embedding. It could be a class nobody has written into, or a corpus that genuinely has no view. An agent that cannot tell those apart fills the gap from its own weights. absence carries a code read off what the corpus states. The class is declared and empty. It has instances and none has that value, and here are the values it does have. The relationship is declared and no instance authors it. The edges exist and go somewhere else. An empty result is where an agent invents, and this is the field that stops it. absence.elsewhere names installed packages holding what this corpus does not. It is a pointer, and whatever it names is that corpus's claim, not this one's.

Every read tool answers from the corpus the server loaded at startup, or from its own last write. retrieve, get_node, neighbors and query all read the corpus and index built on disk when the process started. There are no live git operations and no per-request file reads. query --select body is included: it returns the node text as it was read then, not as the file reads now. A server left running while the corpus is edited keeps answering with the corpus it was started against. That is what the staleness banner at connect time is reporting. This is one snapshot on purpose. A body that read the working tree at request time would answer about a different corpus. It would be one field, on one tool, out of step with every field beside it. Restart to move the snapshot.

The one thing that moves it without a restart is a write this server performed. Until the write tier there was none, and the sentence was simply freshness is a restart. A propose that writes a branch reloads the snapshot.

Anything that changed the repository from outside is still invisible until a restart. An edit, a tonpa install, a commit from another process: nothing told the server about any of them. So there is still exactly one snapshot at any moment. What changed is when it was taken.

In practice nothing you can read moves, and that is worth knowing before you design around it. propose builds its commits against a temporary index and creates the ref with update-ref. The working tree is untouched and HEAD does not move. So every read tool answers byte-identically before and after. The reload is a correct no-op for the only write this tier has.

It is there for two reasons. It costs one corpus re-walk on a call that already wrote to git. And the first tool that does touch the working tree should not also have to be a contract change.

A query response says what it is about. kind is query, and the CLI's --between emits a series under the same envelope. A client must not tell the two apart by testing for an absent key. at is the commit the answer is about, and null for the corpus the server holds. It is present on rejected responses too: a refusal about a tag and a refusal about now are different claims.

pack is query with a budget and a receipt. query reports matched beside returned, which says how many nodes it dropped. pack says what kind, in omitted_by_class. That is the difference between knowing you are missing 28 nodes and knowing they were all recording instances. Only the second lets you decide between spending more budget and reporting that the corpus does not cover this. It is unbudgeted unless you ask for a budget. The token figure is chars / 4 and says so. An honest approximation beats a precise-looking number computed with the wrong tokenizer.

estimate quotes; pack accounts. An agent budgets in tokens. It could otherwise only discover what a retrieval cost by paying for it. The only strategy available was to ask for less than might be needed and hope. estimate runs the traversal and returns none of the prose. It prices the same match set at each projection, with a fits verdict against your budget. chars is exact: it is the payload that would come back. ~tokens is chars / 4 and says so. Use chars if you have a real tokenizer. The decision it serves is not whether to ask, but how much of each node to ask for. That is why it comes back as a table rather than a number.

It is also the most speculative thing here, and the epic that asked for it says so. If agents do not act differently given a quote, this is the surface to drop. Nothing depends on it.

licensed_edges, query, paths, pack and estimate are the five a server may not back. All of them need the class definitions. A projected mirror can hold nodes and edges and no .ont.yml. Such a server declares "ontology": false in the handshake. That is a statement you can read, not a hole you discover.

A dependency is queryable, and only if you ask. query takes across: true, which runs the query over every installed dependency's corpus as well. There is one execution per corpus, every result attributed by origin, and foreign ids qualified pkg::class/name.yml. Without it you cannot see a foreign node at all, which is the boundary rather than an oversight. A hop never crosses between corpora. Two corpora sharing a class name is not agreement, so the walk stays inside whichever corpus it started in. scope on the response says what actually happened. Asking to span a repository with no dependencies installed answers local, and that is not an error.

pack and estimate have no across, deliberately. A pack is what you write from. One mixing two corpora would put a dependency's prose under this repository's class names. The omitted_by_class receipt would then be arithmetic over a category nobody declared. Retrieve across, query across, then pack what you decided to keep.

Asking a source pack, and writing nothing

search_sources and resolve_source are yidam source search and yidam source add --dry-run as tools. Neither writes. Adding the entry stays a commit you make with yidam source add.

Every answer carries answered. It is network when the publisher was asked and fixture when a recorded response was read. Reading a listing, a catalog or a pin read to pin a version counts as asking. It is null when nothing was asked. A corpus declares the fixture route in its own config:

[serve]
offline_sources = true

resolve_source also reports needs and unmet. They describe the server's environment, not yours. A pack requiring a contact address needs YIDAM_CONTACT set where the server runs. The answer names the variable and never its value.

Two tools that write, and one that does not, behind a declaration

propose and cycle sit at the act tier, and no server serves them unless the corpus it serves says so. That is one key in the corpus's own .yidam/config.toml:

[serve]
act = true

Until it is written, tools/list carries the read tier and nothing else. That is at most sixteen tools, and usually fewer. Eight of the sixteen are listed only where the corpus backs them. query, paths, pack, estimate and licensed_edges need declared classes. check_citation needs an installed dependency. search_sources and resolve_source need an enabled source pack. Sixteen is the contract's count, not a promise about any one server. What decides each, and what the example corpus below backs, is in §4. A call to either of these comes back capability-not-supported, exactly as an unbacked query does.

This is the one capability in the handshake that is permission rather than ability. Every other key is filled honestly from what the server can do. A projected mirror holds no class files, so ontology is false because it cannot be true. act is false on a server that could write perfectly well, until a deployment says otherwise.

A server permitted to discover that it may write has discovered a policy. A policy a process can discover about itself is not one.

Three more things must hold. Where one does not, act = true makes the server refuse to start rather than quietly serve the read tools:

  • A git author identity must resolve in the corpus being served — the user.name and user.email a commit here would carry. The history these tools write into is the knowledge graph. A commit recording what a process did rather than who decided it is what this clause prevents. A checkout with no identity cannot declare act on any transport, stdio included.
  • The declaration is that key and nothing else. A flag would put it in the launcher's argv — a client config, a desktop manifest, a shell alias. May a tool write into this corpus is a fact about the corpus, not about its launcher.
  • Every listening socket must be loopback. serve --mcp --http --bind 0.0.0.0 with act declared is refused. It is not a security boundary and should not be read as one. Anything on the host reaches loopback. A tunnel in front of a loopback port is the remote case wearing this clause's clothes. What it separates is this machine from another machine, without inventing an authenticator. That is the most a server can see from inside. Over stdio the clause is vacuous: the transport has one peer, and it is the process that started the server.

The refusal is the point rather than an inconvenience. An operator wrote the key and got a running server. They would read that as the answer to the question they asked.

act = "when-identity" asks a different question, and new scaffolds write it. It declares the tier wherever the identity and loopback clauses hold. Where one fails, the server starts with the read tools and declares act: false. It says why at startup, and every refusal of propose or cycle carries the same sentence (contract 0.32.0). A fresh clone with no user.name still serves every read.

propose may write one thing: a branch. Three verbs are drafted as commits onto propose/<head>: open, withdraw, close. Each asserts only what a finding or the corpus's own declarations already assert.

Nothing lands on the baseline, nothing is merged, and nothing is synthesized. There is no establish, no new node, no edge and no retag. You review the branch as commits, and you reject it by deleting it.

It takes dry_run and no force. Replacing a proposal branch discards commits nobody has read, and that repair belongs to a person.

cycle is in the tier and writes nothing, which is what the tier means rather than an exception to it. It reports where the repository is in its loop: owed, in flight, blocked, and what to do next.

A report telling an agent what to do next belongs only where the agent can do it. Shipped at a read tier it would be one more tool naming an act the caller cannot perform.

One thing to know about its answer. The order under next is the server's ranking, not a declaration. No kuten declares a phase order; what one declares is a set of phase types. So a client must not read that list as something the corpus specified.

retrieve finds; get_node reads. The distinction is worth stating plainly, because the gap is easy to miss. A retrieve result carries label, class, path, score and a text. That text is the node's description on the keyword path, and the indexed embedding text on the vector one. On a corpus that writes real prose into description, that text is substantial. That is exactly what makes the omission quiet. It is still not the node. The raw YAML is in get_node's content, and the links are only there. An agent that only ever retrieves sees the claims and never the edges between them. On a knowledge graph that is most of what it came for. Retrieval chooses what to read; get_node is the read.

truncated says whether that text is all of it. Present on every result, false almost always. A remote index ([index.remote]) stores each row's text under a 40 KB ceiling. A row over that ceiling is stored cut. Such a row is rare — one in the low thousands. It is also the kind that grows without a bound. A node's text is the fields somebody wrote; a catalog source's is a whole document. A true here means read the file, not the result. Keyword search and a local index answer false about every row. Neither has a ceiling to cut against.

corpora reaches past this corpus, where an index is shared. Several corpora may push to one vector index. retrieve takes a list of the others and searches them alongside its own. Name one by a nickname this corpus declared, or by a genesis hash. This corpus is always in the set. A caller that wants only the others filters on corpus.

scope says whether that happened. It reads across only when rows could come from more than one corpus, and local otherwise. A server with no shared index answers local however it was asked. That is not an error. It is how a caller tells a span that did not happen from a corpus with nothing to say.

A row from another corpus is named, not fetchable. corpus carries its identity: twelve characters of its genesis hash, null for this server's own rows. Its id is the reference grammar's absolute form, yidam://<corpus>/node/<class>/<name>. get_node cannot resolve it — that corpus is not installed here — so its text is all a reader gets. This is where truncated matters most: the row cannot be opened to see what was cut.

corpus is not origin, and the difference is what you can follow. origin names an installed dependency, whose nodes this server read. A corpus sharing an index is not installed. A misspelled name in corpora is rejected (unknown-corpus) before any search. The reason is unknown-class's: searching only the names that were recognised would answer a question nobody asked.

An empty retrieve says which kind of empty it is. results: [] used to mean four different things at once. An agent that cannot tell them apart fills the gap from its own weights. The claim will then be attributed to having worked in the corpus. Every response carries rejected and absence, both null on an answer that found something:

  • A class that names no declared class is rejected (unknown-class, with the near miss) rather than searched. A filter that cannot match cannot produce a true negative.
  • An empty answer carries absence: {code, message, instances}. class-unpopulated means the class is declared and nothing has been written into it. no-term-match means keyword search read every node and none of them uses these words. That is a statement about the words, not about coverage. class-unindexed means the corpus has the nodes and the index predates them, so re-embed. On a corpus with no .ont.yml the class rows cannot be derived at all. class-undeclared says exactly that instead of guessing.

instances is how many nodes the filter admitted to the search. None of four and none of nine hundred are different facts. It is the difference between "nobody has written this" and "your words missed it".

where is query's predicate, asked of a ranked answer. It takes the text inside a step's [...], verbatim: began<=1893,ended>?1893. The same grammar parses it, the same checker typechecks it and the same evaluator compares it. The rows it admits are exactly the rows query 'tenure[began<=1893,ended>?1893]' returns, ranked. It runs before the k cut. Without a class it narrows as * does, to the classes declaring each property with an ordered type. Only date and number properties can be asked; an ordering on a string is unordered-property, here as there. A where that cannot be asked is rejected under the code query gives the same text. Two rejections are this tool's own. where-unindexed says the local index predates typed property columns, and the repair is yidam embed && yidam index-build. where-remote says the server is backed by a remote index, which carries no properties. Keyword search answers a where in every build. An empty answer whose predicate refused every candidate is predicate-unsatisfied, with instances the candidates it was asked of. That is evidence about the values, not a search that missed.

neighbors is the other half of that. Half the interesting connections into a node are inbound. Reading a node's own YAML shows you only the edges it asserts. The ones asserted at it are invisible from the file.

A claim may carry a qualifier — the scope it is asserted under. [verified — as proposed] says the proposal was checked, not that it was adopted, and claims returns that text alongside the standing. It is free text with no vocabulary. Before contract 0.19.0 such a tag matched none of the three tokens exactly. It was served as no claim at all.

Alongside the tools, the server publishes MCP resources under a yidam:// scheme: yidam://graph/summary, yidam://corpus/<class>, yidam://corpus/<class>/<name>, yidam://skills/<name>, yidam://decisions/<name>. yidam://corpus/<class> and list_nodes are required to answer identically. The resource channel exists for clients that prefer to browse rather than call.

Those five URIs are read by RFC-0032's grammar, not by a second parser. Three of them are references. yidam://corpus/<class> names a set and yidam://graph/summary a computed view; neither is a thing with identity. The server names those two exceptions where it serves them.

A URI naming another corpus — yidam://<corpus>/<kind>/<path> — is refused, not served from this one. The server answers for the repository it was started in.

What it records about what you asked

A second key in the same file, and the only other thing a server does outside the protocol:

[serve]
record = true

With it, one line goes to .yidam/record/calls.jsonl per tools/call, over either transport. Absent, the server writes nothing at all. That is what every server did before this key.

The reason to turn it on is an asymmetry. This corpus can say who asserted every node, and when, and under what review. Until this key it could not say whether any node had ever been read. So three questions had no answer. Which of my queries came back empty. Has this server been answering from keyword search for a month. Did anything ever act on a clock.

{"at":1758758400,"commit":"2bb499a","tool":"retrieve",
 "args_digest":"sha256:9f3a…","outcome":"ok","results":3,
 "node_ids":["concept/a","concept/b","concept/c"],
 "degraded":true,"rejected":false,"ms":12}

yidam record reads the file and answers those questions. It needs no jq.

A refusal is recorded too, on the same shape with outcome: "error". That is the path answering which queries returned nothing. Dropping it would drop the reason to keep the file.

Your query text is never written. A digest of the arguments, and nothing else. Over --http a server answers callers it cannot tell apart, token or no token. The record must not become a file of their questions. A request the token refuses never reaches a tool, so it is never recorded. The digest is stable, so the same call digests alike. This was asked forty times is still answerable.

A retrieve line also carries node_ids: which nodes came back, in rank order. That is how yidam record names the nodes nothing ever retrieved. The ids are names list_nodes already gives any caller. No line says who the caller was.

.yidam/record/ must be gitignored, and the server refuses to start until it is. A tracked record would dirty the working tree after every session anyone served. The server writes no commit. The file is a staging buffer, and yidam record --fold moves it into the history. That writes .yidam/consumption.json as one refresh: commit, holding counts rather than lines. Run it on whatever clock you like: with nothing new, it commits nothing.


4. Check what you are connected to

Three signals, at three different moments.

The banner, at startup, on stderr:

yidam MCP server — domain "streamflow", 8 node(s), 1 skill(s), 2 decision(s)
vector index: absent (no_index) — `retrieve` degrades to keyword search; run `yidam embed && yidam index-build` to build one
serving MCP over stdio

That first line is the check that matters. A domain you do not recognise, or 0 node(s), means the working directory was wrong — see above. It also warns when HEAD has advanced past the commit the index was built at. It keeps serving the stale index rather than refusing.

Over HTTP there is no banner to read. The server is on another machine, so the same facts are in the handshake — see capabilities.yidam.corpus below. Nothing about the check changes; only where you look for it.

capabilities, on initialize. The server declares what it backs under capabilities.yidam rather than letting a client discover the holes through tool-not-found errors:

{"contract": "0.32.0",
 "corpus": {"domain": "streamflow", "commit": "a1b2c3d",
            "nodes": 8, "skills": 1, "decisions": 2,
            "indexed_commit": null, "stale": false},
 "retrieve": {"vector": false, "reason": "no_index"},
 "graph": true, "ontology": true, "dependencies": false,
 "phases": false, "sangha": false, "act": false, "sources": false,
 "resources": true}

corpus is the banner, in the protocol (contract 0.13.0). Every other key here says what this server can do. This one says which corpus it is. Until 0.13.0 that was only ever printed to stderr. A client that spawned the server can read stderr; one that reached it by URL cannot.

stale has three states. true when the index was built at another commit. false when it was not, which covers both current and no index at all; indexed_commit distinguishes those. And null when the server cannot tell. That is the honest answer from a projected mirror with no working git repository behind it. The key is null rather than absent. A client never has to tell "not stale" apart from "a server too old to say".

phases and sangha are false and will stay false for this server. Both read live ma/* and rigpa/* refs. This one reads a built model on disk. ontology follows the corpus. A repository with no .ont.yml has no class contract to back. The five tools at that tier — query, paths, pack, estimate, licensed_edges — are then neither listed nor callable.

dependencies follows the corpus the same way. It is true iff this server resolved at least one installed dependency. check_citation is neither listed nor callable when it did not. The block above is such a server. examples/streamflow declares classes and installs nothing. So it backs the five ontology tools, and not check_citation. That is the ordinary case: most corpora depend on none. A server with nothing installed could serve the tool and answer external-citation-unresolved to every citation put to it. That is correct every time, and a statement about a dependency set it does not have. That is the same thing the contract forbids one tier over. There, a server with no .ont.yml must not call a class unpopulated.

sources follows the corpus too. It is true iff .yidam/sources/ enables a pack, and examples/streamflow enables none.

A tool this server does not back refuses by name. Calling one returns an MCP tool error whose text begins capability-not-supported, naming the capability that is false, rather than unknown tool. The two are different repairs. One says you mistyped a name. The other says this server declines a name the contract froze. Before contract 0.11.1 an unbacked tool was merely absent from tools/list and answered anyway. That put the hole back where the capability block exists to close it.

degraded and degraded_reason, on every retrieve. Both are present on every response — there is no third state, and degraded_reason is null exactly when degraded is false. true means the answer came from case-insensitive term matching over label, description and body. It is ranked by BM25 over the nodes scanned. A short node about your query beats a long one that mentions it. That is a real answer and often a good one, but it is lexical. It will not find a node that says the same thing in different words.

The reason says which repair you need, and they are not the same repair:

degraded_reasonWhat it meansWhat to do
no_indexThis corpus has no vector indexyidam embed && yidam index-build
no_vector_supportAn index exists; this binary cannot read itReinstall from any channel; a build from before vector-read joined the default set, or one built --no-default-features, lacks it
stale_contractAn index exists and was built with different embedding settings than this server uses, so answering from it would be answering in another vector spaceyidam embed && yidam index-build with this binary
remote_unavailableThis corpus is served out of a remote vector index and the service did not answer — a permission, a throttle, an outage, no networkCheck [index.remote] and its credentials; yidam doctor

The distinction is why the field exists. Both answer keyword-degraded. Being told to build an index you already built is the kind of advice that costs an afternoon. Note the precedence. A binary without vector-read on a corpus with no index reports no_index, not no_vector_support. Indexing is the repair under either build, so the reason names the nearer cause.

remote_unavailable is different in kind from the other three and it is worth knowing which you are looking at. Those three are properties of a deployment: they are true when the server starts and stay true for its lifetime. remote_unavailable describes a call, so a server may report it on one request and nothing on the next. A client that caches the first degraded_reason it sees will be wrong about the second question it asks.

It is also one value for every remote failure, deliberately. A 403 and a 503 need different things done about them. But a client branching on this field is deciding one thing: whether to trust the ranking. The answer is the same for both. Which one it was is in the human-readable message beside it.

yidam index-status says whether an index exists and how stale it is.

origin, on a degraded result and on every get_node. Once a dependency is installed with tonpa, the keyword path spans it. Results carry id and origin: the package name for a foreign node, null for a local one. It is null rather than absent. A client testing the key never has to distinguish "local" from "an older server that never said." A foreign id is qualified as pkg::class/name, and get_node accepts that form and answers with origin either way.

The vector path does not span dependencies. yidam embed gathers text from .yidam/corpus/ and .yidam/catalog/ and nowhere else. So the index index-build writes holds this repository's own nodes. An indexed retrieve returns local results carrying no origin. Note that absent is not null here. A key that is missing means the search never looked outside this corpus. That is a different fact from a node being local. On a composed corpus, degraded: true is currently the more complete search. sharing-derivations.md has the history and why this is a gap rather than a boundary.

id is on both arms, and used not to be. This paragraph read "carrying neither id nor origin" and stated the two absences as one fact. They are not one fact. A local node has an id under either arm, and the vector path simply did not emit it. So retrieve found nodes and get_node could not be handed them. That was on the arm a corpus gets for having built an index. The degraded keyword path was the followable one. Fixed in #425. The vector arm resolves each row through the same find_node that get_node resolves with. An id it hands back is therefore an id that fetches, by construction. It is null rather than absent for a row that resolves to no node. That is a catalog source, or an index built before a file moved.

An agent reading a foreign node is reading someone else's claim. It is evidence to consult, not a commitment this repository has made — and it may never be an edge target. neighbors refuses a qualified id for exactly that reason rather than pretending the node is missing. sharing-derivations.md is the document on what a cross-corpus citation is and is not. An agent working a composed corpus should have read it.


5. When it answers nothing

In rough order of likelihood.

The working directory. This one now announces itself: started outside a corpus, the server refuses rather than connecting. If your client reports that the server failed to start, read its stderr. The refusal names the directory it landed in and the repair.

It used to connect. The banner said domain "nowhere", 0 node(s), and list_nodes answered {"nodes": []}. From the client side that was indistinguishable from a corpus that was simply empty. So this entry was advice about reading a node count carefully. It is now a startup failure. Name the directory with --root, or use the plugin, which asks at install time.

The corpus was never built out. A repository that has been bootstrapped but not written into has .yidam/ and no nodes in it. That is a legitimate empty corpus and it is served, because the startup check tests .yidam/, not content. So 0 node(s) on a connection that came up means this, not the case above. yidam status in the repository confirms it.

retrieve finds nothing and list_nodes finds plenty. Almost always degraded: true plus a query phrased in words the corpus does not use — keyword search matches terms, not meanings. Try the corpus's own vocabulary, or read degraded_reason and do what it says.

query or pack finds nothing. Read absence rather than guessing. It says whether the class is declared and empty. It says whether the class has instances that all fail the predicate, and what values they do carry. It says whether the relationship is one the ontology promises and no instance has written. And it says whether the edges are there and land somewhere else. Each has a different repair, and only the first and third mean the corpus is genuinely quiet on the subject.

The client sees garbled frames. Something is folding stderr into stdout. The banner is not protocol.


Reference

ForSee
The frozen tool contract — names, schemas, response shapesrfcs/0005-mcp-tool-contract.md
The machine-readable freeze every server is tested againstyidam/sdks/parity/mcp/tools.json
Which document each contract version names, and how to bump oneyidam/sdks/parity/mcp/CONTRACT_SHA
Dependencies, origin, and what a cross-corpus citation issharing-derivations.md
The index the non-degraded retrieve runs ondomain-computer.md
Getting a corpus to serve in the first placequickstart.md