文档中心

AgentKit

MCP 接入

MCP 协议版本兼容性说明

MCP 协议版本用来约定客户端与服务端“怎么说话”（消息格式、能力声明、初始化方式、调用行为等）。当您调用 MCP 服务或 MCP 工具集时，需要选一个双方都支持的协议版本来完成通信。

MCP 支持的协议版本

不同协议版本在交互方式上可能存在差异。例如，MCP 2026-07-28相比旧版协议，演进为更适合网关和 Serverless 场景的“无状态调用模型”，因此在初始化、会话保持、多轮交互方式上与旧版不同。MCP 协议版本用于定义消息格式、能力声明、初始化方式和调用行为；Streamable HTTP 是消息传输方式，二者是不同概念。当前通过 Streamable HTTP 对外提供访问时，客户端仍需根据自身支持情况选择对应的 MCP 协议版本进行调用。

MCP 服务	MCP 工具集
2026-07-28 2025-11-25 2025-06-18 2025-03-26	2026-07-28 2025-11-25 2025-06-18 2025-03-26

注意

全量返回、语义检索、标签检索是 MCP 工具集的“工具匹配方式”，不代表不同的 MCP 协议版本。

MCP 2026-07-28 协议兼容性说明

AgentKit MCP 现已完成 MCP 2026-07-28 协议兼容性改造，改造后您仍可使用旧版协议调用 MCP 服务/MCP 工具集。

对于已有的 MCP 服务和 MCP 工具集，可采用以下低改造成本的兼容方案：无需修改存量 MCP 服务，只需将存量 MCP 服务添加至 MCP 工具集，即可通过 MCP 工具集使用新协议能力。

MCP 工具集新协议兼容规则

存量 MCP 工具集兼容逻辑

存量无影响规则：使用 MCP 2026-07-28 无状态协议调用 MCP 工具集时，可以访问工具集内已有的工具，无需关注各工具实际使用的协议。原有调用方式仍可继续使用。

下游工具兼容能力：MCP 工具集支持添加采用有状态或无状态调用方式的下游工具。调用 MCP 工具集时，客户端无需感知下游工具实际使用的协议或会话机制。

客户端改造要求：客户端可以使用有状态或无状态调用方式访问 MCP 工具集。切换至 MCP 2026-07-28 协议时，只需按照该协议调整客户端的调用逻辑，无需修改 MCP 工具集内已有工具所使用的协议。

MRTR 工具调用要求：如果需要调用支持 MRTR（Multi Round-Trip Requests，多轮往返请求）的工具，客户端必须使用 MCP 2026-07-28 协议向 MCP 工具集发起请求。

注意

是否支持 MRTR 取决于目标工具的能力。

MCP 服务不同接入场景的改造要求

存量 MCP 服务兼容逻辑

存量 MCP 服务不会自动升级协议版本，其协议支持能力由您自行实现的后端逻辑决定。如需使用 MCP 2026-07-28 协议调用已有 MCP 服务，可以选择以下任一方式：

方法一：直接调用已有 MCP 服务，请根据不同 MCP 服务的创建方式进行改造。

方法二：无需做任何改造，仅需把 MCP 服务加入 MCP 工具集，使用新协议通过 MCP 工具集调用已有 MCP 服务中的工具。MCP 工具集的新协议兼容覆盖范围，大于用户直接调用 MCP 服务场景的兼容范围。

不同创建方式改造要求

部署 MCP 服务

如果需要使用新协议调用使用镜像部署的已有 MCP 服务，您需要先完成镜像的新协议适配改造并发布镜像。

在 AgentKit 控制台 MCP 服务列表中，单击目标 MCP 名称，在基本信息页签单击“后端服务”部分的“编辑”按钮。

单击镜像输入框，然后选择已改造并发布的镜像，单击“确定”按钮，更新镜像并触发滚动重启即可生效

导入 MCP 服务：如果需要使用新协议调用已导入的 MCP 服务，您需要自行完成后端服务的新协议适配。适配完成后，即可使用新协议调用该 MCP 服务中的工具。

HTTP 转 MCP 服务：如果需要使用新协议调用已有的 HTTP 转 MCP 服务，无需进行额外改造，可直接发起调用。

注意

协议插件更新机制如下：

