> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> 接入 MCP 服务并使用其工具

AgentScope 集成 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)，让智能体可以接入任意兼容 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 之前完成连接。

<CodeGroup>
  ```python title="Stateful (STDIO)" theme={null}
  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])
  ```

  ```python title="Stateful (HTTP)" theme={null}
  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])
  ```

  ```python title="Stateless (HTTP)" theme={null}
  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])
  ```
</CodeGroup>

## 筛选暴露的工具

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

```python theme={null}
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` 一样使用。