Codex CLIとMCPの関係
Codex CLIとMCPを組み合わせると聞いても、MCPが何なのかわからなければ、いまひとつピンとこないかもしれません。
ここでは、MCPという仕組みの基本と、Codex CLIと組み合わせて何ができるようになるのかを、順番に見ていきましょう。
【関連】Codex CLIとは？初心者向けにできることや使い方をわかりやすく解説
MCP（Model Context Protocol）の基本
MCPとは、AIと外部のツールや情報源をつなぐためのプロトコルです。Anthropicが策定したオープンな標準規格で、MCPに対応したさまざまなアプリケーションが利用できます。AIモデルが外部サービスとやりとりするための「共通言語」のようなものだとイメージするとわかりやすいでしょう。
MCPの仕組みは、サーバーとクライアントの関係で成り立っています。MCPサーバーは外部サービスへのアクセスを担う側で、GitHubやドキュメントサイトに接続する役割を持ちます。
一方のMCPクライアントは、そのサーバーにリクエストを送る側です。Codex CLIは、このMCPクライアントとして動作します。
この仕組みを使うと、Codex CLIはAI単体の知識だけでなく、外部の最新情報やサービスの機能を利用しながら回答や操作ができるようになります。簡単にいえば「Codex CLIというAIが、外部の便利なツールを呼び出して使える」状態になるイメージです。
Codex CLIでMCPを使ってできること
では、実際にMCPを組み合わせると、Codex CLIは何ができるようになるのでしょうか。
Codex単体でも、手元のプロジェクトのファイルを読んだり、コマンドを実行したりはできます。ただし、AIモデルの知識は学習した時点のものなので、新しいライブラリの仕様などは反映されていない場合があります。
MCPサーバーをつなぐと、この制約が外れます。必要なときに外部から最新の情報を取ってきたり、実際にサービスを操作したりできるようになるのです。
代表的な用途には以下のものがあります。
-
技術ドキュメントの検索
ライブラリの最新仕様をAIに渡して、正確なコードを生成させる -
GitHubの操作
リポジトリのファイル一覧の取得や、IssueやPRの内容の確認をCodex CLI上から行う -
コード解析・編集支援
プロジェクト内のコード構造をMCPサーバーが解析し、Codexが的確な修正や検索をできるようにする
STDIOとStreamable HTTPの違い
MCPサーバーへの接続方法には、STDIOとStreamable HTTPという2つの方式があります。名前だけ見ると難しそうですが、要は「サーバーが同じPCの中にあるか、外にあるか」の違いだと考えると理解しやすくなります。
STDIOは、いわば同じ部屋にいる人と直接話すような方式です。Codex CLIが動いているのと同じPCの中でMCPサーバーのプログラムを起動し、その場で直接やりとりするため、Codexとサーバーの間の通信にネットワークを使わないのが特徴です。
Node.jsやPythonで書かれたMCPサーバーをコマンドで起動するケースが多く、初心者がまず試すなら、この方式が定番です。
一方のStreamable HTTPは、電話をかけて話すイメージに近い方式です。インターネット上のどこかで動いているMCPサーバーに、URLを通じてアクセスします。すでに誰かが公開しているサービスにつなぐ際に使う方式で、自分でサーバーを起動する必要がありません。
ただしインターネット経由での接続が必要になるため、APIキーなどの認証情報を求められる場合もあります。
ちなみに、どちらの方式を使うかは自分で選ぶというより、利用したいMCPサーバーの提供方法によって自然に決まるものです。
Codex CLIにMCPを設定する方法
MCPの概要がわかったら、次はいよいよ実際の設定です。Codex CLIにはMCPサーバーを管理するための専用コマンドが用意されており、コマンド一つで登録・確認・認証まで行えます。
設定ファイルを直接編集すれば、より細かい調整も可能です。ここでは、基本的な登録方法から詳細設定まで、順を追って見ていきましょう。
codex mcp addによるMCPサーバーの追加
MCPサーバーをCodex CLIに使ってもらうには、まず「これを使います」と教えてあげる必要があります。その登録を行うのがcodex mcp addコマンドです。
登録の際に必ず指定するのは、サーバー名と、サーバーへの接続方法の2つです。サーバー名はgithubやcontext7のように、あとで見て何のサーバーかわかる名前を付けておくと管理が楽になります。
接続方法は、サーバーの種類によって2通りあります。ローカル上でサーバーを起動するタイプなら、起動するためのコマンドを指定します。Node.jsで動くサーバーなら、npxから始まることが多いでしょう。一方、GitHub公式MCP Serverのようにインターネット上で提供されているタイプなら、--urlオプションで接続先のURLを指定します。
サーバーによっては、APIキーやトークンといった認証情報も必要です。GitHub公式MCP Serverの場合は、GitHubで発行したトークンを環境変数に入れておき、その環境変数名を--bearer-token-env-varオプションで指定する、という流れになります。
サーバーごとに必要な情報は異なるため、詳しい手順はそれぞれのMCPサーバーの公式ドキュメントで確認するのが確実です。
codex mcp listとloginによる接続確認・認証
サーバーを登録したら、それがちゃんと反映されているかを確認したくなると思います。そこで使うのがcodex mcp listコマンドです。実行すると、これまでに登録したMCPサーバーの名前や接続方式、設定内容が一覧で表示されるので、登録ミスがないかをひと目でチェックできます。
なお、URLで接続するタイプのサーバーの中には、トークンを環境変数で渡す代わりに、OAuthという仕組みでログインするものもあります。OAuthとは、パスワードそのものを渡すのではなく、「このアプリにはここまでの範囲だけアクセスを許可します」という限定的な権限を渡す仕組みです。
こうしたサーバーでは、codex mcp login サーバー名を実行すると、ブラウザで認証ページが開き、ログインを求められます。一度認証を済ませれば、アクセストークンがローカルに保存され、次回からは自動的に認証済みの状態で通信できるようになります。
注意点として、このOAuthログインが使えるのはURLで接続するタイプのサーバーに限った話です。npxなどでローカル上に起動するタイプのサーバーには関係のない仕組みなので、混同しないようにしましょう。
config.tomlを使ったMCPの詳細設定
実は、codex mcp addコマンドで実施している登録作業は、裏側ではconfig.tomlというファイルに設定を書き込んでいるだけです。つまり、このファイルを直接編集すれば、コマンドを使わなくても同じことができますし、コマンドでは指定しきれない細かい設定まで書き込めます。
config.tomlは通常、ホームディレクトリの中にある.codexフォルダに置かれています。ローカルPC上で起動するタイプ（STDIO）のサーバーであればcommand（実行コマンド）とargs（引数）を、URLで接続するタイプ（Streamable HTTP）のサーバーであればurlを指定します。
STDIOタイプのサーバーには、envという項目で環境変数を定義し、APIキーなどをそのサーバー専用に渡せます。ただしこの場合、キーの値そのものがconfig.tomlに書き込まれる点に注意してください。
一方、URLで接続するタイプであれば、先述した--bearer-token-env-varオプションに当たる、bearer_token_env_varという項目を使う方法が安全です。こちらはキーの値ではなく、値を格納した環境変数の名前だけをファイルに書けばよいため、値そのものはファイルに残りません。
CLIコマンドでの登録とconfig.tomlでの設定は、どちらを使っても構いません。とりあえず手早く試したいならCLIコマンドを、細かいオプションまで調整したい場合や設定をGitなどで管理したいときはconfig.tomlを直接編集するのがおすすめです。ただし、Gitで管理する場合は、APIキーなどの認証情報をファイルにそのまま書き込まないよう注意しましょう。
WindowsでCodex CLIにMCPを設定する際のポイント
WindowsでもCodex CLIからMCPサーバーに接続できます。基本的な設定の考え方はmacOSやLinuxと同じですが、次の3点を押さえておくと、余計なトラブルを避けられます。
1つ目はパスの表記です。Windowsは通常バックスラッシュ（\）でフォルダを区切りますが、設定ファイルの中ではスラッシュ（/）を使うか、バックスラッシュを二重にする（\\）ようにすると、エラーになりにくくなります。ちなみに、TOMLではシングルクォートで囲むとバックスラッシュをそのまま書けるため、こちらを使う方法もあります。
2つ目は実行環境です。STDIOタイプのMCPサーバーの多くはNode.jsかPythonで動作します。コマンドプロンプトやPowerShellでnode -vやpython --versionを実行し、正しくバージョンが表示されるかを事前に確かめておきましょう。
3つ目は環境変数です。STDIOタイプのMCPサーバーは、Windowsに登録した環境変数をすべて自動で引き継ぐわけではありません。APIキーなどを渡すには、config.tomlのenvに値を直接書くか、Windowsのユーザー環境変数に登録したうえで、env_varsにその変数名を書いてください。
おすすめのMCPサーバーと活用例
MCPの設定方法がわかったら、次はどのMCPサーバーを使うかを考えましょう。MCPサーバーは世界中の開発者によってさまざまなものが公開されており、目的に応じて選べます。
ここでは、Codex CLIと組み合わせて特に活用しやすい代表的なMCPサーバーをいくつか紹介します。
技術ドキュメントを参照できるContext7
Codex CLI単体は、学習した時点までの知識をもとに回答します。そのため、新しくリリースされたライブラリやバージョンの仕様が反映されておらず、古い書き方のコードを提案してしまう場合があります。
Context7は、この問題を補ってくれるMCPサーバーです。例えば、「このライブラリの最新の使い方を教えて」とCodexに依頼すると、Context7がそのライブラリの最新のドキュメントやコード例を取得してAIに渡すため、それをもとにした回答を返してくれます。
接続方式は、npxでローカルPC上に起動する方法と、URLで接続する方法の両方に対応しています。APIキーなしでも無料で試せます。
新しいライブラリを使ったコーディングをCodexに任せるときは、まずこれを試してみるとよいでしょう。
リポジトリを操作できるGitHub MCP Server
GitHubを日常的に使っているなら、次に試したいのがGitHub MCP Serverです。GitHub公式が提供しているMCPサーバーで、Codex CLIがGitHub上のリソースに直接手を伸ばせるようになります。
例えば、次のような操作が可能です。
- リポジトリ内のファイルの読み取り
- Issueの一覧や内容の確認
- PRのレビューコメントの取得
「このIssueの内容を読んで、修正案のコードを書いて」と頼めば、Codexが自分でIssueの中身を確認し、それに沿ったコードを書いてくれるようになります。GitHubでの作業が多い開発者ほど、恩恵の大きい組み合わせです。
認証には、GitHubで発行したトークンを使います。前のセクションで紹介したように、トークンを環境変数に入れておき、--bearer-token-env-varオプションでその変数名を指定して登録すれば使い始められます。
また、GitHub MCP ServerではIssueの作成やコメントの投稿といった書き込み操作も可能です。トークンに与える権限は、必要な範囲だけに絞っておきましょう。
コード解析を強化するSerenaとcontextの設定
大きなプロジェクトになると、ある関数がどこで使われているかを把握するだけでも一苦労です。単純なテキスト検索では、同じ名前の別の変数まで拾ってしまい、かえって時間がかかるケースもあります。
Serenaは、こうした場面で力を発揮するMCPサーバーです。コードをただの文字列としてではなく、クラスや関数の定義といった意味のある構造として理解した上で、検索やナビゲーションを行ってくれます。
Codex CLIと組み合わせる際は、Serenaを起動するコマンドの末尾に--context codexというオプションを付けて登録しておくのがポイントです。これにより、SerenaがCodexと組み合わせて使うのに適した設定で動くようになります。
例えば、「この関数がどこで使われているか調べたい」「このクラスの定義を見つけて修正したい」といった作業を、大規模なプロジェクトで行うときに特に頼りになります。
用途に合わせたMCPサーバーの選び方
ここまで3つのMCPサーバーを紹介しましたが、全部いきなり導入する必要はありません。むしろ、サーバーの数が増えるほど設定の管理は煩雑になり、トラブルが起きた際の原因の特定も難しくなります。
選ぶ際の考え方は、シンプルです。
- ライブラリの最新の使い方を反映させたいなら、Context7
- GitHubでの作業を効率化したいなら、GitHub MCP Server
- 大きなプロジェクトのコード把握に苦労しているなら、Serena
まずは、この3種類の中から自分の作業スタイルに合うものを1つ選んで試してみるのをおすすめします。使い方に慣れてきたら、必要に応じて少しずつ増やしていくくらいがちょうどいいペースです。
Codex CLIでMCPが動かない場合の原因と対処法
せっかく設定したのに、Codexから反応がないという状況には、MCPを使い始めたばかりの頃は誰もが一度はぶつかるものです。その原因の多くは、設定ミスや環境の問題です。
ここでは、よくあるトラブルの原因や対処法について解説します。焦らず一つずつ確認すれば、大抵の問題は解決できるので、落ち着いて対処しましょう。
MCPサーバーに接続できない場合の確認項目
接続できない場合、まず疑うべきは登録内容そのものです。codex mcp listを実行し、目的のサーバーがきちんと一覧に表示されているか、サーバー名を打ち間違えていないかを確認しましょう。
登録自体に問題がなければ、次は接続方式ごとに確認します。STDIOタイプであれば、登録したコマンド（例：npx @some/mcp-server）を、Codex CLIを介さずにターミナルで直接実行してみてください。ここでエラーが出るなら、原因はCodex側ではなくコマンド自体にあります。
Streamable HTTPタイプであれば、設定したURLに打ち間違いがないか、トークンを入れた環境変数が正しく設定されているかを確認しましょう。codex mcp listでは認証の状態も確認できます。
それでも解決しない場合は、土台となるソフトウェアを疑いましょう。Node.jsやPythonが必要なMCPサーバーであれば、node -vやpython --versionを実行し、そもそもインストールされているか、パスが通っているかを確認してください。
これらの基本的な切り分けを順番に行うと、多くの接続問題は原因を特定できます。
startup_timeout_secとtool_timeout_secの設定
エラーメッセージにtimeoutという文字が含まれていたら、疑うべきは待ち時間の設定です。startup_timeout_secはサーバーが起動するまでの最大待ち時間で、tool_timeout_secはツールの実行が完了するまでの最大待ち時間を表しています。
厄介なのは、サーバー自体はきちんと起動しているのに、単に処理に時間がかかりすぎてタイムアウト扱いになってしまうケースです。大量のドキュメントを取得するような、処理時間の長いMCPサーバーではよく起こります。
この場合は、config.toml内の該当サーバーの設定にtool_timeout_secを追加し、数値を大きくすれば解決する場合があります。例えば、tool_timeout_sec = 120のように、秒単位で指定します。
サーバーの起動自体に時間がかかっている場合は、同じ要領でstartup_timeout_secの方を調整してください。
APIキー・OAuth・環境変数の設定ミス
外部サービスと連携するMCPサーバーの多くは、APIキーやアクセストークンが必要です。これらが正しく設定されていないと、サーバーへの接続はできても、認証エラーで実際の機能が使えないという事態になりかねません。
トークンを使うタイプのサーバーでは、先述したenvやenv_vars、bearer_token_env_varのいずれかを使って値を渡します。
まず下記の点を確認してください。
- キーに誤字がないか
- 有効期限が切れていないか
- 値を渡すはずの環境変数が実際にセットされているか
OAuth認証に対応したサーバーであれば、codex mcp login サーバー名を実行して認証フローを済ませる必要があります。認証が完了していない状態では利用できないため、エラーが出た場合は、もう一度loginコマンドを実行してみてください。
なお、サーバーによってトークン認証とOAuth認証のどちらに対応しているかは異なるので、迷ったらそのMCPサーバーの公式ドキュメントで確認しましょう。
MCP利用時に意識したい権限とセキュリティ
MCPサーバーと接続すると、Codex CLIは外部サービスやローカルのファイルシステムに対して、さまざまな操作ができるようになります。
便利な反面、使い方次第では意図しない操作が行われてしまうリスクも生まれるので、Codex CLIに与える権限の範囲は意識しておくべきです。
Codex CLIには、config.tomlのenabled_toolsという設定で、各MCPサーバーが使えるツールを絞り込む仕組みが用意されています。例えばGitHub MCP Serverであれば、読み取り系のツールだけを許可し、書き込みや削除系のツールは無効にする、といった設定が可能です。
もう一つ大切なのは、信頼できる提供元のMCPサーバーを使うという原則です。よく知らないサーバーを追加するときは、そのサーバーが実際に何を行うのかをドキュメントや公開されているコードで確認してから導入しましょう。必要最小限の権限で運用する習慣が、安全にMCPサーバーを活用するための基本になります。
よくある質問（Q&A）
Q. MCPとプラグインは何が違うの？
A. プラグインはソフトウェアに直接組み込む拡張機能ですが、MCPは独立したサーバーとして動き、標準化されたプロトコルで通信します。異なるAIツールが同じMCPサーバーを共有して使える点が大きな違いです。
Q. MCPサーバーは無料で使えますか？
A. MCPサーバー自体は多くがオープンソースで無料ですが、接続先の外部サービス（GitHubの高度な機能など）によっては有料プランが必要なケースもあります。また、接続先がAI APIを使っている場合は利用料がかかる場合があります。
Q. codex mcp addで追加した設定はどこに保存される？
A. 通常、ホームディレクトリ以下の.codex/config.tomlに追記されます。このファイルをテキストエディターで開くと、追加したサーバーの設定内容を直接確認・編集できます。
Q. 複数のMCPサーバーを同時に使えますか？
A. 使えます。複数のサーバーをconfig.tomlやcodex mcp addで登録しておくと、Codexが必要に応じてそれぞれのサーバーを呼び出します。ただし、サーバーが増えるほど管理が複雑になるため、必要なものだけに絞るのをおすすめします。
Q. MCPサーバーの動作確認はどうすればいい？
A. codex mcp listで登録を確認し、STDIOタイプであれば登録したコマンドをターミナルで直接実行してエラーが出ないかを確認するのが手軽な方法です。正常に動作するなら、Codexからの呼び出しでも問題ない可能性が高いです。
まとめ
MCPはAnthropicが策定したオープンな標準プロトコルです。Codex CLIには、このMCPのクライアントとして動作する機能があらかじめ備わっています。ただし、その機能だけでは何も起きません。
MCPサーバーを登録すれば、Codexは学習した時点の知識だけに頼るのではなく、最新のドキュメントをその場で調べたり、GitHub上のIssueやPRを直接操作したり、コードベース全体の構造を踏まえた上で修正したりできるようになります。
設定にはいくつか手順が必要ですが、一度理解してしまえばさまざまな外部サービスと連携しながら作業効率を高めていけるため重宝するでしょう。
今回の重要なポイントを振り返ります。
重要なポイント
- MCPはAIと外部ツールをつなぐためのオープンな標準規格で、Codex CLIはMCPクライアントとして動作する
- MCPサーバーはcodex mcp addで登録でき、細かい設定はconfig.tomlで行える
- 最初は、自分のニーズに合うMCPサーバーを1つ選ぶのがおすすめ
- トラブルが起きた際は「登録内容→接続方式ごとの確認→実行環境」の順に切り分ける
- 使えるツールやトークンの権限は、必要最小限に絞って運用する
まずは1つのMCPサーバーを登録し、codex mcp listで状態を確認するところから始めてみてください。1つ動かせれば、あとは同じ手順の繰り返しです。
MCPの設定に慣れてきたら、ぜひさまざまなサーバーを試して、自分の作業スタイルに合った組み合わせを見つけていきましょう。