Codex CLI × MCP：カスタムツール・APIの接続方法と活用パターン

この章の要点

Codex CLI は MCP（Model Context Protocol）経由で外部ツール・API・データベースに接続できます。設定は ~/.codex/config.toml または .codex/config.toml の [mcp_servers.<name>] テーブルに書きます。

• トランスポートは stdio（command キーあり）と Streamable HTTP（url キーあり）の 2 種類
• HTTP のヘッダは http_headers / env_http_headers / bearer_token_env_var で指定
• enabled_tools / disabled_tools で個別ツールの公開可否を制御
• codex mcp でサーバの追加・ログイン・一覧、codex mcp-server で Codex 自体を MCP（stdio）として公開
• グローバル OAuth は mcp_oauth_callback_port / mcp_oauth_callback_url / mcp_oauth_credentials_store で管理

---

MCP とは

LLM ツール拡張の業界標準仕様で、外部のサーバが「ツール」「リソース」を公開し、Codex 側がそれを呼び出すクライアントになります。Codex CLI は標準で stdio と Streamable HTTP の双方をサポートします。

---

公式仕様の概要

公式の /codex/mcp と config-reference では、[mcp_servers.<name>] の各キー（stdio 系・HTTP 系・共通系）、トランスポート判定、グローバル OAuth 設定、codex mcp サブコマンドが定義されています。

---

使い方

[mcp_servers.<name>] のキー一覧

区分	キー	説明
stdio	command（必須）	サーバを起動するコマンド
stdio	args	コマンド引数の配列
stdio	cwd	作業ディレクトリ
stdio	env	サーバプロセスに渡す環境変数のマップ
stdio	env_vars	ホスト環境からホワイトリスト渡しする変数名（source = "local" / "remote" 指定可）
HTTP	url（必須）	Streamable HTTP エンドポイント
HTTP	http_headers	静的 HTTP ヘッダ
HTTP	env_http_headers	環境変数で値を埋めるヘッダ
HTTP	bearer_token_env_var	Bearer トークンを取得する環境変数名
共通	enabled	false でこのサーバを無効化
共通	required	true で初期化失敗時に Codex 起動を中止
共通	startup_timeout_sec	起動タイムアウト（既定 10 秒）
共通	tool_timeout_sec	ツール 1 回の実行タイムアウト（既定 60 秒）
共通	enabled_tools	公開を許可するツール名の配列
共通	disabled_tools	公開を拒否するツール名の配列（enabled_tools の後に適用）
共通	experimental_environment	実行配置の指定（local または remote）
OAuth	scopes	認証時に要求するスコープ
OAuth	oauth_resource	RFC 8707 の OAuth resource パラメータ

トランスポートは「command があれば stdio、url があれば Streamable HTTP」で自動判別されます。type キーは指定しません。

グローバル OAuth 設定

# ~/.codex/config.toml
mcp_oauth_callback_port      = 5555           # 既定はエフェメラルポート
mcp_oauth_callback_url       = "https://devbox.example.internal/callback"
mcp_oauth_credentials_store  = "auto"         # auto | file | keyring

stdio サーバの設定例

# ~/.codex/config.toml

[mcp_servers.filesystem]
command = "npx"
args = ["@modelcontextprotocol/server-filesystem", "/Users/user/Projects"]

[mcp_servers.postgres]
command = "npx"
args = ["@modelcontextprotocol/server-postgres"]
env = { DATABASE_URL = "postgresql://user:password@localhost:5432/mydb" }
enabled_tools = ["query", "list_tables", "describe_table"]

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
env = { PLAYWRIGHT_HEADLESS = "true" }

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]   # ホストの LOCAL_TOKEN を引き継ぐ

Streamable HTTP サーバの設定例

