MCP

AgentScope integrates with Model Context Protocol (MCP) servers, letting an agent reach any MCP-compatible tool provider. The framework handles protocol negotiation, tool discovery, and result conversion automatically. Two connection modes are supported:

Mode	Transport	Lifecycle
Stateful	STDIO or HTTP	Persistent session with explicit `connect()` / `close()`
Stateless	HTTP only	Ephemeral session created per tool call, no lifecycle management needed

MCP tools are namespaced as mcp__{server_name}__{tool_name} to avoid name collisions, and tools annotated with readOnlyHint are recognized as read-only by the permission system (auto-allowed in EXPLORE and ACCEPT_EDITS modes; in DEFAULT they still ASK unless an allow rule matches). AgentScope 2.0.11 uses the MCP Python SDK 2.x (mcp>=2.0.0). Protocol negotiation is automatic for existing STDIO, Streamable HTTP, and SSE servers.

Register MCP Client

Build one or more MCPClient instances and pass them to Toolkit(mcps=[...]). Stateful clients must be connected before the toolkit is constructed.

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])

Filter Exposed Tools

To expose only a subset of an MCP server’s tools, set enable_tools or disable_tools on the client itself:

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

Update HTTP Headers at Runtime

The headers in mcp_config are fixed at construction. When an auth token rotates mid-session, call set_runtime_headers() on a Streamable HTTP client to replace the headers sent with subsequent requests — no rebuild and no reconnect:

# The map is replaced, not merged; an empty dict clears it and the static headers apply again
await client.set_runtime_headers({"Authorization": "Bearer new-token"})

The behaviour has a few boundaries worth knowing:

Aspect	Behaviour
Scope	Streamable HTTP clients only; STDIO and SSE clients raise `ValueError`
When it takes effect	The next outbound request. A call already under way keeps the snapshot it started with, and the headers of a Streamable HTTP session’s long-lived GET stream are fixed when the stream is established
Precedence	Headers MCP sets per request (`mcp-session-id`, `content-type`, …) always win; `connection`, `content-length`, `host` and `transfer-encoding` are owned by the HTTP layer and are rejected
Persistence	Runtime headers are live instance state, excluded from `model_dump` and from workspace persistence

In a Docker workspace the live MCP client runs inside the gateway process and the host holds a proxy. Calling set_runtime_headers() on the proxy relays the update to the gateway — see MCP Gateway.

Use MCP Tools Outside a Toolkit

If you need to invoke MCP tools outside a Toolkit, call await client.list_tools() to retrieve a list of MCPTool adapters and use them like any other ToolBase instance.

Stream Tool Progress

Set stream_progress=True on a local MCPClient to show progress while a server executes a tool. The server must emit MCP progress notifications:

Enable progress notifications

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])

During Agent.reply_stream(), progress arrives as CustomEvent(name="mcp_progress"). Its value contains reply_id, tool_call_id, progress, and optional total and message values. Use the IDs to update the matching tool indicator. These are transient snapshots: consumers must not rely on receiving every update. They are excluded from the final tool result and ignored by Msg.append_event(). Outside a toolkit, await tool(...) returns an asynchronous iterator of ToolChunk objects when streaming is enabled. Progress is carried in chunk.metadata["mcp_progress"], followed by the final result chunk. With the default stream_progress=False, it returns only the final chunk.

Sandbox gateway tools return only final results even when the configuration enables progress streaming. If an MCP result contains structured content but no text block, AgentScope adds its JSON representation to the final result.

Get Started

Building Blocks

Agent as Service

Others

Register MCP Client

Filter Exposed Tools

Update HTTP Headers at Runtime

Use MCP Tools Outside a Toolkit

Stream Tool Progress

​Register MCP Client

​Filter Exposed Tools

​Update HTTP Headers at Runtime

​Use MCP Tools Outside a Toolkit

​Stream Tool Progress

Register MCP Client

Filter Exposed Tools

Update HTTP Headers at Runtime

Use MCP Tools Outside a Toolkit

Stream Tool Progress