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）。

注册 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"],
)

在 Toolkit 之外使用 MCP 工具

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

快速开始

核心模块

智能体即服务

其他

注册 MCP 客户端

筛选暴露的工具

在 Toolkit 之外使用 MCP 工具

​注册 MCP 客户端

​筛选暴露的工具

​在 Toolkit 之外使用 MCP 工具

注册 MCP 客户端

筛选暴露的工具

在 Toolkit 之外使用 MCP 工具