Codex MCP セットアップ｜GitHub サーバーをつないで読み取り確認まで

Codex MCP の設定は config.toml の 1 か所だけで、デスクトップアプリ・CLI・IDE 拡張が同じ内容を読みます。入口ごとに書き分ける必要はありません。GitHub には公式ガイドが用意した URL 形式の構成があり、決めるのはトークンに渡すスコープと、開くツールの範囲の 2 つです。まず読み取り中心で登録し、Issue 一覧のような依頼で実際のデータが返るところまで確かめます。

Codex の MCP 設定は、どのファイルに書けばどの入口でも効きますか

~/.codex/config.toml の 1 ファイルだけです。[mcp_servers.<名前>] のブロックをここに足せば、デスクトップアプリからでも CLI からでも、IDE 拡張からでも同じサーバーが見えます。入口ごとにファイルを分ける必要はありません。

案件ごとに接続先を分けたいなら、プロジェクト側に .codex/config.toml を置く手があります。ただし読まれるのは、信頼済みプロジェクトとして扱っているフォルダだけです。どこに置いても効くわけではありません。この共有が届くのは手元の PC で動く 3 つの入口までで、Web 版のスケジュールタスクとクラウド実行はその外にあります。

MCP は共通規格なので、同じサーバーは Claude Code のような別のクライアントからも使えます。ただ、設定ファイルの形式と置き場所はクライアントごとに別です。Codex は TOML、Claude Desktop 系は JSON で、接続先が同じでも書き方は揃いません。

GitHub の MCP サーバーは、どの接続方式で登録しますか

stdio 形式とリモート形式の 2 つです。stdio は手元でプロセスを起動するタイプ、リモートはホスト側が公開しているエンドポイントに URL でつなぐタイプです。GitHub はリモート形式なので、自分でプロセスを動かす必要はありません。

つなぐ目的は、git コマンドでは届かない範囲を Codex から扱えるようにすることです。依頼文の中で Issue やプルリクエストを参照できるようになります。使えるのは、つないだサーバーが公開しているツールの範囲までです。

手元で起動する形式で登録する

npx や uvx のように手元でプロセスを起動するタイプは、codex mcp add <サーバー名> -- <起動コマンド> の 1 行で登録できます。設定ファイルに直接書くなら、ブロックに command と args を並べます。書き込まれる先はどちらも同じなので、あとから片方で直しても二重登録にはなりません。

URL と認証情報でつなぐ形式

HTTP で公開されているサーバーは、ブロックに url を書き、認証トークンは bearer_token_env_var に環境変数の名前を入れます。トークン本体を設定ファイルに直書きしなくて済むのが利点です。OAuth が要るサーバーは codex mcp login <サーバー名> でブラウザ認証を通します。どの認証方式になるかはサーバー側の提供形態で決まります。

GitHub の場合の具体例

GitHub の公式ガイドの構成例は、url と環境変数の名前だけで足ります。API キーの部分は自分のトークンに差し替えます。

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_PAT_TOKEN"

CLI から登録するときも同じで、codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN の形です。環境変数の値は自分のトークンにします。

ChatGPT 本体のプラグインとの違い

ChatGPT 本体側と Codex 統合のデスクトップアプリでは、MCP の扱いが違います。本体側が使うのは、プラグインが提供するリモートの MCP ツールです。手元の Codex は、ローカルで起動する stdio サーバーも直接扱えます。GitHub の MCP を試すなら、後者から始めるのが素直です。

GitHub の操作という点では同じでも、本体側のプラグイン経由だと設定の置き場所も手順も別になります。

GitHub の認証とツールの許可は、どこまで絞りますか

絞る場所は 2 か所です。GitHub 側のトークンのスコープと、Codex 側のツール許可リストです。これに加えて、サーバー側の読み取り専用モードを使えば、書き込み系のツールを入口で外せます。

トークンに渡す権限

GitHub の Codex ガイドが最小として挙げるのは、repo（リポジトリ操作全般）、workflow（Actions のワークフロー）、read:org（組織レベルのリソース）、project（クラシックなプロジェクトボード）、gist（gist のツール）です。足りない分は、ツールのリクエストが権限で失敗したときに足します。トークンはパスワードと同じ扱いで、リポジトリにコミットしたり会話に貼ったりしません。

ツール許可リスト

Codex 側は enabled_tools に読み取り系のツール名だけを並べます。書かなかったツールはモデルから見えなくなり、呼ぼうとしても呼べません。GitHub の MCP サーバーで読み取りに対応するのは list_issues、issue_read、search_issues、list_pull_requests、pull_request_read、get_file_contents などです。issue_write や create_pull_request は書き込み系になります。そのセッションで使える名前は /mcp で分かります。

