AI Hub

Codex MCP設定方法｜外部ツール連携の手順を解説

公開:

#MCP #設定

Codexでは、codex mcp addコマンドを使う方法と、config.tomlに直接記述する方法の2通りで、MCP(Model Context Protocol)サーバーを追加できます。この記事では、両方の設定方法の具体的なコマンド・記述例と、追加後の動作確認手順、セキュリティ上の注意点までをまとめて解説します。ドキュメント検索やデザインツールなど、外部サービスと連携させてCodexの作業範囲を広げたい方向けの内容です。

前提・動作環境

対象はCodex CLI(ターミナル版)です。事前にインストールとサインインを済ませておいてください。導入手順や全体像は「Codexの使い方完全ガイド」で解説しています。ここで紹介するMCPの設定は~/.codex/config.tomlに保存され、Codex CLI・VS Code拡張・ChatGPTデスクトップアプリで共有されます。config.tomlの基本的な書き方は「config.toml設定ガイド」を参照してください。

Codexは頻繁にアップデートされ、コマンドやオプションが変更されることがあります。本記事は執筆時点の一般的な仕様です。手元の挙動と異なる場合は、公式サイト(developers.openai.com/codex)で最新情報を確認してください。

CodexにおけるMCPとは

MCPは、AIエージェントが外部のツールやデータソースに接続するためのオープンな標準規格です。MCPサーバーを追加すると、Codexが自分でドキュメントを検索したり外部APIを呼び出したりできるようになります。たとえば「最新のFigmaデザインを見て実装して」といった指示を、実際に外部ツールへアクセスしながら実行できるイメージです。設定はすべてconfig.tomlの[mcp_servers]テーブルに集約されており、CLIコマンドはこのテーブルを操作するショートカットという位置づけになっています。

codex mcp addコマンドで設定する

ローカルプロセスとして起動するstdioサーバーは、次のようにコマンドで追加します。サーバーに渡す引数の前には--(ダブルハイフン)を置いて区切ります。

codex mcp add context7 -- npx -y @upstash/context7-mcp

環境変数を渡したい場合は--envオプションを使います。

codex mcp add github --env GITHUB_TOKEN=YOUR_TOKEN -- npx -y @modelcontextprotocol/server-github

クラウド上で動くHTTPサーバーには--urlを指定します。

codex mcp add openai-docs --url https://developers.openai.com/mcp

登録したサーバーはcodex mcp listで一覧表示でき、削除はcodex mcp remove <name>で行います。コマンドの全体はcodex mcp --helpで確認できます。

config.tomlに直接記述して設定する

~/.codex/config.tomlを直接編集して、[mcp_servers.<サーバー名>]テーブルを追記する方法も使えます。stdioサーバーの場合はcommandとargsを指定します。

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.context7.env]
MY_ENV_VAR = "value"

HTTPサーバーの場合はurlを指定し、認証にはトークンを直書きせず環境変数経由で渡します。

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

startup_timeout_sec(起動タイムアウト、既定10秒)やenabled_tools(利用を許可するツールの絞り込み)といったオプションも用意されており、コマンドでは設定できない項目もconfig.tomlなら調整できます。信頼済みプロジェクトに限り、リポジトリ直下の.codex/config.tomlにも同じ書式でチーム内共有用の設定を置けます。

実用例:定番MCPサーバーを追加する

ドキュメント検索サーバーをコマンドで追加する。ライブラリの最新ドキュメントを参照させたい場合は、Context7のようなstdioサーバーをコマンド1行で追加できます。

codex mcp add context7 -- npx -y @upstash/context7-mcp
Added MCP server "context7" (stdio)

デザインツールをconfig.tomlで追加する。FigmaのようなHTTPサーバーは、OAuthトークンをあらかじめ環境変数に設定したうえで、config.tomlに直接記述する方が見通しがよくなります。

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

「Figmaのデザインを見て、対応するコンポーネントを実装して」のように、外部サービスの情報を踏まえた指示が出せるようになります。

動作確認の方法

設定後は、次のコマンドで登録状況とステータスを確認します。

codex mcp list
context7   stdio   connected
figma      http    needs authentication

needs authenticationと表示されるOAuth対応サーバーは、Codexを起動してから認証フローを通す必要があります。実際にCodexを起動し「利用可能なツールを教えて」のように尋ねると、追加したサーバーのツールが認識されているか確認できます。なお、Claude Codeにも同様のMCP連携機能があり、claude mcp addコマンドとスコープ管理で設定する仕組みです。設定ファイルの場所や考え方が異なるため、Claude Codeも併用している方は「Claude CodeのMCP設定方法」で違いを確認しておくとよいでしょう。

セキュリティ上の注意点

つまずきポイント/よくあるエラー

よくある質問

stdioとHTTP、どちらのサーバーを選べばよいですか?

ローカルのファイルやコマンドラインツールと連携する場合はstdio、クラウド上のサービスに接続する場合はHTTP(url指定)を使います。迷う場合は、利用したいサーバーの配布元が案内している方式に合わせてください。

コマンドとconfig.tomlの直接編集、どちらを使うべきですか?

サーバーを1つ追加するだけならコマンドが手軽です。タイムアウト値やツールの絞り込みなど細かい設定や、複数サーバーのまとめ管理をしたい場合はconfig.tomlの直接編集が向いています。

追加したMCPサーバーが認識されません

codex mcp listで登録の有無を確認し、されていればCodexを再起動してください。config.tomlを編集した場合は、TOMLの構文ミス(引用符の閉じ忘れなど)がないかもあわせて確認しましょう。

まとめ

CodexのMCP連携は、codex mcp addコマンドで手軽に追加するか、config.tomlの[mcp_servers]テーブルを直接編集して細かく設定するかを、用途に応じて使い分けられます。追加後はcodex mcp listで状態を確認し、認証が必要なサーバーは忘れずに認証を済ませましょう。信頼できるサーバーだけを追加し、認証情報は環境変数経由で渡すことをおすすめします。設定ファイル全体の書き方は「config.toml設定ガイド」、Codex全体の使い方は「Codexの使い方完全ガイド」もあわせてご覧ください。