--- title: "Set up ChatCrystal MCP: make Claude Code calls reviewable" description: Connect ChatCrystal to Claude Code with a project-scoped stdio server, then verify its seven tools, HTTP backend, approvals, and request path. image: "https://zengliangyi.com/og/blog/en/chatcrystal-mcp-setup.png" --- 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](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/src/cli/mcp/server.ts), [CLI command](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/src/cli/commands/mcp.ts), and fixed commit [`7642768`](https://github.com/ZengLiangYi/ChatCrystal/tree/764276814e5c5a33ecbfeae63754f74b9261a3a8). Use the [official Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) 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: ```bash 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: ```bash 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 ```text 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: ```text /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](/en/blog/agent-knowledge-memory-loop) for task-memory boundaries. Share: ## Related Posts [## Claude Code memory workflow: recall, verify, then write back Use recall_for_task, validate_task_memory, and write_task_memory as an auditable workflow without treating MCP configuration as an automatic-memory guarantee. 曾亮懿 October 3, 2026 4 min read #ChatCrystal #MCP #Claude Code](/en/blog/claude-code-memory-workflow) [## MCP Boundaries: Discovery, Identity, and Call Permissions Examine Model Context Protocol boundaries: tool discovery, server instance tracking, and execution permissions in reviewable developer environments. 曾亮懿 October 7, 2026 4 min read #ChatCrystal #MCP #Node.js](/en/blog/mcp-protocol-boundaries) [## A Minimal MCP Server: Register Tools & Verify Stdio Calls Build an offline addition tool with TypeScript SDK, verify protocol discovery and calls, and inspect ChatCrystal adapter integration boundaries. 曾亮懿 October 6, 2026 4 min read #ChatCrystal #MCP #Node.js](/en/blog/mcp-server-implementation) ## From writing to code Explore ChatCrystal, developer tools and daily learning notes on my GitHub. Questions about the implementation are welcome. [Visit my GitHub](https://github.com/ZengLiangYi) ```json { "@context": "https://schema.org", "@type": "WebSite", "name": "ZengLiangYi Blog", "alternateName": [ "Zeng Liangyi", "ZengLiangYi", "zengliangyi.com" ], "url": "https://zengliangyi.com", "description": "曾亮懿的个人网站。记录 AI Native 探索、开发者工具与全栈产品实践。" } { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "Set up ChatCrystal MCP: make Claude Code calls reviewable", "description": "Connect ChatCrystal to Claude Code with a project-scoped stdio server, then verify its seven tools, HTTP backend, approvals, and request path.", "url": "https://zengliangyi.com/en/blog/chatcrystal-mcp-setup/", "image": "https://zengliangyi.com/images/blog/chatcrystal-mcp-setup.svg", "datePublished": "2026-10-03T00:00:00.000Z", "dateModified": "2026-10-03T00:00:00.000Z", "author": { "@type": "Person", "name": "曾亮懿", "url": "https://zengliangyi.com/en/about" }, "publisher": { "@type": "Organization", "name": "ZengLiangYi Blog", "logo": { "@type": "ImageObject", "url": "https://zengliangyi.com/favicon-96x96.png" } }, "mainEntityOfPage": { "@type": "WebPage", "@id": "https://zengliangyi.com/en/blog/chatcrystal-mcp-setup/" } } { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://zengliangyi.com/en" }, { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://zengliangyi.com/en/blog" }, { "@type": "ListItem", "position": 3, "name": "Set up ChatCrystal MCP: make Claude Code calls reviewable", "item": "https://zengliangyi.com/en/blog/chatcrystal-mcp-setup/" } ] } ```