Connect an agent (MCP)

Point Claude or any MCP client at the resolved cascade — from the Mac app, or by running the server from a source checkout.

From the Mac app (recommended)

If you installed ContextCake for Mac, you don’t build a command line by hand. Choose Connect an agent in the app, pick your client — Claude Code, Codex, Cursor, Claude Desktop, or another MCP client — and the app prepares the exact local MCP registration for it, plus a verification step and a first prompt to test with. Add at least one source first: an agent needs something to query.

The rest of this page is the source route: starting mcp-server.mjs from a checkout and registering it with your client yourself. The tools an agent sees are identical on both paths.

Start the server

mcp-server.mjs is a dependency-free stdio MCP server. It resolves every read through the same cascade engine as the CLI — section/field merge, precedence, provenance, per-section conflicts — and exposes the result as MCP tools.

Point it at the bundled demo:

node mcp-server.mjs --manifest apps/playground/manifest.json

With a Project Profiles manifest, register this command once. The server selects --profile when explicitly supplied; otherwise it uses the deepest project mapping that contains the MCP process’s startup working directory, then falls back to default.

Or use the legacy two-layer form, no manifest file required:

node mcp-server.mjs --personal ~/kb-personal --shared ~/kb-shared

--help prints usage for both forms.

Register it with Claude Code

Use absolute paths — MCP clients spawn the server from their own working directory, not yours:

claude mcp add contextcake -- node /ABS/PATH/mcp-server.mjs --manifest /ABS/PATH/apps/playground/manifest.json

The server identifies itself over the MCP initialize handshake as contextcake. Any MCP-compatible client — not just Claude Code — can spawn it the same way: command is node, args are the script path and flags.

Verify automatic selection

From a mapped project folder, first confirm the CLI selection:

cd /ABS/PATH/TO/MAPPED/PROJECT
contextcake profile current

Start a new agent session from that folder. Its MCP initialization instructions should name the same stable profile id and reason: project; the display label is available in structured initialization metadata. Then call list_concepts and confirm only that profile’s concepts appear. The project path itself is never included in MCP instructions.

Some clients do not start a global stdio server with the project as its working directory. For those clients, automatic folder mapping is unavailable. Use the default profile, or create a separately named opt-in registration whose command is contextcake mcp --profile <id>. Do not replace the one global automatic registration unless that client requires it.

Tools

Tool	What it returns
`search`	One entry per matching concept ID, with a snippet and the layers that contribute to it. Takes `query` and an optional `limit`.
`read_file`	The resolved effective concept: merged sections, frontmatter, provenance, and per-section conflicts. Takes `concept_id`; pass `layer` to instead read one layer’s raw, unmerged concept.
`list_concepts`	Every effective concept ID across the cascade with its contributing layers. Takes an optional `type` filter.
`get_links`	Outgoing and incoming links for a concept, resolved against the effective graph. Takes `concept_id`.
`find_captures`	Recent, unreviewed teammate captures ranked by relevance and recency. Takes `query`, optional `kinds`, and optional `limit`.
`whats_new`	Captures and curated-concept changes since a timestamp. Takes `since`.

Reading a resolved concept as an agent

Call read_file with concept_id: "decisions/primary-db" against the demo manifest and the response carries the same shape the CLI prints: contributors (every layer that has this concept, with its updated date), frontmatterProvenance (which layer set each frontmatter field), and sections each tagged with the sourceLayer that won them. Where layers disagree on a section, the losing layers’ content rides along as that section’s conflicts array instead of being dropped.

This is what makes the resolved graph safe for an agent to read directly: it can quote the winning value as authoritative, but it can also see that there’s a live disagreement, who holds each position, and when each side was last updated — so it can flag the disagreement to a human instead of silently picking a side, or weight a personal-layer note lower than a company-layer policy when they conflict.

MCP tools reference — full input/output schemas for the read tools (and the capture tools behind --capture)
The trust boundary — what spawning an mcp layer’s command means for the machine running the server