MCP

AgentScope 集成 Model Context Protocol (MCP)，让智能体可以接入任意兼容 MCP 的工具服务。框架自动处理协议协商、工具发现与结果转换。支持两种连接方式：

连接方式	传输协议	生命周期
有状态（Stateful）	STDIO 或 HTTP	持久会话，需显式 `connect()` / `close()`
无状态（Stateless）	仅 HTTP	每次调用临时建会话，无需生命周期管理

为了避免冲突，MCP 工具的命名空间为 mcp__{server_name}__{tool_name}；被标注 readOnlyHint 的 MCP 工具会被权限系统识别为只读（在 EXPLORE 与 ACCEPT_EDITS 模式下自动放行；DEFAULT 模式下若没有 allow 规则命中，仍然会 ASK）。 AgentScope 2.0.11 使用 MCP Python SDK 2.x（mcp>=2.0.0），并自动与现有 STDIO、Streamable HTTP 和 SSE 服务器协商协议。

注册 MCP 客户端

通过 Toolkit(mcps=[...]) 接口可以注册多个 MCP 客户端，其中有状态的 MCP 客户端必须在构造 toolkit 之前完成连接。

from agentscope.mcp import MCPClient, StdioMCPConfig
from agentscope.tool import Toolkit

client = MCPClient(
    name="filesystem",
    is_stateful=True,
    mcp_config=StdioMCPConfig(
        command="mcp-server-filesystem",
        args=["--root", "/my/project"],
    ),
)

await client.connect()

toolkit = Toolkit(mcps=[client])

from agentscope.mcp import MCPClient, HttpMCPConfig
from agentscope.tool import Toolkit

client = MCPClient(
    name="weather",
    is_stateful=True,
    mcp_config=HttpMCPConfig(
        url="https://api.weather.com/mcp",
        headers={"Authorization": "Bearer xxx"},
    ),
)

await client.connect()

toolkit = Toolkit(mcps=[client])

from agentscope.mcp import MCPClient, HttpMCPConfig
from agentscope.tool import Toolkit

client = MCPClient(
    name="search",
    is_stateful=False,
    mcp_config=HttpMCPConfig(url="https://api.search.com/mcp"),
)

toolkit = Toolkit(mcps=[client])

筛选暴露的工具

如果希望只暴露 MCP 服务的部分工具，可以在客户端上配置 enable_tools 或 disable_tools 参数：

client = MCPClient(
    name="search",
    is_stateful=False,
    mcp_config=HttpMCPConfig(url="https://api.search.com/mcp"),
    enable_tools=["web_search", "image_search"],
)

运行时更新 HTTP header

mcp_config 中的 headers 在构造时就已固定。当鉴权令牌会在会话中途轮换时，对 Streamable HTTP 客户端调用 set_runtime_headers() 即可替换后续请求携带的 header，既不用重建客户端，也不用重新连接：

# 传入完整映射，整体替换运行时 header；传入空字典则清空，回到 mcp_config 中的静态 header
await client.set_runtime_headers({"Authorization": "Bearer new-token"})

使用时需要注意以下边界：

项目	说明
适用范围	仅 Streamable HTTP 客户端，STDIO 与 SSE 客户端调用会抛出 `ValueError`
生效时机	下一个出站请求。已经在途的调用沿用它启动时的快照，Streamable HTTP 长连 GET 流的 header 在流建立时即固定
覆盖关系	MCP 自己按请求设置的 header（`mcp-session-id`、`content-type` 等）始终优先；`connection`、`content-length`、`host`、`transfer-encoding` 由 HTTP 层所有，传入会被拒绝
持久化	运行时 header 是实例上的活跃状态，不参与 `model_dump`，也不会写入工作区持久化

Docker 工作区中真正的 MCP 客户端跑在网关进程里，主机侧持有的是代理对象。对代理调用 set_runtime_headers() 会转发给网关，详见 MCP 网关。

在 Toolkit 之外使用 MCP 工具

需要在 Toolkit 之外直接调用 MCP 工具时，调用 await client.list_tools() 拿到 MCPTool 实例列表后，即可像普通 ToolBase 一样使用。

接收工具进度

为本地 MCPClient 设置 stream_progress=True，可以在工具执行期间展示进度。 MCP 服务器需要主动发送进度通知：

启用进度通知

from agentscope.mcp import HttpMCPConfig, MCPClient
from agentscope.tool import Toolkit

# Pass this toolkit to the agent that will call the server's tools.
client = MCPClient(
    name="reports",
    is_stateful=False,
    mcp_config=HttpMCPConfig(url="http://localhost:8000/mcp"),
    stream_progress=True,
)
toolkit = Toolkit(mcps=[client])

在 Agent.reply_stream() 中，进度以 CustomEvent(name="mcp_progress") 发出。其 value 包含 reply_id、tool_call_id、progress，以及可为空的 total 和 message。使用这两个 ID 更新对应工具的进度显示。进度是临时快照，不保证逐条送达，也不会写入最终工具结果；Msg.append_event() 会忽略这些事件。在工具包外调用工具时，启用进度后，await tool(...) 返回由 ToolChunk 组成的异步迭代器。进度位于 chunk.metadata["mcp_progress"]，最后一个块携带最终结果。默认的 stream_progress=False 则只返回最终结果块。

沙箱网关工具即使启用进度配置，也只返回最终结果。如果 MCP 结果只有结构化内容而没有文本块，AgentScope 会将其 JSON 表示补充到最终结果中。

快速开始

核心模块

智能体即服务

其他

注册 MCP 客户端

筛选暴露的工具

运行时更新 HTTP header

在 Toolkit 之外使用 MCP 工具

接收工具进度

​注册 MCP 客户端

​筛选暴露的工具

​运行时更新 HTTP header

​在 Toolkit 之外使用 MCP 工具

​接收工具进度

注册 MCP 客户端

筛选暴露的工具

运行时更新 HTTP header

在 Toolkit 之外使用 MCP 工具

接收工具进度