Codex MCP セットアップ: Codex CLI と IDE 拡張にリモート MCP サーバーを追加する

Codex MCP セットアップ: Codex CLI と IDE 拡張にリモート MCP サーバーを追加する
Unif Agents team
Unif Agents team

OpenAI Codex で MCP を設定する手順。codex mcp add、config.toml の書き方、codex mcp login による OAuth、ツール読み込みの確認まで。

要点: Codex は MCP サーバーを ~/.codex/config.toml から読み込み、CLI がそのファイルを代わりに編集してくれます。リモートサーバーならコマンド 1 つで足ります。codex mcp add unifapi --url https://mcp.unifapi.com です。codex mcp list で登録されたことを確認し、初回利用時に OAuth のサインインが開かなかった場合は codex mcp login unifapi を実行します。Codex IDE 拡張も同じファイルを読むので、一度追加したサーバーはターミナルでも VS Code でも使えます。

OpenAI のコーディングエージェントである Codex は、CLI と IDE 拡張で Model Context Protocol に対応しています。設定は TOML ファイル 1 つなので、セットアップしやすいクライアントの 1 つであると同時に、気づきにくい間違いを起こしやすいクライアントの 1 つでもあります。誤ったテーブルに追加したサーバーや、URL として宣言した stdio サーバーは、ツールを求めるまで黙って失敗します。このガイドでは UnifAPI MCP サーバー（https://mcp.unifapi.com、ソーシャルプラットフォームと SEO スタックのライブな公開データ）を実例として使いますが、手順はどのリモートサーバーでも同じです。

必要なもの

  • Codex CLI（npm install -g @openai/codex または brew install codex）、あるいは VS Code、Cursor、Windsurf 用の Codex 拡張。どちらも ~/.codex/config.toml を読み込みます。
  • サインイン済みの Codex（codex login）。MCP は ChatGPT でのサインインでも API キーでも動作します。
  • UnifAPI の場合: OAuth のプロンプトが開いたときのための UnifAPI アカウントと、最初の課金対象の呼び出しの前にワークスペースのクレジット。カタログの閲覧は無料です。

codex mcp add でリモートサーバーを追加する

リモート（streamable HTTP）サーバーは URL です。次のように登録します。

codex mcp add unifapi --url https://mcp.unifapi.com

書き込まれたことを確認します。

codex mcp list
codex mcp get unifapi

codex mcp list は、設定済みのすべてのサーバーをトランスポートと認証状態とともに表示します。OAuth で保護されたサーバーとのセッションを Codex が初めて開始するとき、ブラウザでサインインが開きます。開かなかった場合や、ブラウザのないマシンを使っている場合は、自分で起動します。

codex mcp login unifapi
# headless: print the URL instead of opening a browser
codex mcp login unifapi --no-browser

OAuth ログインは streamable HTTP サーバーに対してのみ提供され、stdio サーバーにはサインインの手順がありません。トークンはキーリング（または Codex がフォールバックとして使う認証情報ファイル）に保存され、セッションをまたいで再利用されます。codex mcp logout unifapi でトークンを消去し、codex mcp remove unifapi でサーバーを削除します。

その裏にある config.toml

CLI が書き込んだ内容はすべて、[mcp_servers.<name>] の下のプレーンな TOML です。UnifAPI のエントリは 1 行です。

[mcp_servers.unifapi]
url = "https://mcp.unifapi.com"

ほかのリモートサーバーでは、2 つのオプションフィールドが重要になります。

[mcp_servers.example]
url = "https://mcp.example.com"
# Read a static bearer token from this environment variable instead of OAuth
bearer_token_env_var = "EXAMPLE_TOKEN"
# Extra headers, literal or sourced from the environment
http_headers = { "X-Client" = "codex" }
env_http_headers = { "X-Tenant" = "EXAMPLE_TENANT" }

UnifAPI はワークスペースの API キーを使った bearer_token_env_var も受け付けますが、推奨は OAuth です。dotfile に貼り付けるものがなく、トークンは読み取り専用です。

ローカルの stdio サーバーは url の代わりに command と args を使います。2 つの形は排他的で、混在させたテーブルは拒否されます。

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Projects"]
env = { "NODE_OPTIONS" = "--max-old-space-size=512" }

プロジェクトごとのサーバー

