MCP 服务器发布工具定义并执行工具调用。Agents API 发现工具、调用服务器，并将结果返回给智能体。您的应用无需处理每次调用。
根据服务器的可访问范围，选择从何处建立连接：
| 连接 | 运行位置 | 是否需要环境 |
|---|---|---|
使用 connection_origin: "service" 的 HTTP 连接（默认） | OpenAI | 否 |
使用 connection_origin: "environment" 的 HTTP 连接 | 您的会话环境 | 是 |
| 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。将以下条目添加到 agent.tools，并将 URL 替换为您的环境可以访问的地址：
{
"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选择其中一个。 - Stdio 凭证： 在环境中提供凭证值，并在
transport.env_vars中列出对应的变量名。在环境中运行的代码可以读取这些值。自托管会话不接受在transport.env中内联提供的值。
例如，HTTP 传输配置可以包含一个 Bearer Token 和另一个请求头：
{
"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。对于从环境建立的连接，请检查执行器是否已连接，以及其网络是否能够访问服务器。 - 凭证： 检查 Token 或请求头。如果使用保管库，请检查凭证是否与服务器 URL 匹配。
- 可执行文件和依赖项： 检查配置的命令是否能在环境中运行。
- 工作目录： 对于内联 stdio 配置，请将
cwd设置为现有目录的绝对路径。