Codex MCP Diagnostics And Plugin Loading

この文書は Codex 0.123.0 以降の MCP 診断と plugin MCP loading の運用メモ。 Claude Code 側の claude mcp、.claude/mcp.json、hook type: "mcp_tool" の話とは混ぜない。

目的

Codex の /mcp は、普段の軽量確認に使う。 接続済み server の概要だけを素早く見たい時の入口。

Codex の /mcp verbose は、困った時だけ使う。 diagnostics、resources、resource templates まで確認する詳細診断の入口。

この分け方にすると、通常の確認は速いまま、MCP server が見えない・resources が出ない・template が読めない時だけ詳しく掘れる。

使い分け

状況	使うもの	見るポイント
MCP server が登録されているかだけ見たい	/mcp	server 名、接続状態、ざっくりした有効 / 無効
server が表示されない	/mcp verbose	diagnostics の起動エラー、認証エラー、設定ファイル読み込み
tool は見えるが resource が見えない	/mcp verbose	resources の有無、resource templates の有無
plugin の .mcp.json が読まれているか怪しい	/mcp verbose	plugin MCP loading の対象 server と diagnostics

診断手順

1. まず Codex TUI で /mcp を実行する。
2. 期待した server が見えない、または状態が分からない時だけ /mcp verbose を実行する。
3. diagnostics で起動失敗、認証失敗、設定ファイル parse error がないか見る。
4. resources で server が公開している resource が見えているか見る。
5. resource templates で repo://\{owner\}/\{name\} のような template が公開されているか見る。
6. plugin 由来の MCP server だけが見えない場合は、plugin の .mcp.json の形を確認する。

.mcp.json の対応形式

Codex 0.123.0 以降の plugin MCP loading は、plugin 内の .mcp.json について次の 2 形式を受け取れる。

mcpServers 形式

{
  "mcpServers": {
    "docs": {
      "command": "node",
      "args": ["server.js"]
    }
  }
}

top-level server map 形式

{
  "docs": {
    "command": "node",
    "args": ["server.js"]
  }
}

どちらも plugin MCP loading の入力として扱える。 新規で書く場合は、他の AI tool と共有しやすい mcpServers 形式を優先する。 既存 plugin が top-level server map 形式なら、無理に書き換えず Codex 側の読み込み改善を利用する。

Claude Code 側と混ぜないこと

この文書の対象は Codex の plugin MCP loading と Codex TUI の /mcp / /mcp verbose。

Claude Code 側の設定や診断とは入口が違う。

領域	入口	この文書で扱うか
Codex TUI の MCP 診断	/mcp, /mcp verbose	扱う
Codex plugin の .mcp.json loading	plugin 内 .mcp.json	扱う
Claude Code CLI の MCP 管理	claude mcp ...	扱わない
Claude Code project MCP 設定	.claude/mcp.json	扱わない
Claude Code hook の type: "mcp_tool"	hooks.json	53.1.2 の別判断として扱う

注意点

• /mcp verbose は詳細診断用。毎回の通常確認では /mcp を使う。
• .mcp.json には secret を直接書かない。必要な値は環境変数や管理された credential store に寄せる。
• resources と resource templates が空でも、server によっては正常な場合がある。tool だけを提供する MCP server もある。
• plugin .mcp.json の読み込み改善は Codex 側の話。Claude Code の .claude/mcp.json や managed settings の仕様変更として扱わない。