存量 HTTP 转 MCP 服务：不会自动更新协议插件。仅当您在 MCP 类型专属网关上对 MCP 转换规则进行增加、删除或修改操作时，系统会自动同步更新插件；若未进行任何操作，插件版本不会发生变化。

新建 HTTP 转 MCP 服务：默认使用最新版本的插件，自动支持新旧两类协议。

MCP 2026-07-28 无状态机制

在 MCP 2026-07-28 协议下，协议层采用无状态调用模型：

不再使用 initialize、notifications/initialized 初始化握手。

不再使用 Mcp-Session-Id 维护协议级会话。

每个请求都应独立携带协议版本、客户端能力和本次调用所需的上下文信息，服务端不能依赖同一连接或历史请求来恢复客户端协议版本、能力或业务上下文。

MCP 服务无状态机制实现原理

MCP 2026-07-28 采用协议层无状态调用模型。客户端不再使用 initialize 和 notifications/initialized 完成初始化握手，也不再使用 Mcp-Session-Id 维护协议级会话。

每个请求都应独立携带协议版本、客户端能力和当前调用所需的上下文信息。服务端不能依赖同一连接或历史请求，恢复客户端的协议版本、能力或业务上下文。

发起无状态请求

通过 Streamable HTTP 调用 MCP 服务时，每个 JSON-RPC 请求都应作为一次独立请求处理。

请求头中应携带以下信息：

MCP-Protocol-Version：MCP 协议版本。

Mcp-Method：当前调用的方法。

Mcp-Name：目标名称或 URI。调用tools/call、resources/read或prompts/get等带目标名称或 URI 的方法时携带。

请求体的params._meta中应携带以下信息：

io.modelcontextprotocol/protocolVersion

io.modelcontextprotocol/clientCapabilities

建议同时携带io.modelcontextprotocol/clientInfo，且请求头中的协议版本、方法名和目标名应与请求体中的对应字段保持一致。

发现服务能力

客户端可调用server/discover，获取服务端支持的协议版本、能力声明、服务端信息和缓存提示。server/discover仅用于发现服务能力，不是初始化握手，也不会创建协议级会话。

跨请求保留业务状态

如果 MCP 服务需要在多个调用之间保留业务流程上下文、外部系统操作进度或临时任务状态，应由工具返回显式 handle、task id 或状态标识，并由客户端在后续请求中通过普通参数传入。

对于 MRTR 场景，服务端可返回以下信息：

resultType的取值为input_required：状态标志，即服务端通过把resultType设为input_required，告诉客户端“本次任务没处理完，还需要更多信息”，当resultType取值为complete，表明任务处理完成。

inputRequests：说明清单，告诉客户端“我需要你做什么”，比如让用户补填一个参数、确认一个操作，或者提供某种能力的结果。

可选的requestState：上下文存档，服务端把当前处理进度打包成一个不透明的字符串，让客户端在下次重试时带回来，这样服务端知道“刚才做到哪了”。不是所有工具都有中间状态需要保存。

客户端收集所需输入后，重新发起原请求，通过inputResponses携带处理结果，并原样回传requestState。服务端需要在每次调用时重新校验当前调用方是否有权访问相关状态，避免将业务状态隐式绑定到 HTTP 连接或协议会话中。

对于旧版 MCP 协议，客户端仍应按照对应版本的初始化和会话机制调用服务。平台可以在兼容范围内处理不同协议版本的请求，但客户端不应混用不同版本的消息格式。

MCP 工具集无状态机制实现原理

在 MCP 2026-07-28 协议下，MCP 工具集的工具发现和工具调用采用按请求自描述的无状态模型。客户端不需要先执行initialize和notifications/initialized初始化握手，也不依赖Mcp-Session-Id维护协议级会话。

每次 tools/list 或 tools/call 请求都应独立携带当前调用所需的协议版本、客户端能力、认证信息和业务参数。认证信息通常来自 HTTP 认证上下文，例如 Authorization 请求头，而不是 clientInfo。

发起无状态请求

通过 Streamable HTTP 调用 MCP 工具集时，每个 JSON-RPC 请求都应作为一次独立请求处理。

请求头中应携带以下信息：

MCP-Protocol-Version：MCP 协议版本。

Mcp-Method：当前调用的方法。

Mcp-Name：调用的工具名称，仅调用具体工具时携带。

请求体的params._meta中应携带以下信息：

io.modelcontextprotocol/protocolVersion

