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 project setup    # interactive; or --yes for non-interactive
tesserae project 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 project 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

Tools — invoked by the model

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 active 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 register-project /path/to/research --name research
tesserae register-project /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.

Fan-out across every registered vault

The ask tool accepts scope: "all-registered" to query every registered project in parallel and return aggregated results:

{
  "name": "ask",
  "arguments": {
    "question": "Where is splatting used?",
    "scope": "all-registered"
  }
}

Restrict to a subset with scope_aliases: ["research", "notes"].

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.