MCP — Tesserae를 Claude Code, Codex, Cursor에 연결하기

<!-- translations:start -->

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

<!-- translations:end -->

Tesserae는 컴파일된 타입 그래프를 MCP를 지원하는 모든 클라이언트(Claude Code, Codex CLI, Cursor, Claude Desktop 등)에 노출하는 Model Context Protocol stdio 서버를 함께 제공합니다. 이 서버는 세 가지 MCP 표면(tools, resources, prompts)을 모두 광고하므로, 클라이언트는 필요에 따라 그래프를 쿼리할 수도 있고 정형 URI로부터 저렴하게 컨텍스트를 시드할 수도 있습니다.

사전 요구사항

서버는 .tesserae/graph.json에서 읽어오므로, 한 번의 컴파일이 필요합니다:

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

소스가 변경될 때마다 다시 컴파일하세요. 서버는 재시작 없이 다음 tool 호출에서 새 그래프를 자동으로 인식합니다.

1) 클라이언트 설정 생성

tesserae project mcp-config

대략 다음과 같은 JSON 스니펫을 출력합니다:

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

정확한 경로는 현재 프로젝트에 맞춰 채워집니다. 서버 항목 이름을 tesserae가 아닌 다른 이름으로 지정하고 싶다면 --name <alias>를 전달하세요.

2) MCP 클라이언트에 붙여넣기

편집 후 클라이언트를 재시작하세요. 다음 세션에서 연결되어 Tesserae 표면이 인식됩니다.

3) 클라이언트가 보는 것

Tools — 모델이 호출하는 도구

Resources — 모델 컨텍스트에 자동 로드

클라이언트가 tool 턴을 소비하지 않고도 리소스 선택기를 통해 가져올 수 있는 URI:

• tesserae://graph/schema — schema tool과 동일한 페이로드를 정적 컨텍스트로 제공
• tesserae://graph/summary — 활성 프로젝트의 요약
• tesserae://lint-report — markdown 형식의 최신 lint 보고서

또한 클라이언트가 필요에 따라 구성할 수 있는 URI 템플릿:

• tesserae://wiki/{kind}/{slug} — 컴파일된 모든 위키 페이지 본문
• tesserae://raw/{source_path} — 모든 원본 소스 markdown

Prompts — 원클릭 리서치 템플릿

이 항목들은 클라이언트의 슬래시 메뉴(예: Claude Code의 / 팔레트)에 표시됩니다:

각 prompt는 모델이 어떤 Tesserae tool을 어떤 순서로 연결해야 하는지를 정확히 알려주는 단일 사용자 메시지로 렌더링되므로, 모델이 매번 표면을 다시 발견할 필요가 없습니다.

다중 프로젝트: 하나의 서버에 여러 vault 등록하기

~/.tesserae/registry.json에 저장되는 영속 레지스트리를 통해 동일한 MCP 서버가 이름으로 등록된 모든 프로젝트를 해결할 수 있습니다:

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

이후 project 또는 graph_path를 받는 모든 tool은 전체 경로 대신 project: "research"를 레지스트리에 대해 해결합니다. 서버는 등록된 graph_path가 여전히 존재하는지 검증하고, 재컴파일이 필요한 경우 명확한 오류를 반환합니다.

등록된 모든 vault에 대한 팬아웃

ask tool은 scope: "all-registered"를 받아 등록된 모든 프로젝트를 병렬로 쿼리하고 집계된 결과를 반환합니다:

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

scope_aliases: ["research", "notes"]로 부분집합으로 제한할 수 있습니다.

다중 계정 Claude CLI

ask tool이 Claude CLI를 통해 라우팅되고 여러 계정(예: ~/.claude와 ~/.claude-personal2)이 있다면, 호출마다 claude_config_dir을 전달하세요:

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

서버는 해당 호출 동안에만 CLAUDE_CONFIG_DIR을 export하고 이후 이전 값을 복원합니다. 호출 간 누수가 없습니다.

검증

MCP 클라이언트를 재시작한 뒤 연결을 확인하세요:

• Claude Code: /mcp에 tesserae가 tool 개수와 함께 나열되어야 합니다.
• Cursor: 채팅 바의 MCP 아이콘에 tesserae: connected와 tool/resource/prompt 개수가 표시되어야 합니다.
• Codex / Hermes: 이름으로 임의의 tool(예: schema)을 호출하고 응답을 확인하세요.

아무것도 나타나지 않는다면 --graph가 기존 .tesserae/graph.json을 가리키는지 다시 확인하세요 — 서버는 이제 시작 시점과 모든 tool 호출 시점에 이를 검증하므로, 조용한 500 대신 명확한 오류 메시지를 보게 됩니다.

어디에 적합한가

MCP 서버는 타입 그래프에 대한 읽기 인터페이스입니다. 쓰기 경로(소스 수집, 재컴파일, RAG-Anything 또는 Understand-Anything 같은 동반 도구 갱신)에는 CLI를 직접 사용하세요. 둘은 분리되어 있습니다: CLI는 .tesserae/를 업데이트하고, MCP 서버는 다음 tool 호출 시 그곳에 있는 것을 읽습니다.