Codex│MCPサーバーの追加方法｜codex mcp addとconfig.tomlの書き方

2026年9月29日2026年10月27日

Codex に MCP サーバーを足すと、外のツールやデータを Codex から使えるようになります。

コマンドのサーバー：codex mcp add 名前 -- 起動するコマンド
URL のサーバー：codex mcp add 名前 --url https://… --bearer-token-env-var 変数名
通常は~/.codex/config.tomlの[mcp_servers.名前]に保存。CODEX_HOMEを変えた場合はその設定フォルダーを使う
同じCodexホストと設定フォルダーを使うCLI・デスクトップ・IDE拡張で設定を共有する

2026年10月23日に公式MCP資料とWindows側のcodex mcp add --helpを再照合しました。以下の追加・削除・画面の記録は過去の確認で、今回の接続試験ではありません。

手元の確認は、Codex CLI 0.158.0 で、ふだんの設定に触れないよう、練習用の設定フォルダー（CODEX_HOME=C:\demo\codex-mcp）を使って行いました。

追加して、config.tomlの中身を見た

$env:CODEX_HOME = "C:\demo\codex-mcp"
codex mcp add everything -- npx -y @modelcontextprotocol/server-everything
codex mcp add docs --url https://example.com/mcp --bearer-token-env-var DOCS_TOKEN

Added global MCP server 'everything'.
Added global MCP server 'docs'.

config.toml には、次のように書かれました。

[mcp_servers.everything]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-everything"]

[mcp_servers.docs]
url = "https://example.com/mcp"
bearer_token_env_var = "DOCS_TOKEN"

このbearer_token_env_var方式ではトークン本体でなく変数名DOCS_TOKENを保存します。値はCodexが起動する環境から読み取れる必要があります。example.com/mcpは書式確認用のダミーURLです。追加成功や一覧のenabled表示だけでは、接続・認証・ツール呼出しの成功を確認できません。

HTTPサーバーの--bearer-token-env-varは任意で、サーバーが指定する認証方式に合わせて使います。

認証不要のサーバーならcodex mcp add 名前 --url 実際のURLで登録でき、OAuthを使うサーバーでは登録後にcodex mcp login 名前を実行して案内に従います。

登録後はCodexの/mcpで接続状態を確認し、提供されている読み取り用ツールで期待する結果を取得できるか確認してください。

一覧・確認・削除

codex mcp list

Name        Command  Args                                        Env  Cwd  Status   Auth
everything  npx      -y @modelcontextprotocol/server-everything  -    -    enabled  Unsupported

Name  Url                      Bearer Token Env Var  Status   Auth
docs  https://example.com/mcp  DOCS_TOKEN            enabled  Bearer token

codex mcp get everything

everything
  enabled: true
  transport: stdio
  command: npx
  args: -y @modelcontextprotocol/server-everything
  cwd: -
  env: -
  remove: codex mcp remove everything

codex mcp remove docs

Removed global MCP server 'docs'.

削除すると、config.toml から [mcp_servers.docs] の表が消えました。

コマンド	働き
codex mcp add	追加（`--env` でサーバーに渡す環境変数、`--url` で HTTP）
codex mcp list / get	一覧・1件の表示（`--json` も可）
codex mcp remove	削除
codex mcp login / logout	OAuth に対応した HTTP サーバーのログイン・ログアウト

codex mcp --help と公式ドキュメントをもとに作成

Windows PowerShellでcodex --versionとcodex mcp --helpを実行した結果。codex-cli 0.160.0、コマンドの一覧にlist、get、add、remove、login、logout、helpが並ぶ — 2026-10-17 20:40（日本時間）撮影。Windows PowerShell 5.1、Windows 11 Pro (10.0.26200)。`codex mcp --help` の出力の前半。

2026年10月17日に、この PC の Codex CLI（0.160.0）で codex mcp --help を表示したところです。

Commands の欄に list・get・add・remove・login・logout が並び、上の表のコマンドと一致しました。

codex mcp add --help では、--env は STDIO のサーバーだけ、--bearer-token-env-var は HTTP のサーバーだけに使えると表示されました。

追加・一覧・削除は0.158.0時の記録です。2026年10月23日のaddヘルプでもSTDIO用--envとHTTP用--bearer-token-env-varの区別を確認しましたが、接続・認証の再試験はしていません。

config.tomlの主な項目

項目	意味
command・args	起動するコマンドと引数（STDIO）
env	サーバーに設定する環境変数
env_vars	手元の環境から引き継ぐ変数の名前
url	HTTP のサーバーの URL
bearer_token_env_var	ベアラートークンを入れた環境変数の名前
startup_timeout_sec	起動の待ち時間（初期値10秒）
tool_timeout_sec	ツールの実行の待ち時間（初期値60秒）
enabled = false	消さずに止める
enabled_tools・disabled_tools	使うツール・使わないツール

OpenAI「Model Context Protocol」（Codex）をもとに作成

プロジェクトごとの設定は .codex/config.toml に書けますが、信頼したプロジェクトでだけ読まれます。

config.toml のほかの項目は、Codexのconfig.tomlの設定一覧で紹介しています。

デスクトップアプリの設定画面で見る

以下は2026年10月17日のWindowsアプリで確認した画面です。メニュー名・位置は版によって変わるため、現在も同じ配置とは限りません。

左下のアカウントのアイコンから［設定］を開き、左の一覧の［プラグイン］を選んで、上の［MCP］のタブに切り替えます。

