MCP — conecta Tesserae con Claude Code, Codex, Cursor

<!-- translations:start -->

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

<!-- translations:end -->

Tesserae incluye un servidor stdio de Model Context Protocol que expone el grafo tipado compilado a cualquier cliente compatible con MCP: Claude Code, Codex CLI, Cursor, Claude Desktop y otros. El servidor anuncia las tres superficies completas de MCP — tools, resources y prompts — de modo que los clientes pueden tanto consultar el grafo bajo demanda como sembrar contexto de forma económica a partir de URIs canónicas.

Requisitos previos

El servidor lee desde .tesserae/graph.json, por lo que se requiere una compilación inicial:

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

Recompila siempre que cambien tus fuentes. El servidor recogerá el nuevo grafo en la siguiente llamada a una tool sin necesidad de reiniciar.

1) Generar la configuración del cliente

tesserae projects mcp-config

Imprime un fragmento JSON aproximadamente así:

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

La ruta exacta se completa a partir del proyecto actual. Pasa --name <alias> si quieres un nombre de entrada de servidor distinto a tesserae.

2) Pégalo en tu cliente MCP

Reinicia el cliente después de editarlo. La siguiente sesión se conectará y descubrirá la superficie de Tesserae.

3) Lo que ve el cliente

Tools — invocadas por el modelo

Cada tool acepta un graph_path o project (alias del registro) opcional, de modo que un solo servidor puede resolver cualquier vault registrado por llamada. Si se omite, recurre al proyecto activo.

Consulta y recuperación del grafo

Compilador de contexto bajo demanda (Phase 7)

Memoria de sesiones (ver sessions.md)

Preguntas y registro

Configuración guiada

Resources — cargados automáticamente al contexto del modelo

URIs que el cliente puede incorporar mediante su selector de recursos sin gastar un turno de tool:

• tesserae://graph/schema — la misma carga útil que la tool schema, lista como contexto estático
• tesserae://graph/summary — resumen del proyecto activo
• tesserae://lint-report — el último lint report en markdown

Además de plantillas de URI que el cliente puede construir bajo demanda:

• tesserae://wiki/{kind}/{slug} — el cuerpo de cualquier página wiki compilada
• tesserae://raw/{source_path} — cualquier markdown fuente sin procesar

Prompts — plantillas de investigación de un solo clic

Aparecen en el menú de comandos del cliente (por ejemplo, la paleta / de Claude Code):

Cada prompt se renderiza como un único mensaje de usuario que le indica al modelo exactamente qué tools de Tesserae encadenar, así el modelo no tiene que redescubrir la superficie cada vez.

Multiproyecto: registra varias vaults bajo un mismo servidor

Un registro persistente en ~/.tesserae/registry.json permite que el mismo servidor MCP resuelva cualquier proyecto registrado por nombre:

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

A partir de esto, cada tool que acepte project o graph_path resolverá project: "research" contra el registro en lugar de necesitar una ruta completa. El servidor incluso valida que el graph_path registrado siga existiendo y devuelve un error claro si hace falta recompilar.

Fan-out sobre cada vault registrada

La tool ask acepta scope: "all-registered" para consultar cada proyecto registrado en paralelo y devolver resultados agregados:

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

Restringe a un subconjunto con scope_aliases: ["research", "notes"].

Claude CLI multicuenta

Si tu tool ask se enruta a través de la Claude CLI y tienes varias cuentas (por ejemplo, ~/.claude y ~/.claude-personal2), pasa claude_config_dir por llamada:

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

El servidor exporta CLAUDE_CONFIG_DIR solo durante esa llamada y restaura el valor anterior al terminar. Sin filtraciones entre llamadas.

Verificación

Después de reiniciar tu cliente MCP, confirma la conexión:

• Claude Code: /mcp debería listar tesserae con el conteo de tools.
• Cursor: el icono MCP en la barra de chat debería mostrar tesserae: connected con los conteos de tools/resources/prompts.
• Codex / Hermes: invoca cualquier tool por nombre (por ejemplo, schema) y revisa la respuesta.

Si no aparece nada, verifica que --graph apunte a un .tesserae/graph.json existente — el servidor ahora valida esto al arrancar y en cada llamada a tool, así que verás un mensaje de error claro en lugar de un 500 silencioso.

Dónde encaja esto

El servidor MCP es la interfaz de lectura al grafo tipado. Para la ruta de escritura (ingestar fuentes, recompilar, refrescar herramientas acompañantes como RAG-Anything o Understand-Anything) usa la CLI directamente. Ambas están desacopladas: la CLI actualiza .tesserae/, y el servidor MCP lee lo que haya allí en la siguiente llamada a tool.