Codex CLI の MCPサーバー：追加、設定、認証
MCPサーバーは Codex に新しい道具を渡します — 最新のドキュメント、あなたのデータベース、GitHub リポジトリ。このウォークスルーでは codex mcp add でローカル stdio サーバーを追加し、--url と OAuth でリモートサーバーに切り替え、両者の裏にある config.toml エントリを確認し、サーバーが本当に動くことを証明するチェックを示します。
要点まとめ
- Codex は ~/.codex/config.toml（グローバル）か .codex/config.toml（プロジェクト）から MCPサーバーを読みます。各エントリは [mcp_servers.<name>] テーブルで、ローカル stdio サーバーには command/args、リモートには url を書きます。
- codex mcp add context7 -- npx -y @upstash/context7-mcp ならファイルを触らずに stdio サーバーを追加。codex mcp add <name> --url https://mcp.example.com/mcp ならリモートを登録します。
- リモートサーバーは初回接続時にブラウザで認証し（Codex が Detected OAuth support を表示して同意画面を開きます）、あとから codex mcp login <name> でも可能。
- 検証は TUI 内の /mcp か、シェルの codex mcp list。Codex 0.160.1 はさらに、リモート env 変数つきでリモート stdio サーバーを起動する際に SYSTEMROOT・TEMP・TMP を保持します。
OpenAI Codex + MCP: How to Install MCP Servers in Codex (Step by Step)
チャンネル: Nathan Sebhastian8:48
OpenAI Codex Tutorial #9 - MCP Servers
チャンネル: Net Ninja6:46
How to Add MCP Servers to OpenAI Codex CLI
チャンネル: Snyk9:14
Connect Codex to an MCP server — official documentation
公式ドキュメント: developers.openai.com/codex
このページのすべてのコマンド、ファイルパス、設定キーは公式の Codex MCP ドキュメントに対して検証しています。上の動画がビジュアルと事実のソースです — OAuth 同意画面とデスクトップアプリの MCP メニューも含めて。
スクリーンショットは各制作者に帰属し、該当タイムスタンプへ深リンクしています。顔出しフレームは使用していません。
Codex に MCPサーバーを追加する、ステップごとに
パート 1 — 初めての stdio サーバー
- 1
公式 MCP ドキュメントからサーバーを選ぶ
developers.openai.com/codex/mcp を開きます — Codex 自身のドキュメントに現在のコマンド構文があり、CLI と IDE 拡張はこの設定を共有します。ドキュメントには試す価値のある既製サーバーが並びます：最新のライブラリドキュメントのための Context7、Figma、GitHub など。MCPサーバーは数百ありますが、最初のテストは Context7 のような読み取り専用が安全です。
公式の Connect Codex to an MCP server ページ — codex mcp add の構文と、そのままコピーできる Context7 の例付き。0:20 から視聴 - 2
codex mcp add でインストール
例をコピーしてターミナルで実行：codex mcp add context7 -- npx -y @upstash/context7-mcp。ダブルダッシュ以降がサーバープロセスを起動するコマンドです。Codex は「Added global MCP server 'context7'」と返答 — global とはユーザーレベルの設定に入った、つまり全プロジェクトで使えるということ。
1 コマンド、ファイル編集なし：CLI がグローバル設定への追加を確認してくれます。0:45 から視聴 - 3
CLI が config.toml に書いたものを見る
codex mcp add は ~/.codex/config.toml のジェネレータにすぎません。ファイルを開けば command = "npx" と args = ["-y", "@upstash/context7-mcp"] を伴う [mcp_servers.context7] が見つかります。エントリは手書きも可能：API キー用の env テーブルを足したり、遅いサーバーのために startup_timeout_sec（デフォルト 10）や tool_timeout_sec（デフォルト 60）を設定したり。手編集こそ、ソースカードの Snyk と Net Ninja の動画が取っている経路です。
- 4
Codex を起動して /mcp で検証
プロジェクトで codex を起動し、/mcp と打ちます。MCP Tools パネルには設定済みサーバーがすべて、ステータス・起動コマンド・公開ツールつきで並び — Context7 なら query_docs と resolve-library-id。ここに何か欠けていたら、エントリが違うファイルに入ったか、起動に失敗しています。
Codex TUI の /mcp パネル：context7 が有効で、2 つのツールが名前一覧されています。1:05 から視聴
パート 2 — 使ってからリモートへ
- 5
サーバーを本当に使うプロンプトを書く
MCP ツールは必要なときに呼ばれるので、それが必要なお願いをします：「Context7 で現在の Tailwind CSS セットアップドキュメントを確認して」。Codex はライブラリを解決し、MCPサーバー経由でドキュメントを引き、出典つきで答えます。ツール呼び出しが流れるのを見れば、サーバーが端から端まで動いている証拠になります。
Codex の答えには、MCPサーバー経由で引いた Context7 ドキュメントの正確な URL が引用されています。1:30 から視聴 - 6
--url でリモートサーバーを追加
多くのプロバイダは MCPサーバーをリモートでもホストしています — ローカルプロセスも npx も不要。codex mcp add context7 --url https://mcp.context7.com/mcp で登録すると、Codex は OAuth 対応を自動検出し、「Detected OAuth support. Starting OAuth flow...」と表示してブラウザで認証を開きます。config.toml のエントリは [mcp_servers.context7] の下に url = "https://mcp.context7.com/mcp" があるだけ。
ひとつのターミナルに収まったリモートの全流れ：--url での追加、OAuth 検出、認可 URL、Successfully logged in。2:22 から視聴 - 7
OAuth 同意画面を承認
ブラウザは Codex がプロバイダの代理であなたのアカウントにアクセスしていいか尋ねます。要求スコープを確認して Allow を押せば、ターミナルが「Successfully logged in」と確認。OAuth フローを載せないサーバーは codex mcp login <name> で別途認証、トークンベースのサーバーは bearer_token_env_var で環境変数を指します。
Context7 の同意画面：Codex が要求するスコープを確認して Allow。2:02 から視聴 - 8
.codex/config.toml でサーバーを 1 プロジェクトに限定
1 つのリポジトリでしか意味を持たないサーバー — データベースと対話する stdio サーバー DBHub など — はプロジェクト設定へ。リポジトリに .codex フォルダを作り、[mcp_servers.dbhub] エントリ入りの config.toml を足し、接続文字列は --dsn 引数で渡します（ドキュメントの Postgres 例を MySQL など自分の環境に合わせて調整）。コミットすればチーム全員が同じサーバーを得られます。読み込むにはフォルダが trusted プロジェクトである必要があります。
プロジェクトの .codex/config.toml：DBHub が stdio で動き、args にリポジトリのデータベース DSN。3:30 から視聴
パート 3 — 本物のサーバーと日々の運用
- 9
MCP ツール経由でデータベースに問い合わせ
DBHub を設定したら、Codex にデータベースを尋ねます：「Petco データベースを見つけてテーブルを説明して」、続いて「一番売れている商品は？」。Codex はサーバーの describe_table と execute_sql ツールを呼び、SQL 実行前に許可を求め、実データの数字で答えます。バックエンド作業中のスキーマデバッグとデータ検証は、これが最速です。
Codex は dbhub の execute_sql ツールを実行し、一番売れている商品とその売上で答えました。4:40 から視聴 - 10
リモート MCPサーバーで GitHub に接続
github/github-mcp-server の README が Codex の設定を文書化しています：url = "https://api.githubcopilot.com/mcp/" を伴う [mcp_servers.github] エントリを足し、認証は OAuth か、個人アクセストークンを環境変数としてエクスポート（GitHub Settings → Developer settings で Administration と Contents を許可した fine-grained PAT を作成）。このサーバーや Figma MCPサーバーのようなリモートファーストはステップ 6 と同じ型です。
GitHub の MCPサーバーインストールガイド：Codex CLI エントリと OAuth/PAT 認証の注記。5:22 から視聴 - 11
再起動してツールを実戦投入
codex を再起動してバナーを見ます：「Starting servers (0/3): context7, dbhub, github」。もう「openai/codex リポジトリを私のアカウントに fork して」のような 1 命令で十分 — Codex は GitHub の fork ツールを選び、承認を求め、実行します。タスクごとのセットアップはもう不要：道具は今日から毎セッションの一部です。
- 12
codex mcp list とデスクトップアプリで管理
codex mcp list はシェルから設定済みサーバーをすべて表示。削除は config.toml からそのブロックを消し、確認のためコマンドを再実行するだけ。デスクトップアプリと IDE 拡張は同じ ~/.codex/config.toml を読むため、ここで入れたサーバーはデスクトップアプリの Settings、MCP servers ページに on/off トグルつきで現れます。
Codex デスクトップアプリの MCP servers 設定：トグルつきの context7、dbhub、github と、おすすめサーバー一覧。7:30 から視聴
Codex のローカル stdio vs リモート MCPサーバー
両者とも同じ [mcp_servers.*] テーブルに住み、同じ /mcp パネルに現れます — 違いはサーバーがどこで動き、どう認証するか。プロジェクトごとではなく、サーバーごとに選びましょう。
- 1ローカル stdio：Codex が command と args — 典型的には npx かバイナリ — で自分でプロセスを起動します。手元のマシンで動くので、開発データベースのような localhost サービスに届きます（ウォークスルーで DBHub が MySQL に問い合わせたのがまさにそれ）が、ランタイムと更新は自分で提供します。
- 2リモート：Codex はホストされた url と streamable HTTP で話します。維持すべきプロセスがなく、認証は一元化 — デフォルトは OAuth、トークンベースなら bearer_token_env_var と http_headers。ドキュメント自身の例は url = "https://mcp.figma.com/mcp" の [mcp_servers.figma] です。
- 3リモート実行 stdio：実験的な中間地帯。stdio エントリに experimental_environment = "remote" を設定すると、実行がリモートエグゼキュータに移り、env_vars がどの変数が旅するか決めます — source = "remote" マークのエントリも含む。Codex 0.160.1 が強化したのはこの経路です。
- 4スコープ：codex mcp add は常にグローバルの ~/.codex/config.toml に書きます。プロジェクト固有のサーバーはリポジトリ内の .codex/config.toml へ（trusted プロジェクトのみ）。どこでも欲しい道具はグローバル、環境固有の認証情報を運ぶものはプロジェクトへ。
- 5両方に効くコントロール：遅いサーバーのための startup_timeout_sec（デフォルト 10）と tool_timeout_sec（デフォルト 60）、Codex が呼べるものを許可リスト化する enabled/disabled_tools、そしてサーバーが必ず立ち上がるべきなら required = true。
実用的なデフォルト：Context7 のような読み取り専用ドキュメントサーバーはグローバルでよく、認証情報やデータに触れるもの — DBHub、PAT つき GitHub — は、リポジトリと一緒にレビュー・失効できるプロジェクト設定に属します。
設定したのに動かない：いつもの容疑者たち
Codex での MCP 失敗の大半は、スコープ、タイムアウト、認証 — この順です。サーバー自体に触れる前に、このリストをなぞりましょう。
- 1/mcp にサーバーが出ない：どのファイルを編集したか確認。グローバルは ~/.codex/config.toml、プロジェクトは .codex/config.toml で trusted プロジェクト限定。シェルから codex mcp list を実行すれば、Codex が実際に見えているものが分かります。
- 2起動時にタイムアウト：startup_timeout_sec のデフォルトは 10 秒で、大きなパッケージの npx コールドダウンロードは容易に超えます。パッケージを事前インストールするか、エントリの startup_timeout_sec を上げましょう。
- 3ツール呼び出しが 401/403 で失敗：認証情報がないか古いです。OAuth サーバーなら codex mcp login <name>、あるいは bearer_token_env_var を設定して変数をエクスポート。直れば /mcp はサーバーを再び enabled と表示します。
- 4リモート stdio サーバーが Windows 関連の奇妙なエラーでクラッシュ：0.160.1 未満では、明示的に設定されたリモート環境変数つきでリモート stdio MCPサーバーを起動すると SYSTEMROOT・TEMP・TMP が落ちて、Windows エグゼキュータの起動環境が壊れることがありました。0.160.1 以降へ更新を。
- 5サーバーは立つのに答えがおかしい・空：多くのホスト型サーバーは OAuth の上でも独自の API キーを欲しがります — 例えば Context7 は env 経由の API キーを要求。プロバイダのドキュメントで正確な env 名を確認し、エントリの env テーブルに足しましょう。
デバッグ中に効く 2 つのレバー：依存するサーバーに required = true を設定すれば Codex が黙って起動せず、enabled = false なら設定を消さずに 1 台オフ。