ChatCrystal 的 MCP 入口是一个 stdio 桥接层：Claude Code 启动 crystal mcp 子进程，子进程再通过 HTTP 调用 ChatCrystal Server。stdio 不等于整个链路没有网络，也不等于工具每次都会自动调用；配置、服务健康和具体请求都要分别验收。
本文依据 MCP server 实现、CLI 命令 和固定提交 7642768。Claude Code 的安装命令和作用域以官方 MCP 文档为准。
先启动可访问的 ChatCrystal 服务
CLI 要求 Node.js 24 或更高版本；安装后在默认本机连接上启动服务：
npm install -g chatcrystal
crystal serve --daemon
crystal statuscrystal mcp 启动时会先请求服务状态，再注册 stdio 工具。默认本机连接的服务未运行时，客户端会尝试后台启动并等待就绪；其他连接不会这样启动。健康或状态检查最终失败时，MCP 不会进入正常工具通信阶段。默认本机端口是 3721。若使用云端连接，应通过 CLI 的 token/base URL 连接配置完成认证；不要把真实 token 写进项目文件。应用当前对自定义回环地址有连接限制，先以实际 crystal status 和连接配置为准。
用 Claude Code 项目作用域注册
官方 CLI 使用 -- 把 Claude Code 的选项与 stdio 命令参数分开。项目作用域会写入项目根目录的 .mcp.json，适合团队审阅和共享：
claude mcp add --scope project --transport stdio chatcrystal -- crystal mcp
claude mcp list
claude mcp get chatcrystal首次使用项目级服务器可能需要在 Claude Code 中批准工作区。也可以检查 .mcp.json 内容，但不要把 API token 或机器特定路径提交到仓库。官方文档说明了 local、project、user 三种作用域及其优先级；如果只想本机使用，可省略 --scope project 使用 local 作用域。
核对七个工具的实际边界
服务器注册以下工具：
search_knowledge：语义检索，默认上限 10。get_note：按 ID 读取完整笔记。list_notes：每页最多 20 条，支持标签和标题/摘要筛选。get_relations：读取某条笔记的关系。recall_for_task：将有界全库检索的候选筛选为项目记忆与全局补充。validate_task_memory：写回前的无副作用质量预检。write_task_memory：把有具体结论的经验写回知识库。
工具结果以 MCP text content 返回 JSON 字符串，不是文章里可以直接假定的任意结构化对象。list_notes 的搜索筛选沿用 API 的 SQL LIKE 语义；需要语义排序时调用 search_knowledge。自动写回会严格拒绝一次性状态报告、模糊日志和不可复用的内容；手动模式仍有结构校验，但标题、摘要和结论可读时，可能带质量警告接受。接受结果也不代表经验已经被当前项目验证。
明白 stdio 与 HTTP 的关系
Claude Code
│ MCP stdio
▼
crystal mcp
│ HTTP (CrystalClient)
▼
ChatCrystal Server :3721
└─ SQLite + Vectracrystal mcp 是 Claude Code 启动的 stdio 子进程。协议消息占用 stdout，诊断日志写入 stderr；不要在 MCP 进程里向 stdout 打印调试文本。桥接进程依赖 HTTP 服务的可达性、认证和超时，stdio 只描述 Claude Code 与桥接进程之间的传输。
逐层验收连接
先运行 crystal status，再在 Claude Code 中执行：
/mcp查看 chatcrystal 的连接状态和工具数量。随后用一个知识库中确实存在的问题请求 search_knowledge，再用返回的 ID 调 get_note；不要只凭列表里出现服务器名称就宣称检索成功。最后可用一个有具体结论的构造记忆先调用 validate_task_memory，确认质量门槛后再决定是否写回。
Claude Code 能调用工具不保证每次自然语言请求都会自动调用它。需要确定性流程时，在项目规则或任务步骤中明确要求先回忆、展示来源、再验证后写回。更多任务记忆边界见 Agent 知识记忆闭环。