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。将以下配置项添加到 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 时,由执行器启动服务器进程。请先在环境中安装服务器及其依赖项。
要运行 Python 版客户查询示例,请安装 MCP SDK。
python3 -m venv /workspace/mcp-demo
/workspace/mcp-demo/bin/python -m pip install 'mcp==1.26.0'将 Python 服务器脚本保存为 /workspace/lookup_mcp.py。
如果使用 Ruby,请安装 1.10.0 版的 mcp gem,并将 Ruby 服务器脚本保存为 /workspace/lookup_mcp.rb。此示例已在 Ruby 3.3 上通过测试。
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。
以下配置会启动 Python 服务器。
如果使用 Ruby,请将 transport.command 设置为 Ruby 可执行文件的绝对路径,并将 transport.args 设置为 ["/workspace/lookup_mcp.rb", "stdio"]。请在该 Ruby 运行时中安装此 gem。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将凭据库关联到会话。只有从 OpenAI 发起的连接才能使用凭据库进行 MCP 身份验证。系统会根据服务器 URL 匹配凭据。如果有多个匹配项,请使用credential_id指定其中一个。 - stdio 凭据。 在环境中设置相应的环境变量,并在
transport.env_vars中列出变量名。在该环境中运行的代码可以读取这些值。自托管会话不接受在transport.env中直接填写的值。
例如,HTTP 传输配置可以包含持有者令牌和另一个请求头。
{
"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 配置字段,请参阅创建会话 API 参考。
排查连接问题
如果必需的服务器无法初始化,请查看 agent.session.turn.failed 中的错误信息。对于 stdio 服务器,还应检查 MCP 进程日志。
- 网络访问。 检查 URL 和
connection_origin。如果从环境发起连接,请确认执行器已连接,并且可以通过执行器所在的网络访问服务器。 - 凭据。 检查令牌或请求头。如果使用凭据库,请确认凭据与服务器 URL 匹配。
- 可执行文件和依赖项。 确认配置的命令可以在环境中运行。
- 工作目录。 在内联 stdio 配置中,将
cwd设为现有目录的绝对路径。