MoAI-ADK 在 Claude Code 的 MCP 生态之上，又叠加了一个自有的 MCP 服务器。一个二进制文件（moai mcp-server）以 stdio 本地服务器的方式运行，向 Claude Code 运行时暴露 MoAI-ADK 独有的 17 个工具——SPEC 生命周期审计、验证快照、目标引擎、跨模型审计、codex 委托等。

两份 MCP 文档的关系

Claude Code 通用 MCP 讲的是平台自身的 MCP（Model Context Protocol）集成——USB 端口比喻、服务器注册、传输类型、/mcp 命令、OAuth 认证、延迟加载原理。

本文档讲的是叠加在其上的 MoAI 自有 MCP 服务器。两个表面共享相同的核心规则，但所讨论的主体不同。

Claude Code 的 MCP 生态与 MoAI 的自有 MCP 服务器是各自独立的服务器，但都建立在相同的运用原则之上。它们共享三条核心规则。

flowchart TD
    CC["Claude Code 运行时
(工具权限 · 延迟加载 · 审批)"]
    CMCP["通用 MCP 服务器
(context7, chrome-devtools, …)"]
    MMCP["moai mcp-server
(MoAI 自有 · 17 工具)"]
    CC --> CMCP
    CC --> MMCP
    MMCP --> TOOLS["SPEC lifecycle · 验证 · 目标 · 审计 · codex 委托"]
    CMCP --> EXT["外部工具 (库文档 · 浏览器自动化 · …)"]

关键在于，“MoAI 不配置 MCP"是一个半真半假的说法。不默认配置外部 MCP 服务器（context7、playwright 等）是对的。但 MoAI 自有的那个服务器在 moai init 时就会以 default-on 装上。这个服务器正是 MoAI 的 17-工具目录触达 Claude Code 的通道。

moai init 在项目根目录创建 .mcp.json（project scope），在里面建立恰好一个活跃条目——自有的 moai 本地 stdio 服务器。

{
  "mcpServers": {
    "moai": {
      "command": "moai",
      "args": ["mcp-server"]
    }
  },
  "staggeredStartup": {
    "enabled": true,
    "delayMs": 500,
    "connectionTimeout": 15000
  }
}

staggeredStartup 是 Claude Code 运行时字段，用来调节服务器顺序启动。当服务器有多个时，它能防止同时启动的竞争（race）。

部署默认值只有 moai 一个服务器处于活跃状态。四个外部服务器已写入文档但处于禁用状态，用 moai mcp add <名称> 命令来开启。

.mcp.json 是 git-tracked 文件。因此"搭载秘密的条目、需要凭证的条目、未通过中立性检查的条目"是禁止的。所有环境变量的值都以 ${VAR} 字面量写入——Claude Code 运行时扩展实际值，被解释的秘密不会被序列化到 git-tracked 的 .mcp.json 中。

{
  "remote-needs-auth": {
    "type": "http",
    "url": "https://mcp.example.com/sse",
    "headers": {
      "Authorization": "Bearer ${MY_API_KEY}"
    }
  }
}

${MY_API_KEY} 由运行时从环境变量中填充。文件本身只保留字面量字符串，所以秘密不会暴露到存储库中。

用户不直接手编 .mcp.json。moai mcp add|remove|list CLI 管理该文件，且此 CLI 通过 atomic-RWM seam（flock 文件锁 + compare-retry + 备份后写入 + idempotent-skip）运作。即使两个会话同时编辑，也不会让一边的变更覆盖另一边。

moai mcp-server 暴露的 17 个工具分为五组。调用时都带 mcp__moai__ 前缀。

用于 plan-phase（manager-spec 编写新 SPEC 时确认时代分类和漂移）与 sync-phase（manager-docs 验证生命周期终结）。plan-auditor 用 spec_audit / spec_drift 执行 plan-phase 的怀疑式审查。

manager-develop 在 run-phase 自验证（接缝 §E）中使用，sync-auditor 和 super-advisor 用于审查趋势。verify_snapshot 读取或记录以 HEAD 摘要为键的快照，verify_trend 展示用于判断收敛的历史。

goal_arm 是编排器专用的——自治循环武装是编排器关注的事，所以不在智能体内调用。这是为了保留平面层级武装表面而做的设计。goal_status 是 manager-develop / manager-kanban 读取已武装条件进度的通道，session_list 是 manager-kanban 在 fan-out 前检测同一检出上并发会话的竞争缓解手段。

单一后端审计模式由项目的 audit_model 设置决定：codex+glm（默认值，通过 audit_multi 收敛）| glm | codex | none（Claude 独自，无后端调用）。所有后端都是 fail-open——不可用的后端返回 inconclusive，而非 Go error。

codex 委托工具族连线到 super-advisor——因为按需高推理咨询智能体是后台跨模型委托的自然消费者。用 codex_task 委托任务，用 codex_job_status / codex_job_result 轮询完成情况，用 codex_job_cancel 中断。codex 是可选的（optional）——缺失或不可用时返回 fail-open 的 inconclusive，而非 hard error。

当智能体的 tools: 列表中存在 MCP 工具时优先走 MCP 路径而非 CLI。两条路径在后台跑的是同一套实现。MCP 路径的优势有三：

• 返回结构化输出（无需解析）
• 避开 shell-quoting 风险
• 在 Bash 可能受限的子智能体环境中以低延迟运作

CLI 仅在 MCP 工具不在 tools: 列表中，或在主会话中 CLI 形态更自然时使用。

在 GLM 会话（moai glm 或 moai cg 的 GLM 面板）中运行时，网络搜索和网络查询会路由到 z.ai MCP 工具，而非内置的 WebSearch / WebFetch。认证从 ~/.moai/.env.glm 读取。

z.ai MCP 服务器（zai-mcp-server、web_search_prime、web_reader）默认禁用，在 GLM 会话中用 moai glm tools enable 开启。GLM 会话中的路由规则请参考多 LLM 后端。

codex 审计/委托工具（codex_audit、codex_task 等）从 ~/.codex/auth.json 读取认证凭证。codex 是可选的——认证文件不存在或 codex 未安装时，相关工具返回 inconclusive 并继续。这是智能体工作不依赖于 codex 可用性的设计。

GLM、codex、Claude——三个后端都遵循 fail-open 原则。不可用的后端只会返回 inconclusive，不会引发 Go error。即使一个后端缺失，其余后端也能让审计收敛；如果所有后端都不可用，则以 Claude 独自运作（audit_model: none）。

codex 委托工具中的 codex_task 可以用 background: true 启动后台任务。此时不等待任务结束就立即返回任务 ID。

进度通过两个工具来轮询：

codex_task(background=true) ──▶ 返回任务 ID
       │
       ├── codex_job_status(任务 ID) ──▶ 运行中 / 完成 / 失败
       │
       └── codex_job_result(任务 ID) ──▶ 完成时读取输出

需要时 codex_job_cancel(任务 ID) ──▶ 中断

可以在 MCP 控制台（Web 控制台）中查看各工具的设置和认证状态。控制台的详细功能请参考 Web 控制台。

MoAI 自有 MCP 服务器也和 Claude Code 通用 MCP 一样遵循延迟加载原则。如果把工具定义全部常驻加载到上下文中，上下文窗口会很快填满，因此平时只放简短的元数据，在实际调用时才加载 schema。

要调用延迟工具，必须先用 ToolSearch 将 schema 加载到活动上下文中。

需要工具了 ──▶ {schema 在上下文中吗？}
                   │
            ┌──────┴──────┐
            否              是
            │               │
    先用 ToolSearch         调用工具
    加载 schema
            │
            └──▶ 调用工具

跳过此步骤，工具调用会因验证错误而被拒绝。延迟加载原理的背景说明请参考 Claude Code 通用 MCP 文档的"延迟加载与 Tool Search"一节。

• Claude Code 通用 MCP — 平台自身的 MCP 集成（USB 端口比喻、服务器注册、传输类型、/mcp 命令）
• 多 LLM 后端 — Claude × GLM 多后端运用 · GLM 会话中网络搜索/查询路由到 z.ai MCP 工具的规则
• 跨模型审计 — 多审计者收敛机制
• Web 控制台 — MCP 工具设置与认证表面