Codex で最初の MCP サーバーを接続する方法(2026)
Codex は MCP クライアントです。サーバーモードはありません。サーバーを追加する最速の方法は、CLI で codex mcp add <name> -- <command> を実行するか、Desktop アプリの Settings → MCP servers → Add server、または IDE 拡張機能のギアメニューから追加することです。設定は ~/.codex/config.toml の [mcp_servers.<name>] に保存されます。この記事では、OpenAI 公式ドキュメントにそのまま載っている中立的な context7 の例を使って、3 つの方法すべてを解説します。私が推している製品ではありません。
- 以下のコマンド、フラグ、config.toml の構文は、執筆時点(2026 年 8 月)で learn.chatgpt.com/codex/extend/mcp の公式ドキュメントと照合済みです。Codex CLI はドキュメントよりも速く進化するため、これらに依存する前に codex mcp add --help を実行して、インストール済みのバージョンを確認してください。
Codex における「MCP サーバーの接続」の意味
MCP(Model Context Protocol)は、ツールごとに個別の連携を作る代わりに、1 つの共有インターフェースを通じてエージェントが外部のツールやデータを呼び出せるようにするオープン標準です。Codex における「MCP サーバーの接続」とは、どのコマンド(または URL)がサーバーを起動するのか、そして実行に必要な環境変数やトークンを Codex に伝えることを意味します。
まず覚えておくべきこと。Codex は MCP クライアントとしてのみ動作します。外部サーバーを呼び出すだけで、他のツールが呼び出す MCP サーバーにはなりません。Codex のサーバーモードを確認できるドキュメントは存在しません。MCP という概念自体にまだ慣れていない場合(Codex 固有の話ではなく)は、まず MCP とは何か、どう動くのかから読んで、それからここに戻ってきてください。
サーバーを追加する 3 つの方法
Codex にはサーバーを追加する方法が 3 つあり、どれか 1 つが特に「正しい」わけではありません。ワークフローに合わせて選んでください。
| 方法 | やること | 向いている場面 |
|---|---|---|
CLI - codex mcp add | ターミナルでコマンドを 1 つ実行 | STDIO サーバー、高速、コンテキストの切り替えなし |
| Desktop アプリ | Settings → MCP servers → Add server | STDIO とリモート HTTP の両方、手動での TOML 編集なし |
| IDE 拡張機能 | ギアメニュー → MCP servers → Add server | VS Code / IDE 内での作業、別ターミナル不要 |
3 つとも同じ場所、config.toml に書き込みます。完全なリファレンスはCodex MCP 公式ドキュメントにあります。以下のセクションでは CLI と直接編集の方法を詳しく解説します。ターミナルにすでに慣れているなら、この 2 つが最速です。
方法 1 - CLI からサーバーを追加する(STDIO)
基本コマンドの形は 1 つだけです。
codex mcp add <server-name> -- <server-launch-command>OpenAI 公式ドキュメントにそのまま載っている実例です。context7(バージョンを意識したライブラリ/フレームワークのドキュメント検索)を npx 経由で実行します。
codex mcp add context7 -- npx -y @upstash/context7-mcpこの例を使うのは、商用ベンダーのサーバーではなく中立的だからです。誰かが自社製品を最初の実行例として紛れ込ませることがありません。サードパーティの Codex-MCP ガイドの多くは自社サーバーをデモに使いますが、それでも動くとはいえ、クリーンなベースラインではなく、その製品がうまくいくケースをテストしていることになります。サーバーが環境変数(API キー、トークンなど)を必要とする場合は、--env フラグを変数ごとに繰り返して指定します。
codex mcp add my-server --env API_KEY=xxx --env REGION=us -- npx -y some-mcp-server追加したら、2 つの方法で確認します。
codex mcp list- 設定済みのサーバーを一覧表示します。- Codex TUI セッション内で
/mcpと入力 - そのセッションでアクティブなサーバーを表示します。
サーバーが表示されない場合、ほとんどは --(codex mcp add 自身のフラグとサーバーの実際のコマンドを区切る二重ハイフン)の打ち間違いです。サーバー自体が壊れていると決めつける前に、まずそこを確認してください。
方法 2 - config.toml を直接編集する
より明示的に制御したい場合や、MCP 設定をプロジェクトと一緒にバージョン管理したい場合は、ファイルを直接編集します。STDIO サーバーは次のようになります。
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
[mcp_servers.context7.env]
API_KEY = "your-value-here"Streamable HTTP(リモート)サーバーは異なるキーのセットを使います。command/args の代わりに url を使う、例えば Figma サーバーの場合です。
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_TOKEN"
http_headers = { "X-Client" = "codex" }bearer_token_env_var は、実際のトークンを保持する環境変数の名前を指します。その変数は自分のマシンで設定し、トークンをファイルに直接書き込むことはしません。~/.codex/config.toml はグローバルファイルで、すべてのプロジェクトに適用されます。信頼済みとマークされたプロジェクトでは、Codex はプロジェクトディレクトリ内の .codex/config.toml ファイルも読み込みます。リポジトリごとの MCP 設定をバージョン管理に含めたい場合に便利です。
リモート(Streamable HTTP)サーバーを追加する
現時点で HTTP サーバーの確実な方法は、Desktop の Settings か IDE 拡張機能のギアメニューです。名前を入力し、STDIO か HTTP を選び、URL を貼り付けます。この方法は明確にドキュメント化されています。
ここで慎重になるべき点です。一部のサードパーティガイド(公式ドキュメントではない)は、HTTP サーバーを CLI から直接追加する codex mcp add <name> --url <url> のような構文を示しています。OpenAI の公式ドキュメントは、執筆時点では CLI 構文セクションでこの --url フラグを確認していません。存在すると決めつけないでください。頼る前に codex mcp add --help を実行して、インストール済みの正確な CLI バージョンがそれをサポートしているか確認してください。最悪の場合でも、config.toml を手で編集する方法(上の方法 2)は、特定のフラグの存在に依存しないため、インストール済み CLI バージョンが何をサポートしていても機能します。
いくつかの微調整用キーは STDIO と HTTP の両方に適用され、同じ [mcp_servers.<name>] ブロック内で宣言します。startup_timeout_sec、tool_timeout_sec、enabled(サーバーのオン/オフ)、そして enabled_tools/disabled_tools(そのサーバーが公開できるツールを許可リスト/拒否リストで指定)です。
Codex と Claude Code - MCP 設定は同じではない
このサイトは Claude Code と Codex の両方を扱っているので、はっきり言っておきます。片方のツールの習慣をそのままもう片方に持ち込まないでください。
| 項目 | Codex | Claude Code |
|---|---|---|
| 設定フォーマット | TOML - config.toml | JSON - .mcp.json |
| 追加コマンド(STDIO) | codex mcp add <name> -- <command> | claude mcp add <name> -- <command> |
| 追加コマンド(HTTP) | 確認された CLI フラグなし - Desktop/IDE の設定を使用 | claude mcp add --transport http <name> <url> -H "Authorization: Bearer TOKEN" |
| スコープ | グローバル(~/.codex/config.toml)とオプションのプロジェクト単位ファイル、明示的なスコープフラグなし | 明示的な -s フラグ: local(デフォルト)/ project / user |
同じ実在のサーバー(GitHub)がもう片方でどう設定されるか見たいですか?GitHub MCP サーバーを Claude Code に接続するを読んでください。理論ではなく、ツールをまたいだ具体例です。
動作を確認する
最速のチェック方法は、TUI で /mcp と入力し、現在のセッションでアクティブなサーバーを確認することです。最もよくある失敗パターンは次のとおりです。
- 環境変数の不足 - サーバーは
API_KEYを必要とするのに、--envまたは TOML の.envブロックを忘れている。 - 誤った
command/args- パッケージ名の打ち間違い、またはnpx経由で実行する際の-yの欠落。 - HTTP トークンが未設定 -
bearer_token_env_varで指定した変数がマシンで設定されておらず、構文が正しくてもサーバーの認証が失敗する。
境界をはっきりさせるための一言。MCP サーバーは Codex に呼び出せる新しいツールを与えます(Figma ファイルを読む、データベースにクエリするなど)。AgentKit のスキルレイヤー(agentkit.best、有料キット。OpenAI の AgentKit とは別物)はその上に乗る別のレイヤーで、あらかじめ用意されたワークフローをパッケージ化したものです。MCP サーバーの接続とは別物であり、一方を使うのにもう一方は必要ありません。
よくある質問(FAQ)
Codex は MCP サーバーですか、それともクライアントだけですか?
クライアントだけです。Codex はより多くのツールやデータを得るために外部の MCP サーバーを呼び出します。Codex 自身が、他のツールから呼び出される MCP サーバーとして動作することを確認できるドキュメントはありません。
MCP サーバーを追加する正確なコマンドは?
codex mcp add <server-name> -- <launch-command>、例えば codex mcp add context7 -- npx -y @upstash/context7-mcp です。環境変数は --env KEY=VALUE を変数ごとに繰り返して追加します。
Codex は MCP 設定をどこに保存しますか?
~/.codex/config.toml(グローバル、すべてのプロジェクトに適用)の [mcp_servers.<name>] の下です。信頼済みプロジェクトの場合、Codex はプロジェクトディレクトリ内の .codex/config.toml ファイルも読み込みます。
STDIO と Streamable HTTP の違いは?
STDIO は command/args を通じてサーバーをローカルプロセスとして実行します(例えば npx 経由で起動)。Streamable HTTP は url でリモートサーバーを呼び出し、bearer_token_env_var またはカスタムヘッダーで認証します。ローカルにインストールするものはありません。
リモートサーバーを CLI から直接追加できますか?
確認されていません。一部のサードパーティガイドは --url フラグを示していますが、Codex の公式ドキュメントは執筆時点でそれを記載していません。現時点で確認されている方法は Desktop Settings か IDE のギアメニューです。お使いの CLI がサポートしているか確認するには、codex mcp add --help を実行してください。
Codex の MCP セットアップは Claude Code と同じですか?
いいえ。Codex は TOML(config.toml)を使い、明示的なスコープフラグはありません。Claude Code は JSON(.mcp.json)を使い、明示的な -s local/project/user フラグがあります。基盤となる MCP 標準は同じですが、設定の仕組みは異なります。片方のツールから構文をそのままコピーしないでください。
まとめ
高速な STDIO 追加には CLI を、リモート HTTP サーバーが必要で CLI がまだそのフラグをサポートしているか不明なときは Desktop/IDE を、プロジェクトごとの設定をバージョン管理下に置きたいときは config.toml を直接編集する、という使い分けです。MCP を超えて Codex を拡張したいですか?Codex Skills(SKILL.md)を参照してください。MCP の代替ではなく、並行する拡張手段です。Codex 全般が初めてですか?まずは OpenAI Codex とは何かから始めてください。