Codex MCP設定ガイド｜接続手順と安全な権限設計

Codex MCPを設定すると、Codex CLIから外部のデータやツールへ共通の方法で接続できます。リポジトリ内の作業だけでなく、承認した業務システムの検索や操作をワークフローへ組み込める一方、接続先へ情報が渡り、外部操作が実行される可能性も生まれます。そのため、「接続できた」で終わらず、設定範囲、認証、公開ツール、承認方法まで設計することが重要です。

本記事では、OpenAIのCodex MCP公式ドキュメント、基本設定、CLIリファレンスに基づき、追加から確認までを解説します。変わりにくい設定手順へ絞り、実行前には利用中のCodex CLIでcodex mcp --helpも確認します。

Codex MCPとは

MCP（Model Context Protocol）は、AIアプリケーションと外部システムを接続するためのオープンな標準です。MCPクライアントがサーバーへ接続し、サーバーが公開する機能を利用します。CodexではCodex CLI、IDE拡張、デスクトップアプリがクライアント側になり、接続先のMCPサーバーがツールを提供します。

MCPそのものの構造は、MCP（Model Context Protocol）の解説も参考にしてください。

要素	Codex MCPでの役割
Codex	MCPクライアントとしてサーバーへ接続し、ツールを呼び出す
MCPサーバー	検索、読み取り、更新など、接続先が定義したツールを公開する
config.toml	サーバー名、接続方式、起動情報、タイムアウト、ツール範囲などを定義する
認証基盤	接続先が要求するOAuthやトークンなどを管理する

OpenAI公式によると、Codexが対応するトランスポートはSTDIOとStreamable HTTPです。STDIOは端末上でローカルプロセスを起動し、標準入出力を使って通信します。Streamable HTTPはURLで示したリモートサーバーへ接続します。サーバーがどちらに対応するかは、接続先の公式ドキュメントで確認します。

CLI・IDE・デスクトップで設定を共有する

CodexのMCP設定は、CLI、IDE拡張、Codexデスクトップで共有されます。「CLIだけの試験設定」と思い込まず、変更前後に各インターフェースへの影響を確認してください。

Codex CLI自体のインストールや基本操作が未完了なら、先にCodex CLIの使い方ガイドで起動、認証、権限の基本を確認しましょう。

導入前に決めること

MCPサーバーを追加する前に、次の項目を明文化します。

• サーバーの提供・運営主体は誰か
• ローカルで何のプロセスを起動するか、またはどのURLへ通信するか
• どのコード、文書、入力が接続先へ渡る可能性があるか
• 読み取り、作成、更新、削除のどこまで必要か
• 認証情報を誰が発行し、どこへ保管し、どう失効するか
• 障害や誤操作が起きた場合に誰が接続を停止するか

MCP対応だけで接続先の安全性は保証されません。ローカルプロセスの権限とリモートへの送信内容を事前審査してください。サーバー選定の観点はMCPサーバーの仕組みと選び方でも整理しています。

Codex MCPを最短で追加する手順

Codex MCPの導入は、シェルで設定を管理するcodex mcpと、Codexの対話TUIで状態を見る/mcpを使い分けると迷いません。シェルコマンドをTUIへ入力したり、スラッシュコマンドを通常のシェルで実行したりしないよう注意してください。

1. 利用中のCLIでヘルプを確認する

最初にターミナルで次を実行します。

codex mcp --help

公式ドキュメントは基準になりますが、CLIは更新されます。サブコマンドやオプションの正確な形は、利用中の環境に表示されるヘルプと接続先の公式手順を照合してください。記事やSNS投稿からコピーしたコマンドを、そのまま本番端末で実行するのは避けます。

2. STDIOサーバーを追加する

STDIOサーバーを追加する基本形は次のとおりです。

codex mcp add <server-name> -- <stdio-server-command>

<server-name>にはCodex上で識別する名前、<stdio-server-command>にはサーバー提供元が指定する起動コマンドと引数を入れます。ここでは実在パッケージ名を例示していません。パッケージの取り違えや名前の類似を避けるため、必ず提供元の公式ページから取得してください。