# GitHub MCP（HTTP）
[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_TOKEN"   # Authorization: Bearer ${GITHUB_TOKEN}

# 静的ヘッダと環境変数ヘッダの併用例
[mcp_servers.internal-docs]
url = "https://internal-mcp.example.com/mcp"
http_headers     = { "X-Tenant" = "shogo-works" }
env_http_headers = { "Authorization" = "INTERNAL_MCP_TOKEN" }   # 値を環境変数から取得
startup_timeout_sec = 20
tool_timeout_sec    = 90
required = true

プロジェクト共有

.codex/config.toml を Git 管理すれば、チーム全員が同じ MCP サーバ構成で Codex を使えます。シークレットは TOML には書かず、bearer_token_env_var か env_http_headers で参照する環境変数名だけを定義しておくのが定石です。

個別ツールの絞り込み

破壊的なツールだけ無効化したい場合は disabled_tools を使います。

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_TOKEN"
disabled_tools = ["delete_repository", "merge_pull_request"]

enabled_tools を指定すると、列挙したものだけが Codex から呼べます（disabled_tools は enabled_tools の後に適用される）。

codex mcp サブコマンド

外部 MCP サーバを CLI から管理するサブコマンド群です。OAuth が必要なサーバへのログインや一覧表示に使います。

codex mcp --help    # サブコマンド一覧
codex mcp add ...   # サーバ追加（対話）
codex mcp login ... # OAuth ログイン

Codex CLI 自体を MCP サーバとして公開する

codex mcp-server を起動すると、Claude Desktop や Cursor などの他クライアントから Codex の機能を呼び出せます。トランスポートは stdio です。

codex mcp-server

Claude Desktop 側の設定例:

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "codex": {
      "command": "codex",
      "args": ["mcp-server"]
    }
  }
}

提供される MCP ツール：

• codex … 新しい Codex セッションをタスク委譲で起動
• codex-reply … 既存の Codex セッションへ続きを依頼

---

自作 MCP サーバの接続例

社内 API・独自データベースを Codex に接続する場合は、MCP SDK でサーバを実装します。

# /path/to/deploy-mcp-server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("社内デプロイメント API")

@mcp.tool()
def get_deployment_status(service: str) -> str:
    """指定したサービスのデプロイ状況を取得する"""
    return fetch_from_deploy_api(f"/services/{service}/status")

@mcp.tool()
def list_services() -> list[str]:
    """デプロイ可能なサービス一覧を返す"""
    return fetch_from_deploy_api("/services")

if __name__ == "__main__":
    mcp.run()

# config.toml への接続設定（stdio）
[mcp_servers.internal-deploy]
command = "python"
args    = ["/path/to/deploy-mcp-server.py"]

---

Claude Code の MCP との比較

観点	Codex CLI	Claude Code
設定ファイル	config.toml（TOML）	.mcp.json（JSON）または settings.json
トランスポート	stdio・Streamable HTTP	stdio・HTTP・SSE
公式レジストリ	未提供（2026-05 時点）	あり（api.anthropic.com/mcp-registry/v0/servers）
MCP サーバとして公開	codex mcp-server（stdio）	claude mcp serve
プロジェクト共有	.codex/config.toml を Git 管理	.mcp.json を Git 管理
ツール絞り込み	enabled_tools / disabled_tools	設定 UI / Hooks

---

注意点・セキュリティ観点

シークレットを TOML に直書きしない http_headers にトークンを直書きすると Git に含まれた時点で流出します。bearer_token_env_var か env_http_headers で「環境変数名」を渡してください。

ネットワークはサンドボックス側で許可が必要 Streamable HTTP の MCP サーバへ接続するには、config.toml 側のネットワーク許可（[permissions.<name>.network.domains]）でドメインを allow に設定しておく必要があります（詳細は「承認モード&サンドボックス」章）。

required = true の使い分け 業務上必須のサーバは required = true にしておくと、起動失敗時に Codex 全体を停止できます。補助的なサーバまで required にすると、不安定な MCP が原因で Codex が起動しなくなる場合があります。

enabled_tools / disabled_tools で破壊的ツールを抑える GitHub MCP の merge_pull_request のように取り消せない操作は、明示的に disabled_tools に入れておくと事故を防げます。

stdio サーバが起動しないときは単体実行で確認

npx @modelcontextprotocol/server-filesystem /tmp 2>&1

依存パッケージや環境変数の不足はここで切り分けられます。

Codex を MCP として公開するときは承認設定を確認 codex mcp-server で公開した Codex は、別クライアントの指示でファイル変更やコマンド実行を行います。サンドボックス・承認ポリシーは config.toml で適切に絞っておいてください。

---

一次ソース

• MCP integration — Codex Docs
• Configuration reference — Codex Docs
• Use Codex with the Agents SDK — Codex Docs
• Model Context Protocol 公式サイト
• openai/codex リポジトリ（mcp-server クレート）