A senior engineer asks Claude Code to refactor the user-notification pipeline. Claude spawns three subagents, one per service. Subagent A reasons about the shape of the notification event, picks a pattern, and implements it. Subagent B, working in parallel on a different service, reasons independently, picks a different pattern, and implements that one. Subagent C harmonizes by reading the other two and compromising. The pull request is coherent within itself and subtly inconsistent with the rest of the system. The senior engineer reviews it, flags the drift, and asks the team to align before merging. Two days lost.
The subagents were not wrong. They were reasoning locally, which is what they are built for. What they did not have was a shared declaration of what the system is supposed to be. Each one invented one. The inventions did not compose. Ribo exists to make that declaration real, one source of truth that every agent can read, and Claude Code's MCP support is the socket Ribo plugs into.
Local reasoning is cheap. Shared truth is expensive.
Claude Code's power is its orchestration. It will happily spawn a subagent to read a codebase, another to propose a plan, another to implement, another to test. Each runs in isolation with its own context window, does useful work, reports back. The orchestration is what makes non-trivial changes possible in a single session.
But isolation cuts both ways. Two subagents operating on different parts of the same system will each build a mental model from whatever is in front of them. If their contexts do not overlap, their mental models do not agree. The output looks fine in each subagent's slice. The sum of the slices does not make a consistent system.
Teams solve this today with CLAUDE.md files, skill READMEs, and stern prompt discipline. These help. They do not scale, because every file is a snapshot, every snapshot goes stale, and no snapshot is structured enough for a subagent to query. When a subagent needs to know "what does this project consider a valid retry policy," reading a 400-line CLAUDE.md is the wrong shape of answer. It needs a direct lookup.
MCP is the shape that fits. Claude Code's MCP client lets any tool call reach out to an external server during a subagent's turn. Point that at Ribo and the declaration becomes a lookup, not a read.
What changes when every subagent shares a source of truth
Ribo exposes four read tools over MCP: search across declared artifacts, retrieve a specific declaration, list artifacts in a project, walk the relationships between them. Each subagent gets the same view. When subagent A picks a retry policy, it searches Ribo, finds the algorithm artifact that declares exponential backoff with a 30-second ceiling, and uses that. When subagent B makes the same decision two seconds later in a different service, it reaches the same artifact and picks the same pattern. No coordination between subagents is needed. The shared truth lives outside them.
The refactor scenario plays out differently. Subagent A, B, and C each search Ribo for artifacts governing the notification pipeline. They find the contract artifact that declares the envelope schema, the glossary artifact that defines "notification" as distinct from "message" and "event," and the intent artifact that says the pipeline exists to deliver exactly-once to external subscribers. All three implement against the same declared shape. The harmonization step becomes unnecessary. The pull request is coherent because the subagents were never divergent to begin with.
That is the thesis of MCP + Ribo in one sentence: coherence as a property of input, not output.
Role-appropriate projection for a coding agent
Claude Code runs on a developer's machine, which means the token it holds is on a laptop. Keep the projection narrow. Ribo's DNA splits into thirteen layers: intent, contract, algorithm, evaluation, escalation, pace, monitor, glossary, integration, reporting, compliance, constraint, and tradeoff. A coding agent does not need all of them.
The seven layers to expose: intent, contract, algorithm, glossary, constraint, tradeoff, and integration. Intent defines what the component does. Contract defines its interfaces. Algorithm defines how computations behave. Glossary translates the team's vocabulary. Constraint and tradeoff record what the system must not become and why. Integration names the external systems it talks to. These are the declarations that shape code as it is written.
The six layers to withhold: compliance, evaluation, pace, monitor, reporting, and escalation. These are review-time, runtime, and incident-time concerns. A laptop-resident agent does not need them. Excluding them reduces token cost on every MCP call and reduces blast radius if the token is ever leaked.
Ribo mints a separate bearer token per integration with an allowed_kinds list that scopes exactly which layers the integration can read. A Claude Code token built with the seven-layer projection above sees only those layers.
How to wire it up
First, mint the token in the Ribo console. Go to Agents, create an agent named after the developer and repository (claude-code-<user>-<repo> keeps audit logs legible). Set scopes to artifact:read. Set projectIds to the Ribo project covering this repo. Set allowed_kinds to the seven-layer coding-agent projection: intent, contract, algorithm, glossary, constraint, tradeoff, integration. Create the agent. Ribo returns a plaintext bearer token once; capture it immediately.
Second, register the server with Claude Code's CLI. The canonical command is:
| Command | claude mcp add --transport http ribo https://mcp.ribo.dev/context/mcp --scope project |
|---|---|
| Scope | project writes .mcp.json at the repo root and is shared via version control; user writes to ~/.claude.json and spans all your projects; local is the default and stores the server in ~/.claude.json scoped to the current project only |
| Transport | http for Ribo's Streamable HTTP endpoint |
| Auth header | Bearer token from the Ribo console, added via the CLI's prompt or the config file |
Use project scope for repos that have a one-to-one mapping with a Ribo project, and user scope when a single Ribo project serves multiple repos. Claude Code's MCP docs cover the command variants and the managed-MCP config if you run an enterprise controlled rollout. Once registered, every subagent Claude Code spawns in that scope will see Ribo's tools in its tool list and call them when it needs to check a declaration.
What the session looks like
The shift is visible in how Claude Code explains its plans. Without Ribo, a plan reads like a generic software-engineering proposal: "I will add a retry policy to the webhook handler, using exponential backoff with jitter." With Ribo mounted, the same plan reads: "I will add a retry policy to the webhook handler, using exponential backoff with the 30-second ceiling declared in algorithm artifact alg_retry_v2, and routing failures through the notification channel declared in integration artifact int_alert_primary."
The plan is no longer Claude's opinion about good engineering. It is Claude's reading of what the team already decided good engineering was for this system. Disagreements with the plan become disagreements with the artifact, not with the agent. That is the right level of argument to be having.
The point of sharing truth
Claude Code is already the closest thing to a senior engineer pair that runs on your machine. The gap between "pair who knows the system" and "pair who knows software in general" is the gap this integration closes. Every subagent it spawns, every skill it invokes, every command it runs now has the same declared view of what the system is. The cost of coordination falls because the cost of shared context falls. The refactor that used to take two days of harmonization now takes one PR.
Claude Code orchestrates. Ribo anchors. Every subagent reads the same declaration, which is the only way orchestration stops producing drift.