コマンドの後半はローカルでプロセスを起動します。配布元、引数、作業ディレクトリ、読み書きできる範囲を確認し、検証用環境から始めましょう。

3. 登録済みサーバーを一覧確認する

追加後、次を実行します。

codex mcp list

目的のサーバー名が表示されるか、接続方式や設定が想定と一致するかを確認します。一覧に現れない場合は、設定を書いたユーザー、ホームディレクトリ、プロジェクト、起動場所が一致しているかを見直してください。

4. 必要なサーバーだけログインする

接続先がOAuthに対応し、認証を要求する場合の導線は次のとおりです。

codex mcp login <server-name>

Codex本体とMCPサーバーの認証は別です。接続先ドメイン、要求権限、利用アカウントを確認し、不要になった認可を失効できる手順も把握してください。

すべてのMCPサーバーがOAuthを使うわけではありません。ログイン方法は接続先の仕様に従い、確認できない認証コマンドやパラメータを推測で追加しないでください。

5. TUIの/mcpで実状態を確認する

Codex CLIの対話TUIを起動し、プロンプトで次を入力します。

/mcp

確認すべきなのは、設定ファイルに名前があることだけではありません。サーバーが有効か、必要なツールが見えるか、想定外の書き込み・削除ツールが公開されていないかまで点検します。その後、検証用データに対する読み取りなど、影響の小さい操作から試します。

codex mcp listは設定の棚卸し、/mcpは対話セッションから認識される状態の確認、と考えると整理しやすくなります。追加直後だけでなく、設定変更やサーバー更新後にも両方を確認してください。

config.tomlでMCPサーバーを設定する

CLIコマンドに加えて、TOML形式のconfig.tomlへMCPサーバーを定義できます。設定項目をレビューしたい場合や、秘密情報を除いたプロジェクト設定をチームで管理したい場合に適しています。

2つの設定範囲を使い分ける

主な設定場所は次の2つです。

範囲	パス	適した用途	注意点
ユーザー設定	~/.codex/config.toml	同じ利用者が複数の作業で共通利用する接続	意図しないプロジェクトでも利用対象にならないか確認する
プロジェクト設定	<project>/.codex/config.toml	特定プロジェクトだけで使う接続	信頼済みプロジェクトでのみ利用し、秘密情報をコミットしない

プロジェクトから配布するのはサーバー名、承認済みURL、許可ツールなどの非秘密情報に限定します。認証情報は安全な管理先へ分離し、Git履歴へ入った場合は失効・再発行してください。

STDIOの設定例

以下は構造を示す説明用の例です。

[mcp_servers.example_local]command = "/absolute/path/to/example-mcp-server"args = ["--read-only"]startup_timeout_sec = 10tool_timeout_sec = 60enabled_tools = ["search", "read"]

commandは起動するプログラム、argsはその引数です。example_local、パス、引数、ツール名はすべてプレースホルダーであり、実際のサーバーがその値を受け付けることを意味しません。接続先の公式仕様で置き換えてください。

相対パスは起動場所で結果が変わるため、導入方法とパス方針を統一します。パッケージ実行時は配布元も審査してください。

Streamable HTTPの設定例

リモートサーバーへ接続する構造は次のようになります。

[mcp_servers.example_remote]url = "https://mcp.example.com/api"bearer_token_env_var = "EXAMPLE_MCP_TOKEN"enabled_tools = ["search", "read"]

urlは説明用です。実運用ではサーバー提供元の正式なHTTPSエンドポイントを指定します。bearer_token_env_varにはトークンそのものではなく、トークンを保持する環境変数名を指定します。この例なら、秘密の値はEXAMPLE_MCP_TOKENという環境変数側で管理し、TOMLへ書きません。

OAuthなど別の認証方式を使う場合は、サーバー公式仕様に従います。企業ネットワークではプロキシ、ファイアウォール、TLSも確認します。

起動・実行タイムアウトを理解する

