Set up ChatCrystal MCP: make Claude Code calls reviewable

ChatCrystal’s MCP entry point is a stdio bridge: Claude Code starts crystal mcp as a child process, and that process calls the ChatCrystal Server over HTTP. Stdio does not make the whole path network-free, and a configured tool is not guaranteed to be called for every request. Verify configuration, service health, and an actual request separately.

This article follows the MCP server, CLI command, and fixed commit 7642768. Use the official Claude Code MCP documentation for current installation flags and scopes.

Start a reachable ChatCrystal service first

The CLI requires Node.js 24 or later. Install it and start the default local connection:

npm install -g chatcrystal
crystal serve --daemon
crystal status

crystal mcp checks service status before registering stdio tools. If the implicit local-default service is stopped, the client attempts a background start and waits for readiness; other connections do not auto-start this way. If health or status checks ultimately fail, the MCP process does not enter normal tool communication. The default local port is 3721. For a cloud connection, configure the CLI’s token and base URL through the supported connection flow; do not commit a real token. The application restricts custom loopback connection addresses, so verify the actual status and connection configuration.

Register a project-scoped Claude Code server

The official CLI uses -- to separate Claude Code options from the stdio command’s arguments. Project scope writes to .mcp.json at the project root, which makes the entry reviewable and shareable:

claude mcp add --scope project --transport stdio chatcrystal -- crystal mcp
claude mcp list
claude mcp get chatcrystal

The first use of a project server may require workspace approval in Claude Code. You can inspect .mcp.json, but do not commit an API token or machine-specific path. The official documentation describes local, project, and user scopes and their precedence; omit --scope project when you want a local-only entry.

Check the seven tools and their actual boundaries

The server registers these tools:

• search_knowledge: semantic search, default limit 10.
• get_note: full note lookup by ID.
• list_notes: up to 20 notes per page, with tag and title/summary filters.
• get_relations: relations for a note.
• recall_for_task: filters bounded library-wide retrieval candidates into project memories and global supplements.
• validate_task_memory: side-effect-free quality preflight before writeback.
• write_task_memory: writes a concrete, durable lesson to the knowledge base.

Tool results use MCP text content containing JSON strings. Do not assume an arbitrary structured object. list_notes uses the API’s SQL LIKE filtering; use search_knowledge for semantic ranking. Auto writeback strictly rejects one-time status reports, vague logs, and non-reusable material. Manual mode still performs structural validation but can accept readable titles, summaries, and conclusions with quality warnings. Acceptance does not prove that a lesson applies to the current project.

Understand the stdio and HTTP relationship

Claude Code
  │ MCP stdio
  ▼
crystal mcp
  │ HTTP (CrystalClient)
  ▼
ChatCrystal Server :3721
  └─ SQLite + Vectra

crystal mcp runs as a stdio child process started by Claude Code. Protocol messages occupy stdout; diagnostic logs go to stderr. Do not print debugging text to stdout from the MCP process. The bridge still depends on the HTTP service’s reachability, authentication, and timeout behavior; stdio only describes transport between Claude Code and the bridge.

Verify the connection in layers

Run crystal status, then inspect the server in Claude Code:

/mcp

Check the chatcrystal status and tool count. Then ask search_knowledge about a problem that is known to exist in the knowledge base and call get_note with the returned ID. Seeing a server name in a list is not proof that retrieval worked. For writeback, call validate_task_memory with a constructed memory containing a concrete lesson before deciding whether to call write_task_memory.

Claude Code’s ability to call a tool does not guarantee invocation on every natural-language request. For a deterministic workflow, state that the agent must recall first, show its source, validate the current task, and only then write back. See the Agent knowledge loop for task-memory boundaries.