MCP — wire Tesserae into Claude Code, Codex, Cursor

<!-- translations:start -->

한국어 · 中文 · 日本語 · Русский · Español · Français · Deutsch

<!-- translations:end -->

Tesserae ships a Model Context Protocol stdio server that exposes the compiled typed graph to any MCP-aware client: Claude Code, Codex CLI, Cursor, Claude Desktop, and others. The server advertises three full MCP surfaces — tools, resources, and prompts — so clients can both query the graph on demand and seed context cheaply from canonical URIs.

Prerequisites

The server reads from .tesserae/graph.json, so a one-time compile is required:

cd /path/to/your-project
tesserae init    # interactive; or --yes for non-interactive
tesserae compile  # deterministic, no LLM calls, no API keys

Recompile any time your sources change. The server will pick up the new graph on the next tool call without needing to restart.

1) Generate the client config

tesserae projects mcp-config

Prints a JSON snippet roughly like:

{
  "mcpServers": {
    "tesserae": {
      "command": "python3",
      "args": [
        "-m", "tesserae.mcp_server",
        "--graph", "/path/to/your-project/.tesserae/graph.json"
      ]
    }
  }
}

The exact path is filled in from the current project. Pass --name <alias> if you want a different server entry name than tesserae.

2) Paste it into your MCP client

Restart the client after editing. The next session will connect and discover the Tesserae surface.

3) What the client sees

Every tool accepts an optional graph_path or project (registry alias) so a single server can resolve any registered vault per call. With no explicit project, read tools resolve the project you're in (the nearest registered project root above the server's cwd), then the server's --graph. There is no "active project" — all registered projects are equal.

Graph query & retrieval

On-demand context compiler (Phase 7)

Session memory (see sessions.md)

Q&A & registry

Guided setup

Resources — auto-loaded into the model's context

URIs the client can pull in via its resource picker without burning a tool turn:

• tesserae://graph/schema — same payload as the schema tool, ready as static context
• tesserae://graph/summary — summary of the resolved (cwd) project
• tesserae://lint-report — the latest lint report as markdown

Plus URI templates the client can construct on demand:

• tesserae://wiki/{kind}/{slug} — any compiled wiki page body
• tesserae://raw/{source_path} — any raw source markdown

Prompts — one-click research templates

These appear in the client's slash menu (e.g. Claude Code's / palette):

Each prompt renders to a single user message that tells the model exactly which Tesserae tools to chain, so the model doesn't have to rediscover the surface every time.

Multi-project: register several vaults under one server

A persistent registry at ~/.tesserae/registry.json lets the same MCP server resolve any registered project by name:

tesserae projects register /path/to/research --name research
tesserae projects register /path/to/notes    --name notes

After this, every tool that accepts project or graph_path will resolve project: "research" against the registry instead of needing a full path. The server even validates that the registered graph_path still exists and returns a clear error if a recompile is needed.

Querying across projects

With no scope, the ask tool routes the question for you: it picks a single project when the question clearly targets one, and federates (one merged, cross-referenced answer) when it's comparative or general. The two explicit cross-project scopes:

• federated — assemble ONE graph from the named projects (identity-merged + embedding-backed semantic links) and return a single cross-referenced answer. Defaults to ALL registered projects; narrow with scope_aliases. semantic is on by default.
• all-registered — fan out and return one independent answer per project (by_project).

{
  "name": "ask",
  "arguments": {
    "question": "What did I decide about caching, and does any clipped paper support it?",
    "scope": "federated"
  }
}

Restrict either scope to a subset with scope_aliases: ["research", "notes"]. Inspect a federation from the CLI with tesserae federation status / tesserae federation explain <node>.

Multi-account Claude CLI

If your ask tool routes through the Claude CLI and you have multiple accounts (e.g. ~/.claude and ~/.claude-personal2), pass claude_config_dir per call:

{
  "name": "ask",
  "arguments": {
    "question": "...",
    "claude_config_dir": "/Users/you/.claude-personal2"
  }
}

The server exports CLAUDE_CONFIG_DIR for the duration of that call only and restores the previous value afterwards. No leakage between calls.

Verification

After restarting your MCP client, confirm the connection:

• Claude Code: /mcp should list tesserae with the tool count.
• Cursor: the MCP icon in the chat bar should show tesserae: connected with tool/resource/prompt counts.
• Codex / Hermes: invoke any tool by name (e.g. schema) and check the response.

If nothing appears, double-check that --graph points at an existing .tesserae/graph.json — the server now validates this on startup and on every tool call, so you'll see a clear error message instead of a silent 500.

Where this fits

The MCP server is the read interface to the typed graph. For the write path (ingesting sources, recompiling, refreshing companion tools like RAG-Anything or Understand-Anything) use the CLI directly. The two are decoupled: the CLI updates .tesserae/, the MCP server reads whatever's there on the next tool call.