io.modelcontextprotocol/clientCapabilities

建议同时携带io.modelcontextprotocol/clientInfo，且请求头中的协议版本、方法名和工具名应与请求体中的对应字段保持一致。

获取可访问的工具

MCP 工具集会根据当前请求的身份认证信息、项目权限、工具集配置和路由上下文，确定本次请求可以访问的工具范围。工具列表可能随授权范围、工具集配置、后端 MCP 服务状态或工具同步结果发生变化，但不能依赖同一 HTTP 连接中的历史请求。

底层工具未发生变化时，工具列表宜保持稳定。客户端可根据ttlMs、cacheScope等缓存提示进行缓存和模型上下文复用。

不同工具调用模式的处理方式如下：

全量返回：客户端通过tools/list获取 MCP 工具集内可直接调用的工具列表。工具集聚合多个 MCP 服务中的工具时，可能会对工具名称进行区分处理，避免不同 MCP 服务中的工具重名。

语义检索：tools/list返回的可能是mcp_search_tool、mcp_use_tool等入口工具。客户端先调用mcp_search_tool，根据任务描述获取候选工具的server_id、server_name、tool_id、tool_name和参数结构，再通过mcp_use_tool显式传入目标工具信息并完成调用。

标签检索：tools/list返回的可能是mcp_list_tools_by_tags、mcp_use_tool等入口工具。客户端先按标签筛选候选工具，再通过mcp_use_tool显式传入目标工具信息并完成调用。

说明

语义检索和标签检索属于 MCP 工具集的工具匹配机制，不是 MCP 2026-07-28 定义的协议会话状态。客户端需要在后续tools/call请求中通过普通参数重新携带目标工具信息。

跨请求保留业务状态

如果工具调用需要在多次请求之间保留业务流程上下文、外部系统操作进度或临时任务状态，应由具体工具返回显式 handle、task id 或状态标识，并由客户端在后续请求中通过普通参数传入。

对于 MRTR 场景，应使用resultType、inputRequests、inputResponses和可选的requestState完成多轮交互。服务端需要在每次调用时重新校验当前调用方是否有权访问相关状态。

MCP 2026-07-28 MRTR 流程

Multi Round-Trip Requests（MRTR，多轮往返请求）用于处理“一次请求无法立即完成，服务端还需要用户输入、用户确认或客户端提供其他信息”的场景。在 MCP 2026-07-28 中，MRTR 用于替代旧版协议中通过 SSE 连接发送独立服务端请求的交互方式。MRTR 的核心信号是resultType，工具调用结果通过 resultType表示处理状态：

complete：工具调用已经完成。

input_required：工具尚未执行完成，还需要用户输入、用户确认或客户端提供其他信息。

MRTR 实现原理

MRTR 的处理流程如下：

客户端发起tools/call、resources/read或prompts/get请求。

服务端返回resultType，其取值为input_required，并通过inputRequests说明客户端需要完成的输入或操作。

客户端完成所需输入或操作后，使用新的 JSON-RPC id重新发起原请求，并通过inputResponses携带处理结果。

如果服务端返回了requestState，客户端必须在重试请求中将其原样回传。

服务端获得所需信息后继续处理：

处理完成时，返回resultType，其取值为complete。

如果仍需其他信息，可以再次返回input_required，客户端重复执行上述流程。

requestState是由服务端生成、用于恢复请求上下文的不透明字符串。客户端不得解析、修改、猜测或将其用于其他请求。服务端应校验requestState的完整性、所属用户、有效期和原始请求信息，防止状态篡改，以及跨用户或跨请求重放。

服务端只能请求客户端已通过clientCapabilities声明支持的能力。例如，如果客户端未声明Elicitation能力，服务端不能要求客户端执行 elicitation/create。

MCP 工具集补充说明

在语义检索和标签检索模式下，mcp_use_tool支持在一次请求中调用一个或多个后端工具：

如果某个后端工具返回input_required，MCP 工具集会向客户端返回对应的inputRequests和requestState。

如果多个后端工具同时需要输入，MCP 工具集会合并待处理的输入请求，并保证请求标识不冲突。

客户端完成输入后，仍需通过新的独立tools/call请求继续调用，并携带原样的requestState和对应的inputResponses。

最近更新时间：2026.09.18 11:13:05

这个页面对您有帮助吗？

有用

无用