ツール名を並べる代わりに、サーバー側で読み取り専用に絞る方法もあります。リモートサーバーの URL の末尾に /readonly を足すと、読み取りを有効にするツールだけに限定されます。既定のツールセットなら https://api.githubcopilot.com/mcp/readonly です。X-MCP-Readonly ヘッダーでも同じ効果が得られ、Codex では静的なヘッダーを http_headers に書きます。

エージェントに渡す道具が増えて、消費の上限を鍵の単位で決めたくなったら、MixRoute のコンソールにあるキー単位の制御が使えます。model_limits はそのキーが呼べるモデルを限定します。remain_quota に事前に渡した金額はリクエストごとに減り、使い切るとそのキーが止まります。どちらもキーに付いた欄で、リクエストのルーティングとは関係ありません。月次の割当や回数の制限ではなく、実際に使える量はアカウント残高でも制限されます。

鍵の単位で先に上限を決めておくと、ツールを増やしたときの効き方が変わります。MixRoute の料金を確かめると、消費の上限をどの単位で決めるかを判断する材料になります。

読み取りだけでつながったことは、どう確認しますか

確認は 2 段階あります。登録が済んだかを見る段階と、実際に API まで届いているかを見る段階で、この 2 つは別物です。一覧に名前が出ただけで終わりにすると、あとで静かに失敗します。

登録の確認

ターミナルでは codex mcp list で登録済みサーバーの一覧が見えます。ここで見えるのは、設定として登録されている内容です。対話画面で /mcp と入力すると、有効なサーバーに加えて使えるツールまで出ます。

実接続の確認

/mcp で github のツールが見えていれば、認証とスコープも通っている目安です。GitHub のガイドもこの /mcp を確認手順にしていて、ツールが 1 つも出ないときはトークンの有効性やスコープを疑います。最後は読み取り専用の依頼を投げます。「〇〇リポジトリの未解決 Issue を一覧にして」のように、対象と操作がはっきりした依頼が向いています。実際のデータが返れば、認証も通信も通っています。エラーが返るなら次の切り分けに進みます。

つないだサーバーが増えるほど、ツールの説明が毎回の依頼に文脈として加わり、利用枠の消費も増えます。読み取り確認が済んだら、その日の作業で使うものだけ有効にしておくのが現実的です。

つながらないときは、どこから見直しますか

確かめる順番は決めておきます。まず記述、次にテーブル名、最後にトークンの有効性とスコープです。複数を同時に変えると、どれが効いたのか分からなくなります。

時間切れは startup_timeout_sec と tool_timeout_sec で調整します。どちらもサーバーごとの設定に書く項目です。起動が遅いサーバーは既定の 10 秒を超えることがあるので、startup_timeout_sec を延ばします。原因が絞れないときは /mcp verbose でサーバーの診断を見ます。

ツールが見えているのに動かないときは、enabled_tools にそのツール名が入っているかを見ます。

手元で動いた設定は、定期実行やクラウドでもそのまま使えますか

そのままは使えません。実行場所が変われば、設定の読み込み元、ネットワーク、認証情報の 3 つが同時に変わります。

Web 版で作ったスケジュールタスクには、手元の config.toml は自動で共有されません。デスクトップアプリのスケジュールタスクは手元のパソコン上で動くので同じ設定の圏内ですが、公式が明示しているのはプラグインを使えるという点です。Codex のクラウド実行の環境設定ページには、MCP サーバーを登録する欄がありません。

無人で動くスケジュールタスクは、既定のサンドボックス設定のまま実行されます。サンドボックスが読み取り専用かワークスペース書き込みだと、ネットワークアクセスが要るツール呼び出しは失敗します。

MCP のツール呼び出しにも承認は効き、サーバー単位・ツール単位で承認モードを設定できます。破壊的な操作は常に承認を求めます。外部サービスに触れる範囲は、トークンのスコープ、enabled_tools と disabled_tools、承認モード、GitHub 側の読み取り専用モードで絞ります。

定期実行に載せる前に、本番と同じスコープとネットワークの範囲で一度手動実行して、通ることを確かめます。

読み取り確認ができたら、次は何から Codex に任せますか

まず読み取りの依頼から始めます。書き込みや送信を伴う操作は、承認を挟みながら試すのが順当です。読み取りだけで完結する仕事も多く、GitHub の Issue を読んで変更点を整理するような作業はそのまま任せられます。

承認の設定は 2 段階です。サーバー単位の default_tools_approval_mode は auto、prompt、writes、approve から選べます。writes は、読み取り専用の印が付いていないツールで承認を求めるモードです。特定のツールだけ挙動を変えたいときは、tools.<ツール名>.approval_mode で上書きします。任せる範囲を広げるときも、サーバーを増やすより先に、いまつないだツールでどこまで進められるかを見ます。

依頼の出し方と開発の流れを押さえておくと、読み取り確認のあとに任せる範囲を決めやすくなります。バイブコーディングの進め方を確かめると、どこまで Codex に渡すかの線引きが持てます。