在对话中使用外部工具
千问云通过 Responses API 支持 Model Context Protocol (MCP)。在
以下示例接入网页解析(WebParser)MCP 服务,展示如何通过 Responses API 调用 MCP 工具。需要先在百炼控制台开通网页解析(WebParser)MCP 服务。
查找与开通更多 MCP 服务,请参见MCP 服务。
典型的响应包含两个阶段:工具列举(模型发现可用工具)和最终输出(模型使用工具并返回结果)。
工具列举输出
响应的
工具调用与最终输出
发现工具后,模型调用工具并生成最终的文本响应。
错误处理
如果模型无法连接 MCP 服务器,响应的
常见原因包括
MCP 工具调用可能涉及与外部服务器的多次往返通信。启用流式输出可实时接收工具调用进度和模型响应。在请求中添加
除标准流式事件外,MCP 响应还会产生以下事件类型:
带认证的配置示例:
MCP 仅通过 Responses API 提供。以下模型支持 MCP 工具调用:
使用 MCP 时涉及两类费用:
tools 参数中传入一个或多个 MCP 服务器配置,模型会连接这些服务器,发现可用工具,并根据需要调用它们来完成请求。
快速开始
以下示例接入网页解析(WebParser)MCP 服务,展示如何通过 Responses API 调用 MCP 工具。需要先在百炼控制台开通网页解析(WebParser)MCP 服务。
查找与开通更多 MCP 服务,请参见MCP 服务。
请将示例代码中 MCP 工具配置的
server_url 和 headers 替换为您实际使用的 MCP 服务信息。- Python
- Node.js
- curl
工作原理
1
定义 MCP 工具配置
定义 MCP 工具配置,包括服务器的 SSE 端点和可选的认证头信息。
2
传入配置
在 Responses API 调用的
tools 参数中传入该配置。3
模型连接并发现工具
模型连接 MCP 服务器,发现可用工具,并调用它们来处理输入。
4
接收响应
响应包含模型的最终输出,其中包括 MCP 工具调用的结果。
MCP 服务器是第三方服务。请仅连接您信任的服务器。恶意 MCP 服务器可能返回有害内容、通过工具描述窃取数据,或产生意外费用。添加服务器前,请务必验证其来源。
仅支持使用 SSE 协议的 MCP 服务器,每次请求最多可配置 10 个。
响应结构
典型的响应包含两个阶段:工具列举(模型发现可用工具)和最终输出(模型使用工具并返回结果)。
工具列举输出
响应的 output 数组首先包含一个 mcp_list_tools 项,展示模型在 MCP 服务器上发现的工具:
output 数组包含每次工具调用对应的 mcp_call 项,以及一个包含综合回答的 message 项:
实际响应取决于 MCP 服务器抓取到的实时内容。Token 用量因请求而异。
status 为 "failed",顶层的 error 对象包含具体信息。output 数组为空。
server_url 无效和服务器超时。请检查 error.code 和 error.message 字段进行排查。
如果 MCP 服务器可达但认证失败,模型可能会静默跳过 MCP 工具,不使用它们直接响应。此时不会返回错误信息。
启用流式输出
MCP 工具调用可能涉及与外部服务器的多次往返通信。启用流式输出可实时接收工具调用进度和模型响应。在请求中添加 stream=True(Python)、stream: true(Node.js / curl)即可。
流式输出的实现细节、事件类型和代码示例,请参阅流式输出。
MCP 专属流式事件
除标准流式事件外,MCP 响应还会产生以下事件类型:
| 事件类型 | 说明 |
|---|---|
response.mcp_list_tools.done | MCP 服务器的工具发现已完成。 |
response.mcp_call.done | MCP 工具调用已完成并返回结果。 |
MCP 工具参数
| 参数 | 必填 | 说明 |
|---|---|---|
type | 是 | 固定值 "mcp"。 |
server_protocol | 是 | 通信协议,仅支持 "sse"。 |
server_label | 是 | MCP 服务器的简短标识。 |
server_description | 否 | 服务器功能的自然语言描述。清晰的描述有助于模型判断何时调用该服务器的工具,提高工具选择的准确性。建议为所有 MCP 服务器提供此参数。 |
server_url | 是 | MCP 服务器的 SSE 端点 URL。 |
headers | 否 | 连接 MCP 服务器时附带的 HTTP 头,例如用于认证的 Authorization。 |
支持的模型
MCP 仅通过 Responses API 提供。以下模型支持 MCP 工具调用:
| 模型系列 | 模型 ID |
|---|---|
| Qwen-Plus | qwen3.6-plus 系列, qwen3.5-plus 系列 |
| Qwen-Flash | qwen3.6-flash 系列, qwen3.5-flash 系列 |
| Qwen3.6 开源 | Qwen3.6 开源系列(qwen3.6-27b 除外) |
| Qwen3.5 开源 | Qwen3.5 开源系列 |
计费
使用 MCP 时涉及两类费用:
- 模型推理费用:根据模型的 Token 用量计费。
- MCP 服务器费用:按各 MCP 服务器提供商的计费规则收取。