OpenAI公式ドキュメントでは、サーバー起動待ちの既定値は10秒、ツール実行待ちの既定値は60秒です。startup_timeout_secとtool_timeout_secでサーバー単位に調整できます。

ただし、接続できないときに最初から値を大きくするのは適切ではありません。起動コマンドの誤り、依存不足、認証失敗、通信遮断を長い待ち時間で隠す可能性があるためです。まずログや設定を確認し、処理の性質上、本当に時間が必要だと確認できた場合だけ変更します。変更理由と期待時間を設定レビューに残しましょう。

STDIOとStreamable HTTPの選び方

どちらが常に優れているわけではありません。MCPサーバーが公式に対応する方式を前提に、運用主体、データ経路、認証、更新、監視の要件で選びます。

比較項目	STDIO	Streamable HTTP
接続先	端末上のローカルプロセス	URLで指定するリモートサーバー
主な設定	command、args	url、必要に応じた認証設定
向く構成	端末ごとに動かすローカル連携	組織で管理する共有サービス
主な障害点	パス、実行権限、依存関係、起動時間	DNS、プロキシ、TLS、認証、接続元制限
更新管理	各端末の実行物を管理	サーバー側と接続契約を管理
データ確認	ローカルプロセスが触れる範囲	ネットワーク越しに送る内容と保存方針

STDIOが候補になる場合

端末内のファイルやローカル開発環境と密接に連携し、MCPサーバーを各利用者が起動する構成ではSTDIOが候補です。通信経路がローカルでも、無条件に安全とは限りません。起動したプロセスはファイル、環境変数、他プロセスへアクセスできる可能性があります。

提供元、更新責任、脆弱性対応、削除手順を決め、ランタイムや起動コマンドを再現可能にします。

Streamable HTTPが候補になる場合

サーバーを組織側で一元管理したい場合、または提供サービスのリモートMCPエンドポイントへ接続する場合はStreamable HTTPが候補です。端末ごとのサーバー配布を減らせる一方、可用性、通信制御、認証、ログ、データ保持、障害対応をサーバー運用として設計する必要があります。

正式なホスト名、TLS、認証、送信対象、保存方針、停止窓口を確認します。ブラウザで開けてもMCP通信が正常とは限らないため、サーバーログも確認します。

企業向けの権限・承認設計

企業でCodex MCPを使うなら、サーバー単位の接続許可だけでなく、ツール単位の権限を設計します。一つのサーバーが検索、読み取り、更新、削除など複数のツールを公開する場合、接続を許可しただけでは権限が広すぎることがあるためです。

enabled_toolsを許可リストとして使う

必要なツールが決まっている場合は、enabled_toolsで利用対象を明示します。

[mcp_servers.example_approved]url = "https://mcp.example.com/api"enabled_tools = ["search", "read"]

ツール名は説明用です。実際の正確な名前を/mcpとサーバー公式情報で確認してください。許可リスト方式なら、サーバー側に新しいツールが追加されても、意図せず利用範囲へ入るリスクを抑えられます。最初は読み取り系の必要最小限から始め、業務上の必要性と復旧方法を確認してから拡大します。

disabled_toolsは補助的に使う

disabled_toolsは、サーバーが公開するツールのうち利用させないものを指定する設定です。多くのツールを使いながら一部を除外する用途があります。

[mcp_servers.example_limited]url = "https://mcp.example.com/api"disabled_tools = ["delete"]

除外リストでは、将来追加されたツールが利用対象になる可能性があります。厳格な統制が必要な環境ではenabled_toolsを基本とし、disabled_toolsは追加の防御として検討します。両方を使う場合の優先関係はOpenAI公式ドキュメントを確認し、テスト環境で実効状態を検証してください。

ツール承認モードをレビューする

CodexにはMCPツールの承認を制御するdefault_tools_approval_modeなどの設定があります。承認モードの選択肢や挙動は公式ドキュメントで確認し、未確認の値を推測で設定しないでください。