Codex は、プロジェクトレベルの .codex/config.toml（リポジトリのルートにあり、プロジェクトが信頼されている場合）をホームの設定の上にマージします。1 つのリポジトリだけが必要とするサーバーはそこに置き、ファイルをコミットすればチームメイトも同じツールを使えます。codex mcp login はマージ後の設定から名前を解決するので、プロジェクトスコープの OAuth サーバーも同じ方法でサインインできます。

ツールの読み込みを確認する

プロジェクトでセッションを開始し、サーバーでしか答えられないことを頼みます。

unifapi MCP サーバーを使って、Reddit で利用できるオペレーションを一覧してください。

回答の前に list_operations へのツール呼び出しが表示されるはずです。IDE 拡張では、MCP サーバーとそのツールが拡張の設定パネルに一覧表示されます。そこで赤いステータスになっているサーバーは、たいてい OAuth トークンがない（codex mcp login）か URL が間違っている（codex mcp get）ことを意味します。

承認モード（codex --ask-for-approval、または IDE で選んだモード）によっては、Codex がツール呼び出しのたびに確認を求めることがあります。UnifAPI のような読み取り専用サーバーなら、セッション中は呼び出しを許可しても安全です。呼び出しで消費されうるのはワークスペースのクレジットだけで、get_operation が call_api の実行前にレコードあたりの価格を示します。

クレジットに値する最初のタスク

UnifAPI の MCP サーバーは、大きなカタログを 3 つのツールで公開しています。発見用の list_operations、スキーマと呼び出し例を得る get_operation、そして実行する call_api です。Codex はこの形を得意としています。コマンドを調べ、ヘルプを読み、実行する、という CLI に対して使うのと同じループだからです。範囲を絞った最初のプロンプトの例です。

unifapi MCP ツールを使って、「OpenAI Developers」で見つかる X アカウントの最新の公開投稿 20 件を取得し、投稿、いいね数、リポスト数、1 行のトピックを表にしてください。call_api の前に list_operations と get_operation を呼び出してください。

課金は公開データのレコード 1 件ごとに、ワークスペースのクレジットで行われます（1 クレジット $0.001。ほとんどのレコードは 1 クレジットで、より高い最低クレジットはカタログに公開されています）。モデルトークンは OpenAI のプランで消費されます。新しいワークスペースには初回チャージまでクレジットがなく、初回チャージには一回限りのボーナスが付くので、最初の call_api の前に UnifAPI コンソールで一度チャージしてください。

仕事の形をした作業には、プラットフォーム Agent と SEO Agent が、Codex 向けのすぐ使えるプロンプトと必要になるオペレーションの一覧を提供します。

トラブルシューティング

症状対処法
codex mcp list にサーバーは出るがツールが現れない新しいセッションを開始する。サーバーはセッション開始時に読み込まれる。IDE ではウィンドウを再読み込みする
「OAuth login is only supported for streamable HTTP servers」テーブルに url ではなく command がある。stdio サーバーにはログインの手順がない
ブラウザでのサインインが完了しないcodex mcp login unifapi --no-browser を実行し、表示された URL を任意のブラウザで開き、コールバックをターミナルに貼り戻す
call_api が insufficient_credits を返すワークスペースにまだクレジットがない。コンソールで一度チャージして同じプロンプトを再実行する
あるリポジトリだけでサーバーが消えるプロジェクトの .codex/config.toml がホームの設定を上書きしている。codex mcp get <name> でエントリの出所のファイルが分かる
ツール呼び出しが拒否される承認モードがブロックしている。セッション中は承認するか、このプロジェクトのモードを緩める

確認したソース

2026 年 10 月 14 日に、Codex CLI の MCP 設定リファレンスと現行リリースの codex mcp サブコマンド（add、list、get、login、logout、remove）、および Codex MCP に関する OpenAI 開発者ドキュメント に照らして執筆しました。config.toml のフィールド名は CLI 自身のスキーマから取っています。

次に読むべきもの

MCP セットアップ - すべてのクライアント向けのホスト型コネクタの手順。

Claude に MCP サーバーを追加する方法 - コネクタ、claude_desktop_config.json、claude mcp add。

Cursor MCP セットアップ - mcp.json とワンクリックインストールリンク。

MCP カタログツールの設計 - サーバーがエンドポイントごとに 1 つではなく 3 つのツールを公開する理由。