PR

Codex CLIでModel Context Protocol (MCP)を有効化する完全ガイド

2025.09.16

Codex CLIは、Model Context Protocol（MCP）対応サーバーと連携することで、コマンドラインから投稿管理や画像生成などの外部ツールを直接呼び出せるようになります。本記事は、ローカル・リモートのどちらのMCPサーバーを扱う場合でも、初心者が迷わずに設定できるように手順を整理しました。すべての操作は順番に進めれば問題ありません。

Model Context Protocol (MCP) とは

MCPは、LLMエージェント（Codex CLI、Claude、Cursorなど）が外部ツールと安全に通信するための共通規格です。WordPress投稿サーバーや画像生成サーバーのような「MCPサーバー」を登録しておけば、Codex CLIが会話の中でそれらの機能を呼び出せます。基本仕様と最新情報は、Anthropic公式MCPサイトおよびOpenAIのCodex CLIドキュメントを参照してください。

準備チェックリスト（ローカル・リモート共通）

  • Codex CLIが使えること: npm install -g @openai/codex または Homebrew で導入後、codex --version で確認します。
  • 設定ファイルを編集できること: ~/.codex/config.toml と、MCPクライアント（Cursorなど）が読む mcp.json を開ける状態にしておきます。
  • サーバー情報を把握していること: ローカルで動かすサーバーなら起動コマンドとパス、リモートAPIなら接続先URLと認証情報（APIキーやユーザー名/アプリケーションパスワード）が必要です。
  • 環境変数の渡し方を決めること: macOS/Linuxなら~/.zshrcなどに書く、direnvを使う、Codexのプロファイルに設定する、といった方法のうち使いやすいものを選びます。

ステップ1: mcp.jsonでサーバー定義を登録する

MCPクライアントが参照するmcp.jsonには、サーバー名・起動コマンド・必要な環境変数をまとめて記述します。ローカルでNodeベースのWordPressサーバーを起動し、リモートAPIで画像生成を呼び出す例は以下の通りです。

{
  "version": "1",
  "servers": {
    "wordpress": {
      "command": "npx",
      "args": ["@nightmustend/wp-mcp", "start"],
      "env": {
        "WP_BASE_URL": "https://nightmustend.net",
        "WP_USER": "your_user",
        "WP_APP_PASS": "your_app_password"
      }
    },
    "imagen": {
      "command": "python",
      "args": ["scripts/generate_thumbnails.py"],
      "env": {
        "IMAGEN_API_KEY": "your_api_key"
      }
    }
  }
}

ポイント:

  • サーバーごとに一つのオブジェクトを定義します。
  • command は実行ファイル、args は引数です。ローカルサーバーならpythonやnode、リモートAPIラッパーならnpxなどに置き換えます。
  • env には、APIキーやログイン情報、接続先URLなどを記載します。ここに平文を置きたくない場合は、シェル側で設定した環境変数を参照するように変更してください。

ステップ2: ~/.codex/config.toml に mcp_servers を宣言する

公式ドキュメントの形式に倣い、Codex CLIが読み込む設定ファイルへサーバーを登録します。基本形は次のTOMLスニペットです。

# ~/.codex/config.toml
# IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`.
[mcp_servers.server-name]
command = "npx"
args = ["-y", "mcp-server"]
env = { "API_KEY" = "value" }

server-name を wordpress や imagen などの実際のサーバー名に置き換え、command/args/env を mcp.json の内容と揃えてください。複数サーバーを登録する際は、このセクションをサーバー数ぶん追加します。

例: WordPressサーバーを登録する場合（ローカル・リモート共通）

[mcp_servers.wordpress]
command = "npx"
args = ["@nightmustend/wp-mcp", "start"]
env = { "WP_BASE_URL" = "https://nightmustend.net" }

ステップ3: Codex CLIで接続動作を確かめる

  1. codex を起動し、初回のみログインを済ませます。
  2. 起動ログに [MCP] の初期化メッセージが出るか確認します。
  3. tools と入力し、登録したサーバー名（wordpress、imagen など）が表示されれば成功です。
  4. 試しに wordpress.listPosts や画像生成サーバーのサンプルツールを実行し、結果が返ってくるかを確認します。

リモートサーバーの場合は、APIキーの権限やIP制限がないかも確認してください。ローカルサーバーなら、プロセスが起動しているかどうか（ポート占有・仮想環境の有無など）を合わせて確認します。

Codex CLIをMCPサーバーとして呼び出す方法