重要なのは、確認画面を減らすことを目的にしないことです。読み取り、外部送信、作成、更新、削除では影響が異なります。ツール名だけでなく、入力値、対象環境、変更範囲、取り消し可能性を基準に承認方針を決めます。自動承認を検討するなら、対象ツールとデータを限定し、ログ、停止方法、定期レビューを組み合わせます。

Codex本体の権限と重ねて守る

MCP設定に加え、Codex本体のサンドボックスと接続先アカウントも最小権限にします。検証用・読み取り専用から始め、必要な操作だけを追加し、異動や利用終了時の失効まで手順化してください。

共有設定をコードと同様にレビューする

CLI、IDE、デスクトップがMCP設定を共有するため、config.tomlの変更は一つの画面だけに閉じない場合があります。プロジェクト設定をGit管理するなら、Pull Requestで次を確認します。

• 追加先は承認済みのホストまたは実行物か
• 新しいツールは業務上必要か
• 書き込み・削除権限が過剰ではないか
• 秘密情報が差分や履歴に含まれていないか
• タイムアウト変更に根拠があるか
• 障害時の停止・ロールバック方法があるか

定期的にcodex mcp listと/mcpを棚卸しします。Codex全体の導入範囲はOpenAI Codexの使い方と企業導入ガイドで確認できます。

接続できないときのトラブル診断

障害時は、複数の設定を一度に変更せず、「設定範囲→起動または通信→認証→ツール制御→タイムアウト」の順に切り分けます。一つ変更するたびにcodex mcp listとTUIの/mcpで結果を確認すると、原因を特定しやすくなります。

1. 設定範囲とTOMLを確認する

最初に次を確認します。

• ~/.codex/config.tomlと.codex/config.tomlを取り違えていないか
• プロジェクト設定を使うフォルダーが信頼済みか
• 想定したユーザー、ホームディレクトリ、プロジェクトから起動しているか
• [mcp_servers.<name>]の階層やTOML構文が正しいか
• 同じ名前のサーバー設定が競合していないか
• CLI、IDE、デスクトップのどこで問題が起きているか

codex mcp listに表示されないなら、接続先を疑う前に設定の読み込み範囲を確認します。一覧にあるが/mcpで利用できない場合は、プロセスや通信へ進みます。

2. STDIOの起動を確認する

STDIOでは、commandに指定したプログラムを通常のターミナルから起動できるかを確認します。実行ファイルの存在、権限、引数、ランタイム、依存ファイル、作業ディレクトリを順に点検してください。

既定の起動待ちは10秒です。先に起動エラーや依存不足を確認し、シェルだけで動く場合はCodexから見えるPATHや環境変数を調べます。

3. Streamable HTTPの通信を確認する

リモート接続では、URLの誤記と対応トランスポートを確認します。その後にDNS、社内プロキシ、VPN、ファイアウォール、TLS証明書、接続元制限を切り分けます。

Codex側のエラー時刻とサーバーログを照合します。証明書検証やネットワーク制御を無条件に解除せず、承認済み経路を使ってください。

4. MCPサーバー側の認証を確認する

Codex本体の認証とMCPサーバーの認証を分けて考えます。OAuth対応ならcodex mcp login <server-name>の案内に従い、接続先と要求権限を確認します。Bearerトークン方式なら、bearer_token_env_varに指定した環境変数がCodexから見えるかを確認します。

以前は動いていた接続が失敗する場合は、トークンの期限切れ、認可の失効、利用者の異動、接続先ロールの変更も候補です。値をTOMLへ一時的に直書きして試すのではなく、定められた秘密情報管理と再認証手順を使ってください。

5. ツールの許可・拒否設定を確認する

サーバーは接続済みでも目的のツールが見えない場合、enabled_toolsとdisabled_toolsを確認します。ツール名の大文字・小文字、綴り、サーバー側での名称変更、許可リストからの漏れを点検します。

問題の切り分けを理由に、本番環境で全ツールを恒久的に許可しないでください。検証環境で正確なツール名を確認し、必要な項目だけ設定へ追加します。表示されたツールが想定より多い場合も、作業を進めず許可リストを見直します。

