MCP and IDE Integration

• Three ways an editor or agent host reaches Cymatix: the MCP shim (Claude Code, Cursor, Claude Desktop), the OpenAI-compatible proxy (Continue, or any client that honors OPENAI_BASE_URL), and raw HTTP API.
• The MCP adapter is a thin shim, not a second engine. It speaks stdio JSON-RPC to the host and proxies every tool call over HTTP to a running cymatix-server. It does no retrieval of its own — so the backend must be up, and everything on Configuration applies unchanged.
• The default tool surface is deliberately lean. Every registered tool's name, description, and JSON schema is injected into the host's context on every turn, so 0.9.1 ships ten core tools and hides the admin, diagnostic, and legacy surface behind CYMATIX_MCP_FULL=1.
• Canonical cymatix_document_* names are the ones to call. The legacy biology-named tools still work under the full surface, with a deprecation nudge in their docstrings. Nothing was removed.
• The consuming agent must carry the prompt fragment. Without it, capable models paint over do_not_answer_from_genome: true and answer from their training prior anyway. See Agent Contract.

Setup

Install the extra, run the backend, then register the shim:

pip install "cymatix-context[mcp]"
cymatix-server                      # binds 127.0.0.1:11437

{
  "mcpServers": {
    "cymatix-context": {
      "command": "python",
      "args": ["-m", "cymatix_context.mcp_server"],
      "cwd": "/absolute/path/to/your/project",
      "env": {
        "CYMATIX_MCP_URL": "http://127.0.0.1:11437"
      }
    }
  }
}

• Claude Code reads this from a project-level .mcp.json or a user-level ~/.claude/mcp.json. Cursor and Continue take the same mcpServers block under their own MCP config file.
• The server self-identifies as cymatix, so tools appear to the host as mcp__cymatix__*.
• On Windows, wrap the stdio launcher as cmd /c python ... when python is not directly resolvable in the host's spawn environment.

The tool surface

Core set — what ships by default (ten tools).

cymatix_document_query defaults its session_id to the MCP subprocess's own session, so repeated calls within one host session elide already-delivered documents automatically.

Canonical and legacy names. The five document_* tools are thin pass-throughs to existing handlers — identical behavior, better names.

CYMATIX_MCP_FULL=1 unhides everything else — 24+ tools in total. Set it in the same env block. What appears:

• Retrieval / store: cymatix_refresh_targets, cymatix_stats, cymatix_resonance, cymatix_consolidate, plus the legacy names above.
• Session registry: cymatix_session_recent, cymatix_announce.
• HITL events: cymatix_hitl_emit, cymatix_hitl_recent.
• Operational: cymatix_metrics_tokens, cymatix_bridge_status, cymatix_swap_db.

Accepted truthy values: 1, true, yes, on. Pruning is non-fatal — if the adapter cannot enumerate or remove a tool it logs a warning and leaves the full surface exposed. Correctness over token savings.

Identity

The eight identity variables are not optional in spirit. Anything you omit falls back to a default that erodes attribution: badges read unknown and the authored_by_* columns fill with mcp-<pid> instead of your handle.

"env": {
  "CYMATIX_MCP_URL":    "http://127.0.0.1:11437",
  "CYMATIX_ORG":        "your-org",
  "CYMATIX_PARTY_ID":   "your-device",
  "CYMATIX_DEVICE":     "your-device",
  "CYMATIX_USER":       "you",
  "CYMATIX_AGENT":      "laude",
  "CYMATIX_AGENT_KIND": "claude-code",
  "CYMATIX_MCP_HANDLE": "laude",
  "CYMATIX_MCP_HOST":   "claude-code"
}

Per-host conventions:

How a call actually travels

Two hops, always:

Claude Code  --stdio JSON-RPC-->  cymatix_context.mcp  --HTTP-->  cymatix-server
   (host)                          (thin adapter)                 127.0.0.1:11437

• On subprocess start the adapter registers itself as a participant: it reads the identity env, posts to /sessions/register, starts a heartbeat, and attaches capability tags ["mcp_tools", "host:<CYMATIX_MCP_HOST>"]. Registration failure is non-fatal — tool calls still proxy, and a warning is logged to the adapter's stderr.
• On every tool call the adapter wraps the arguments into an HTTP request, attaches the four identity layers on ingest paths, and forwards the response back over stdio.
• On heartbeat it pings /sessions/{participant}/heartbeat on a timer. Stop the host process and the participant TTLs out naturally.

Verifying the route. Ask the agent to call cymatix_health, then check the dashboard at http://127.0.0.1:11437/launcher: the Parties panel should show your CYMATIX_PARTY_ID, Identities your CYMATIX_USER workspace, and Agents a participant matching CYMATIX_MCP_HANDLE with the host:<...> capability tag.

The agent-side skill

skills/cymatix/SKILL.md is the contract Claude follows when calling these tools — the identity contract and the tool-use rules. It is purely instructional; it runs no code. Install it project-scoped or user-global:

mkdir -p .claude/skills/cymatix
cp <repo>/skills/cymatix/SKILL.md .claude/skills/cymatix/SKILL.md

# or once, for every project
mkdir -p ~/.claude/skills/cymatix
cp <repo>/skills/cymatix/SKILL.md ~/.claude/skills/cymatix/SKILL.md

Continue IDE

models:
  - name: Cymatix (Local)
    provider: openai
    model: gemma3:e4b
    apiBase: http://127.0.0.1:11437/v1
    apiKey: EMPTY
    roles: [chat]
    defaultCompletionOptions:
      contextLength: 128000
      maxTokens: 4096

Use Chat mode, not Agent mode. The proxy intercepts messages and injects context; it does not route tool calls. Agent mode will appear to work and then fail on the first tool invocation. If you want tool-shaped access from Continue, add the mcpServers block above instead.

OpenAI-compatible proxy

OPENAI_BASE_URL=http://localhost:11437/v1 your-app

Zero code changes. Cymatix intercepts the messages, runs the retrieval pipeline, injects the assembled window into the system message, and forwards to [server] upstream. Details: HTTP API.

Which surface to pick

All three run the same pipeline against the same store and return the same JSON shapes, so an integration can move between them without changing its parser.

Tool responses keep legacy field names on the wire — gene_id in a cymatix_document_get or cymatix_document_neighbors result is verbatim, not a leak from an unconverted page. The tool names and the prose moved to software terms; renaming the JSON contract is a tracked Tier-3 change, deliberately not taken in 0.9.1 because it breaks every existing consumer. See Lexicon.

Go deeper

• docs/clients/claude-code.md — the routing reference: the two hops, the full identity contract, per-host variants, request lifecycle
• docs/api/mcp-tools.md — per-tool input schemas
• skills/cymatix/SKILL.md — the agent-side identity contract and tool-use rules
• docs/architecture/SESSION_REGISTRY.md — the server-side presence and attribution model
• docs/agent-sdk-fragment.md — the prompt fragment the consuming agent must carry
• Next: Agent Contract · HTTP API · CLI · Getting Started