Codex自身をMCPサーバーとして起動すると、別のエージェントやInspectorからCodexをツール化できます。手順の詳細はCodex公式ドキュメントも参照してください。

  1. Inspectorを起動: npx @modelcontextprotocol/inspector codex mcp を実行すると、Inspector経由でCodex MCPサーバーが立ち上がります。
  2. 利用可能ツールの確認: Inspectorから tools/list を送ると、codex（新規セッション開始）と codex-reply（既存セッション継続）の2ツールが表示されます。
  3. プロパティ指定: codex ツールには prompt（必須）のほか、approval-policy（untrusted/on-failure/never）や sandbox（workspace-write など）を渡せます。codex-reply では conversationId と prompt を指定します。
  4. タイムアウト調整: Codexは処理に時間がかかることがあるため、Inspector設定の Request/Total timeout を 600000ms（10分）程度に拡張しておくと安定します。
  5. ワークスペースとの連携: Codex MCPサーバーは codex CLIの設定（プロフィール・sandbox・承認ポリシー）を引き継ぐため、通常の対話と同様にコマンド実行が可能です。

この仕組みを使えば、他のMCP対応クライアントからCodexを「外部ツール」として再利用でき、マルチエージェント連携や自動化パイプラインの一部に組み込みやすくなります。

クライアント側の mcpServers 設定例

Inspector や Codex CLI 以外のMCPクライアントからCodex MCPサーバーを登録する際は、以下のJSONを ~/.cursor/mcp.json などの設定ファイルに追記します。mcpServers キーはCamelCaseなので、Codex CLIの ~/.codex/config.toml に記載する [mcp_servers] と書式が異なる点に注意してください。

{
    "mcpServers": {
      "codex": {
        "type": "stdio",
        "command": "codex",
        "args": ["mcp"]
      }
    }
  }

よくある構成パターン

  • すべてローカル: WordPress開発用のローカル環境にMCPサーバーを立て、テスト用の記事を投稿する。
  • 一部リモート: WordPressは本番サイトに接続し、画像生成はローカルGPUサーバーで行う。
  • 完全リモート: 外部SaaSが提供するMCPサーバー（例: SaaS型WordPress運用、クラウドAI画像生成）を呼び出す。認証情報の保管を厳重に行う必要があります。

Codex v0.36.0で追加された codex mcp add コマンド

2025年9月16日公開の Codex v0.36.0 で、Claude CLIの claude mcp add と同じ書式を備えた codex mcp add サブコマンドが搭載されました。Codex CLIから直接 ~/.codex/config.toml の [mcp_servers] セクションを更新できるため、手動編集を減らし設定ミスを防げます。

使い方は codex mcp add <name> [--env KEY=VALUE ...] <command> [args...] という形です。例えばWordPress MCPサーバーを追加する場合は次のように実行します。

codex mcp add wordpress --env WP_BASE_URL=https://nightmustend.net --env WP_USER=your_user --env WP_APP_PASS=your_app_password npx @nightmustend/wp-mcp start

コマンドは即座に設定を書き込み、codex mcp list や codex mcp get wordpress で内容を確認できます。既存エントリを上書きする場合は同じサーバー名で再実行し、不要になったものは codex mcp remove <name> で削除可能です。MCPサーバーの追加や整理をCLI内で完結できる点が従来の手作業との差分です。

トラブルシューティングと安全運用

  • サーバーが表示されない: mcp.json のキーと [mcp_servers.*] のセクション名が一致しているか、スペルを再確認します。
  • 起動エラーが出る: command で指定した実行ファイルがPATHにあるか確認します。仮想環境内コマンドの場合はフルパスで指定すると確実です。
  • 認証エラー: APIキーの権限、WordPressアプリケーションパスワードの有効性、2段階認証の設定などを再チェックします。
  • 危険なコマンド実行が心配: Codex CLIの承認フローを活用し、approval-policy を untrusted や on-failure に設定しておくと安心です。
  • ログ確認: tail -F ~/.codex/log/codex-tui.log を別ターミナルで開き、MCP関連のログを追うと原因究明が楽になります。

まとめ

MCPサーバーをCodex CLIに登録する作業は、mcp.json と ~/.codex/config.toml の2ファイルを整えるだけです。ローカル・リモートのどちらのサーバーでも、コマンド・引数・環境変数の指定を正しく行えば問題なく連携できます。設定後はツール一覧で接続を確認し、安全な承認ポリシーとログ監視を組み合わせながら、日々のワークフローにMCP連携を取り入れてみてください。Codex自身をMCPサーバーとして呼び出せば、複数エージェント間のハブとしても活用できます。

スポンサーリンク
タイトルとURLをコピーしました