Codexデスクトップアプリの設定のプラグインの画面でMCPのタブを開いたところ。サーバーの欄に登録済みのサーバーが3つ並び、それぞれに歯車とスイッチがある。その下にプラグインから、MCPアプリの欄。右上にディレクトリを参照と追加のボタン — 2026-10-17 20:39（日本時間）撮影。Codex デスクトップアプリ（Windows、パッケージ版 26.1013.3656.0）、Windows 11 Pro (10.0.26200)。設定の［プラグイン］で［MCP］のタブを開いたところ。登録済みのサーバーの名前はぼかしています。

［サーバー］の欄に登録済みのサーバーが1行ずつ並び、右に歯車とスイッチがあります。

今回は歯車もスイッチも押していないので、スイッチと config.toml の enabled の対応は確かめていません。

右上の［追加］を押すと、［プラグインを作成］［マーケットプレイスを追加］［MCP サーバーを追加］の3つが出ます。

［MCP サーバーを追加］を選ぶと、「カスタム MCP に接続する」という入力画面が開きます。

追加からMCPサーバーを追加を選んだ画面。カスタムMCPに接続するの入力欄で、名前、タイプはSTDIO、起動用コマンド、引数、環境変数のキーと値、環境変数パススルー、作業ディレクトリ、右下に保存するのボタン — 2026-10-17 20:39（日本時間）撮影。Codex デスクトップアプリ（Windows、パッケージ版 26.1013.3656.0）、Windows 11 Pro (10.0.26200)。［追加］→［MCP サーバーを追加］で開く入力画面（タイプは STDIO）。何も入力せず、保存していません。

タイプが STDIO のときは、起動用コマンド・引数・環境変数・環境変数パススルー・作業ディレクトリの欄が並びます。

同じ入力画面でタイプをストリーミング可能なHTTPにしたところ。URL、Bearerトークン環境変数、ヘッダーのキーと値、環境変数からのヘッダーの欄が並ぶ — 2026-10-17 20:39（日本時間）撮影。Codex デスクトップアプリ（Windows、パッケージ版 26.1013.3656.0）、Windows 11 Pro (10.0.26200)。タイプを「ストリーミング可能な HTTP」にしたときの入力欄。保存していません。

タイプを「ストリーミング可能な HTTP」に切り替えると、URL・Bearer トークン環境変数・ヘッダー・環境変数からのヘッダーの欄に変わります。

「Bearer トークン環境変数」の欄の見本は MCP_BEARER_TOKEN で、ここでもトークンそのものではなく環境変数の名前を入れる作りです。

欄の並びは、上の表の command・args・env・env_vars・url・bearer_token_env_var に近い内容です。

どちらの画面も入力・保存はしていないので、保存したときに config.toml へどう書かれるかは確かめていません。

現在の公式手順では、デスクトップアプリの設定からMCP serversを開いて追加し、保存後にRestartを選びます。

OAuthが必要なサーバーではAuthenticateから認証し、IDE拡張では保存後にRestart extensionを選ぶ手順です。

上の画像は過去の配置を示すため、表示が異なる場合は公式MCP接続手順の利用中クライアントの説明と照合してください。

起動しないとき

まず起動コマンド・PATH・認証・ログを確認し、時間不足が原因ならstartup_timeout_secを調整する
Codex の画面で /mcp を開き、有効なサーバーを確かめる
npx のサーバーは、Node.js が入っていて PATH が通っているか確かめる

Claude Code での追加は、Claude CodeのMCPサーバーの追加で紹介しています。

まとめ

codex mcp add 名前 -- コマンド、または --url
設定は config.toml の [mcp_servers.名前]
トークンは環境変数の名前で渡す（bearer_token_env_var）
list・get・remove で管理する

参考：OpenAI「Model Context Protocol」「Codex CLI reference」（2026年9月29日に確認）と、Codex CLI 0.158.0 での実行結果。

よくある質問：CodexにMCPサーバーを追加するとき

CodexにMCPサーバーを追加するには、どうしますか？

コマンドで起動するサーバーは codex mcp add 名前 -- 起動するコマンド、URLのサーバーは codex mcp add 名前 --url https://… --bearer-token-env-var 変数名 で追加します。

通常は~/.codex/config.tomlの[mcp_servers.名前]に保存され、CODEX_HOMEを指定した場合はそのフォルダーを使います。

トークンは、config.toml にそのまま書かれますか？

記事のbearer_token_env_var方式では、トークン本体を保存しません。ただしenvや固定ヘッダーなどに秘密を直接指定すれば設定へ保存されるため、config.toml全体が秘密を含まないとは限りません。

トークンそのものではなく、トークンを入れた環境変数の名前（記事の例では DOCS_TOKEN）が書かれます。

URLのサーバーでは、bearer_token_env_var に環境変数の名前を指定します。

追加したサーバーを、一覧・確認・削除するには？

codex mcp list で一覧、codex mcp get で1件の表示ができ（--json も可）、codex mcp remove で削除します。

削除すると、config.toml から [mcp_servers.名前] の表が消えます。

OAuthに対応したHTTPサーバーのログイン・ログアウトは、codex mcp login / logout です。

CLI、デスクトップアプリ、IDEで、設定は別々ですか？

同じ設定を使います。

同じCodexホストと設定フォルダーを使うローカルクライアントでは共通です。別ホストや別のCODEX_HOME、Webのホスト型接続まで自動で同期される意味ではありません。

config.toml の主な項目には、何がありますか？

command・args（起動するコマンドと引数）、env（サーバーに設定する環境変数）、env_vars（手元の環境から引き継ぐ変数の名前）、url（HTTPサーバーのURL）、bearer_token_env_var、startup_timeout_sec（起動の待ち時間、初期値10秒）、tool_timeout_sec（ツールの実行の待ち時間、初期値60秒）、enabled = false（消さずに止める）、enabled_tools・disabled_tools（使うツール・使わないツール）などです。