MCP サーバーはツール定義を公開し、ツール呼び出しを実行します。Agents API はツールを検出し、サーバーを呼び出して、結果をエージェントに返します。アプリケーションで個々の呼び出しを処理する必要はありません。
サーバーにアクセスできる場所に応じて、接続元を選択します。
| 接続方式 | 接続元 | 環境の要否 |
|---|---|---|
connection_origin: "service" を指定した HTTP（デフォルト） | OpenAI | 不要 |
connection_origin: "environment" を指定した HTTP | セッションの環境 | 必要 |
| stdio | セッションの環境内のプロセス | 必要 |
OpenAI からの接続
agent.tools に HTTP MCP サーバーを追加します。サーバーは 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
}ここで localhost の URL が指すのは、セッションの環境です。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 を検索するようエージェントに依頼するメッセージを送信します。ツールは、pro プランを利用している Example Customer を返します。
OpenAI ホスト型の stdio MCP では、ネットワークポリシーを省略するか、enabled に設定します。これらの接続では、ネットワークポリシーの disabled と restricted はサポートされていません。
認証の追加
匿名アクセスを許可するサーバーでは、認証フィールドと vault_ids を省略します。それ以外の場合は、接続に使用する認証情報の取得元を選択します。
- 単一セッション用の HTTP 認証情報： セッションの作成時に
transport.authorizationまたはtransport.headersを設定します。Agents API はこれらの値を暗号化し、返されるセッションリソースには含めません。 - 再利用可能な HTTP 認証情報： 認証情報をボールトに保存し、
vault_idsを通じてボールトを接続します。ボールトは OpenAI からの接続にのみ適用されます。認証情報はサーバーの URL と照合されます。複数の認証情報が一致する場合は、credential_idを使用して 1 つ選択します。 - 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 の取得元には、インライン構成または条件に一致するボールトの認証情報のどちらか一方を使用します。ボールトによる認証には、ほかのヘッダーを併用できます。環境を接続元とする HTTP 接続ではボールトの認証情報は使用されないため、インライン認証または信頼できるプロキシを使用してください。
再利用可能なエージェント定義、プラグインのアーカイブ、ログにはシークレットを含めないでください。エージェントが生成したコードから認証情報にアクセスできないようにするには、環境の外部で認証情報を提供する信頼できるプロキシまたはサーバーを使用します。
ツールへのアクセスと起動の制御
allowed_tools を設定して、エージェントが検出して呼び出せるツールを制限します。サーバーを初期化できない場合にターンを失敗させるには、required: true を設定します。デフォルトでは初期化の成功は必須ではありません。
MCP のすべての構成フィールドについては、セッション作成のリファレンスを参照してください。
接続のトラブルシューティング
必須のサーバーを初期化できない場合は、agent.session.turn.failed のエラーを確認します。stdio サーバーの場合は、MCP プロセスのログも確認してください。
- ネットワークアクセス： URL と
connection_originを確認します。環境からの接続では、エグゼキューターが接続されていることと、そのネットワークからサーバーにアクセスできることを確認してください。 - 認証情報： トークンまたはヘッダーを確認します。ボールトを使用する場合は、認証情報がサーバーの URL に一致することを確認してください。
- 実行ファイルと依存関係： 設定したコマンドが環境内で実行できることを確認してください。
- 作業ディレクトリ： インラインの stdio 構成では、
cwdに既存のディレクトリの絶対パスを指定してください。