6. ツール実行時間を確認する

接続は成功するが処理中に失敗する場合、既定のツール実行待ち60秒に達していないかを確認します。サーバーログで処理開始、外部API待ち、完了または失敗の時刻を追い、処理そのものが遅いのか、応答が返らないのかを分けます。

必要性を確認してからtool_timeout_secを調整し、値を延ばすだけで根本原因を放置しないようにします。

症状	最初に見る場所	次の確認
一覧にサーバーがない	設定ファイルのパス、信頼状態、TOML	起動ユーザーと作業ディレクトリ
STDIOが起動しない	command、args、実行権限	依存関係、環境変数、10秒の起動待ち
HTTPへ接続できない	URL、DNS、プロキシ、TLS	認証、接続元制限、サーバーログ
接続済みだがツールがない	enabled_tools、disabled_tools	ツール名変更、サーバー側公開設定
ツールが途中で失敗する	サーバーログ、処理時間	認証期限、60秒の実行待ち
別の画面にも設定が出る	共有されるconfig.toml	CLI・IDE・デスクトップへの影響

Codex MCPのよくある質問

Q. Codex MCPの設定ファイルはどこですか？

ユーザー設定は~/.codex/config.tomlです。特定プロジェクトだけで使う設定は、信頼済みプロジェクトの.codex/config.tomlへ置けます。プロジェクト設定は共有される可能性があるため、トークンやAPIキーなどの秘密情報を直接書かないでください。

Q. codex mcpとTUIの/mcpは何が違いますか？

codex mcp add/list/loginは通常のターミナルなどのシェルで実行し、MCP設定の追加、一覧、認証に使います。/mcpはCodexの対話TUI内で実行し、現在認識されているサーバーやツールを確認します。設定と実状態の両方を見るため、codex mcp listと/mcpを併用します。

Q. STDIOとStreamable HTTPはどう選びますか？

まずMCPサーバーが公式に対応する方式を選びます。端末上のローカルプロセスを起動するならSTDIO、正式なリモートURLへ接続するならStreamable HTTPです。さらに、実行物の配布、更新、通信経路、認証、ログ、データ保持といった組織要件で判断してください。

Q. MCPサーバーを追加したのにツールが表示されない原因は何ですか？

設定ファイルの場所、プロジェクトの信頼状態、TOML構文、STDIOプロセスの起動、HTTP通信、MCP側認証、enabled_toolsとdisabled_toolsを順に確認します。codex mcp listに設定があるかを見た後、TUIの/mcpでセッションからの認識状態を確認してください。

Q. トークンをconfig.tomlへ直接書いてもよいですか？

推奨できません。Bearerトークンを使う場合はbearer_token_env_varへ環境変数名を設定し、値そのものをTOMLやGit履歴から分離します。OAuth対応なら公式のログイン導線を使い、組織の秘密情報管理、発行、更新、失効手順に従ってください。

まとめ

Codex MCPを導入する基本手順は、codex mcp --helpで利用環境を確認し、codex mcp addで追加、codex mcp listで設定を確認し、必要ならcodex mcp loginで認証した後、TUIの/mcpでサーバーとツールの実状態を確認する流れです。

設定は~/.codex/config.tomlと、信頼済みプロジェクトの.codex/config.tomlを目的に応じて使い分けます。接続方式はSTDIOとStreamable HTTPの2つです。ローカルかリモートかだけで決めず、提供元、実行物、通信先、認証、データ経路、更新、監視まで確認してください。

安全運用では、enabled_toolsによる許可リストを基本にし、disabled_tools、ツール承認設定、Codex本体の権限、接続先アカウントの最小権限を重ねます。CLI、IDE、デスクトップで設定が共有されることを踏まえ、変更をコードと同様にレビューし、不要な接続と認証は廃止します。

MCPを含むAI活用を個人の設定で終わらせず、権限、監査、データ管理、業務フローまで企業単位で整備したい場合は、NexaのAI顧問へ相談するをご利用ください。