模型上下文协议（MCP）

openai.github.io 2026-07-07T09:13:40.344838

模型上下文协议（MCP）标准化了应用程序向语言模型暴露工具和上下文的方式。官方文档指出：

MCP 是一个开放协议，标准化了应用程序如何向 LLM（大语言模型）提供上下文。可以把 MCP 想象成 AI 应用程序的 USB-C 接口。正如 USB-C 提供了一种标准化方式将设备连接到各种外设和配件，MCP 提供了一种标准化方式将 AI 模型连接到不同的数据源和工具。

Agents Python SDK 支持多种 MCP 传输方式。这让你可以复用已有的 MCP 服务器，或者构建自己的服务器，将基于文件系统、HTTP 或连接器的工具暴露给 agent（智能体）。

选择 MCP 集成

在将 MCP 服务器接入智能体之前，需要决定工具调用应在何处执行，以及你可以使用哪些传输方式。下表总结了 Python SDK 支持的选项。

你的需求	推荐选项
让 OpenAI 的 Responses API 代表模型调用可公开访问的 MCP 服务器	托管 MCP 服务器工具，通过 `HostedMCPTool`
连接到本地或远程运行的 Streamable HTTP 服务器	Streamable HTTP MCP 服务器，通过 `MCPServerStreamableHttp`
与实现 HTTP 服务器发送事件（Server-Sent Events）的服务器通信	HTTP with SSE MCP 服务器，通过 `MCPServerSse`
启动本地进程并通过 stdin/stdout 通信	stdio MCP 服务器，通过 `MCPServerStdio`

以下各节将详细介绍每个选项、如何配置以及何时选择某种传输方式。

智能体级别的 MCP 配置

除了选择传输方式，你还可以通过设置 Agent.mcp_config 来调整 MCP 工具的准备工作。

from agents import Agent

模型上下文协议 (MCP) - OpenAI Agents SDK

agent = Agent(
    name="Assistant",
    mcp_servers=[server],
    mcp_config={
        # 尝试将 MCP 工具架构转换为严格的 JSON 模式。
        "convert_schemas_to_strict": True,
        # 如果为 None，MCP 工具故障将作为异常抛出，而非返回模型可见的错误文本。
        "failure_error_function": None,
        # 为本地 MCP 工具名称添加其服务器名称前缀。
        "include_server_in_tool_names": True,
    },
)

注意事项：

convert_schemas_to_strict 是尽力而为的。如果某个架构无法转换，则使用原始架构。
failure_error_function 控制 MCP 工具调用失败时如何向模型呈现错误信息。
当 failure_error_function 未设置时，SDK 使用默认的工具错误格式化器。
服务器级别的 failure_error_function 会覆盖该服务器的 Agent.mcp_config["failure_error_function"]。
include_server_in_tool_names 是可选启用的。启用后，每个本地 MCP 工具将以确定性的服务器前缀名称暴露给模型，这有助于避免多个 MCP 服务器发布同名工具时发生冲突。生成的名称符合 ASCII 安全规则，不超出函数工具名称长度限制，并且避免与同一 agent 上已有的本地函数工具和已启用的交接名称冲突。SDK 仍然会在原始服务器上调用原始的 MCP 工具名称。

在选择传输方式后，大多数集成需要进行相同的后续决策：

如何仅暴露工具的子集（工具过滤）。
服务器是否也提供可复用的提示（Prompts）。
list_tools() 是否应该被缓存（Caching）。
MCP 活动如何在追踪中显示（Tracing）。

对于本地 MCP 服务器（MCPServerStdio、MCPServerSse、MCPServerStreamableHttp），审批策略和每次调用的 _meta 负载也是共享的概念。Streamable HTTP 部分展示了最完整的示例，同样的模式也适用于其他本地传输方式。

1. 托管 MCP 服务器工具

查看原文