MoAI-ADK は Claude Code の MCP エコシステムの上に乗り、さらにその上に独自の MCP サーバーを1つ載せます。バイナリ1つ（moai mcp-server）が stdio ローカルサーバーとして動作し、SPEC ライフサイクル監査、検証スナップショット、ゴールエンジン、クロスモデル監査、codex 委任など、MoAI-ADK 固有の17個のツールを Claude Code ランタイムに公開します。

2つのMCP文書の関係

Claude Code 一般 MCPはプラットフォーム自身の MCP（Model Context Protocol）統合を扱います — USB ポートの比喩、サーバー登録、転送タイプ、/mcp コマンド、OAuth 認証、遅延ロードの原理。

この文書はその上に乗ったMoAI 自身の MCP サーバーを扱います。2つの表面は同じコア規則を共有しますが、扱う主体が異なります。

Claude Code の MCP エコシステムと MoAI の独自 MCP サーバーは、互いに別個のサーバーでありながら、同一の運用原則の上に置かれます。3つのコア規則を共有します。

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 自身のサーバー1つは moai init の時点で default-on で入ります。このサーバーこそが、MoAI の17ツールカタログが Claude Code に届く通路です。

moai init はプロジェクトルートに .mcp.json（project scope）を生成し、その中に正確に1つのアクティブエントリを置きます — 自身の moai ローカル stdio サーバーです。

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

staggeredStartup はサーバーが順次起動するように調整する Claude Code ランタイムのフィールドです。サーバーが複数あるとき同時起動の競合（race）を防ぎます。

配布デフォルトは moai サーバー1つだけがアクティブです。4つの外部サーバーは文書に記録されていますが無効状態で、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 シーム（flock ファイルロック + compare-retry + バックアップ後書き込み + idempotent-skip）で動作します。2つのセッションが同時に編集しても、一方の変更がもう一方を上書きしません。

moai mcp-server が公開する17個のツールは5つのグループに分かれます。呼び出し時点ではすべて 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 がファンアウト前に同一チェックアウトの同時セッションを検出する競合緩和の手段です。

単一バックエンド監査モードはプロジェクトの 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 ツールがあれば CLI より MCP 経路を優先します。両経路は背後で同じ実装を実行します。MCP 経路が有利な理由は3つあります:

• 構造化された出力を返す（パースが不要）
• shell-quoting のリスクを避ける
• サブエージェントで Bash が制限されうる環境で低レイテンシで動作する

CLI は MCP ツールが tools: リストにないとき、またはメインセッションで CLI 形式がより自然なときだけ使います。

GLM セッション（moai glm または moai cg の GLM パネル）で実行すると、ウェブ検索とウェブ照会が組み込みの WebSearch / WebFetch の代わりに z.ai MCP ツールへルーティングされます。認証は ~/.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 — 3つのバックエンドはすべて fail-open 原則に従います。利用不可なバックエンドは inconclusive を返すだけで、Go error を起こしません。1つのバックエンドが欠けても残りで監査が収束し、どのバックエンドもなければ Claude 単独で動作します（audit_model: none）。

codex 委任ツールのうち codex_task は background: true でバックグラウンドジョブを開始できます。この場合ジョブが終わるまで待たず、即座にジョブ ID を返します。

進行状況は2つのツールでポーリングします:

codex_task(background=true) ──▶ ジョブ ID 返却
       │
       ├── codex_job_status(ジョブ ID) ──▶ 実行中 / 完了 / 失敗
       │
       └── codex_job_result(ジョブ ID) ──▶ 完了時に出力読み取り

必要なら codex_job_cancel(ジョブ ID) ──▶ 中断

MCP コンソール（ウェブコンソール）でツールごとの設定と認証状態を確認できます。コンソール機能の詳細はウェブコンソールを参照してください。

MoAI 自身の MCP サーバーも Claude Code 一般 MCP と同じ遅延ロード原則に従います。ツール定義全体をコンテキストに常時ロードするとコンテキストウィンドウがすぐに埋まるため、普段は短いメタデータだけを置き、実際の呼び出し時にスキーマを読み込みます。

遅延ツールを呼び出すには、まず ToolSearch でスキーマをアクティブコンテキストに読み込む必要があります。

ツールが必要になる ──▶ {スキーマがコンテキストにあるか?}
                           │
                    ┌──────┴──────┐
                    いいえ          はい
                    │              │
            ToolSearch で         ツール呼び出し
            スキーマ先行ロード
                    │
                    └──▶ ツール呼び出し

この手順を飛ばすと、ツール呼び出しは検証エラーで拒否されます。遅延ロードの原理に関する背景説明は Claude Code 一般 MCP 文書の「遅延ロードと Tool Search」節を参照してください。

• Claude Code 一般 MCP — プラットフォーム自身の MCP 統合（USB ポートの比喩、サーバー登録、転送タイプ、/mcp コマンド）
• マルチ LLM バックエンド — Claude × GLM マルチバックエンド運用 · GLM セッションでウェブ検索/照会が z.ai MCP ツールへルーティングされる規則
• クロスモデル監査 — 多重監査者収束メカニズム
• ウェブコンソール — MCP ツールごとの設定と認証表面