MCP サーバーはツールの定義を公開し、呼び出されたツールを実行します。Agents API は利用可能なツールを検出し、サーバーを呼び出して結果をエージェントに返します。アプリケーション側で呼び出しを個別に処理する必要はありません。
サーバーにアクセスできる場所に応じて、接続元を選びます。
| 接続方式 | 接続元 | セッション環境の要否 |
|---|---|---|
HTTP（connection_origin: "service"、デフォルト） |
OpenAI | 不要 |
HTTP（connection_origin: "environment"） |
セッション環境 | 必要 |
| stdio | セッション環境内のプロセス | 必要 |
OpenAI からの接続
HTTP で通信する MCP サーバーを agent.tools に追加します。OpenAI からアクセスできるサーバーを指定してください。この接続方式は、セッション環境の有無にかかわらず利用できます。
たとえば、OpenAI ドキュメントの MCP サーバーは匿名アクセスを許可しています。
{
"type": "mcp",
"server_label": "openai_docs",
"transport": {
"type": "http",
"server_url": "https://developers.openai.com/mcp"
},
"connection_origin": "service",
"required": true
}
セッション環境からの接続
エグゼキューターを使う場合は、セッション環境から MCP サーバーに接続します。プライベートネットワーク上のサーバーや、セッション環境にインストールしたソフトウェアを利用する場合に適しています。
セッションの environment.type を self_hosted または openai_hosted に設定します。セルフホスト環境では、エージェントがツールを使用する前にエグゼキューターを接続してください。
HTTP での接続
すでに稼働しているサーバーには HTTP で接続します。次の設定の URL をセッション環境からアクセスできるアドレスに置き換え、agent.tools に追加します。
{
"type": "mcp",
"server_label": "internal_search",
"transport": {
"type": "http",
"server_url": "https://mcp.internal.example.com/search"
},
"connection_origin": "environment",
"required": true
}この設定では、URL の localhost はセッション環境を指します。connection_origin を省略すると、OpenAI から接続します。
stdio を使ったサーバーの起動
エグゼキューターからサーバープロセスを起動するには、stdio を使用します。あらかじめサーバーとその依存関係をセッション環境にインストールしてください。
次の顧客検索の例では、MCP SDK をインストールします。
python3 -m venv /workspace/mcp-demo
/workspace/mcp-demo/bin/python -m pip install 'mcp==1.26.0'サーバーのコードを /workspace/lookup_mcp.py に保存します。
import sys
from mcp.server.fastmcp import FastMCP
server = FastMCP("customer-lookup", host="127.0.0.1", port=8765, stateless_http=True)
@server.tool()
def get_customer(customer_id: str) -> dict:
"""Look up a customer in the example data."""
customers = {"123": {"name": "Example Customer", "plan": "pro"}}
return {"customer": customers.get(customer_id)}
if __name__ == "__main__":
transport = sys.argv[1] if len(sys.argv) > 1 else "streamable-http"
server.run(transport=transport)サーバーを agent.tools に追加します。スクリプトに渡す引数 stdio で通信方式を指定します。
{
"type": "mcp",
"server_label": "customer_lookup",
"transport": {
"type": "stdio",
"command": "/workspace/mcp-demo/bin/python",
"args": ["/workspace/lookup_mcp.py", "stdio"],
"cwd": "/workspace"
},
"required": true
}stdio では、command と絶対パスで指定した cwd が必須です。args は任意です。connection_origin は省略してください。
顧客 123 を検索するようエージェントにメッセージを送ります。ツールは顧客名として Example Customer、利用プランとして pro を返します。
OpenAI がホストする環境で stdio を使って MCP サーバーに接続する場合は、ネットワークポリシーを省略するか、enabled に設定してください。この接続方式では、ネットワークポリシーの disabled と restricted はサポートされていません。
認証の設定
匿名アクセスを許可するサーバーでは、認証用のフィールドと vault_ids を省略します。それ以外の場合は、接続に使用する認証情報の取得元を選びます。
- 単一セッション用の HTTP 認証情報： セッションの作成時に
transport.authorizationまたはtransport.headersを設定します。Agents API はこれらの値を暗号化し、レスポンスのセッションリソースから除外します。 - 再利用可能な HTTP 認証情報： MCP の認証情報をボールトに保存し、
vault_idsでボールトをセッションに接続します。ボールトを使った MCP 認証を利用できるのは、OpenAI から接続する場合のみです。サーバーの URL に一致する認証情報が使用されます。複数の認証情報が一致する場合は、credential_idで使用するものを指定します。 - stdio の認証情報： 環境変数に値を設定し、変数名を
transport.env_varsに列挙します。環境内で実行されるコードは、これらの値を読み取ることができます。セルフホストのセッションでは、transport.envに値を直接指定できません。
たとえば、HTTP トランスポートには Bearer トークンと追加のヘッダーを指定できます。
{
"type": "http",
"server_url": "https://mcp.example.com/mcp",
"authorization": "Bearer YOUR_MCP_ACCESS_TOKEN",
"headers": { "X-Tenant-ID": "tenant_123" }
}Authorization の値は、設定に直接指定するか、サーバーの URL に一致するボールトの認証情報から取得するか、どちらか一方を選んでください。ボールト認証には他のヘッダーを併用できます。セッション環境からの HTTP 接続ではボールトの認証情報を使用しないため、認証情報を設定に直接指定するか、信頼できるプロキシを使用してください。
再利用するエージェント定義、プラグインのアーカイブ、ログにはシークレットを含めないでください。エージェントが生成したコードから認証情報にアクセスできないようにするには、環境の外部で認証情報を提供する信頼できるプロキシまたはサーバーを使用します。
ツールへのアクセスと起動時の動作の制御
allowed_tools を設定すると、エージェントが検出して呼び出せるツールを制限できます。required: true を設定すると、サーバーを初期化できなかった場合にターンが失敗します。デフォルトでは、初期化の成功は必須ではありません。
MCP の設定フィールドの一覧は、セッション作成のリファレンスを参照してください。
接続のトラブルシューティング
必須のサーバーを初期化できない場合は、agent.session.turn.failed のエラーを確認してください。stdio サーバーの場合は、MCP プロセスのログも確認してください。
- ネットワークアクセス： URL と
connection_originを確認してください。セッション環境から接続する場合は、エグゼキューターが接続されていることと、そのネットワークからサーバーにアクセスできることを確認してください。 - 認証情報： トークンまたはヘッダーを確認してください。ボールトを使用する場合は、認証情報がサーバーの URL に一致することを確認してください。
- 実行ファイルと依存関係： 設定したコマンドを環境内で実行できることを確認してください。
- 作業ディレクトリ： stdio の設定をインラインで指定する場合は、既存のディレクトリの絶対パスを
cwdに指定してください。