AgentScope integrates the Model Context Protocol (MCP) to provide agents with a standardized way to connect to external tools, data sources, and context servers. This integration allows agents to utilize a vast ecosystem of MCP servers (e.g., Google Drive, Slack, GitHub, local filesystems) without writing custom wrappers for every API.
The MCP integration in AgentScope is built on three primary pillars:
MCPClient: A unified client handling both stateful (stdio/SSE) and stateless (HTTP) connections to MCP servers [src/agentscope/mcp/_mcp_client.py:24-67].MCPTool Adapter: Wraps MCP-defined tools into AgentScope's ToolBase interface, ensuring compatibility with the Toolkit and ReAct loop [src/agentscope/tool/_adapters.py:167-173].This diagram illustrates how a natural language request from an LLM is translated into an MCP tool call through AgentScope's entity space.
Sources: [src/agentscope/tool/_toolkit.py:171-174], [src/agentscope/tool/_adapters.py:207-222], [src/agentscope/mcp/_mcp_client.py:228-235]
The MCPClient class manages the connection lifecycle [src/agentscope/mcp/_mcp_client.py:24-67].
| Feature | Stateful Connection | Stateless Connection |
|---|---|---|
| Persistence | Connection remains open; maintains session state. | Temporary session created per tool call. |
| Transports | Required for stdio_mcp; optional for http_mcp. | Available for http_mcp only. |
| Performance | Lower latency for repeated calls. | Higher overhead (handshake per call). |
| Initialization | Requires explicit connect() and close() [src/agentscope/mcp/_mcp_client.py:52-54]. | No connect() needed; session is ephemeral [src/agentscope/mcp/_mcp_client.py:64-65]. |
Sources: [src/agentscope/mcp/_mcp_client.py:74-81], [src/agentscope/mcp/_mcp_client.py:128-132]
The MCPTool class [src/agentscope/tool/_adapters.py:167-173] acts as a bridge between the MCP protocol and AgentScope's ToolBase.
__init__: Maps the MCP inputSchema to AgentScope's input_schema and handles naming conventions (mcp__{mcp_name}__{tool_name}) [src/agentscope/tool/_adapters.py:180-205].check_permissions: Implements a safety layer. Read-only tools (flagged by readOnlyHint) are auto-allowed; all other MCP tools default to PermissionBehavior.ASK [src/agentscope/tool/_adapters.py:246-264].__call__: Orchestrates the call through the MCPClient, converting results into ToolChunk objects for the agent [src/agentscope/tool/_adapters.py:207-244].Sources: [src/agentscope/tool/_adapters.py:167-264]
In sandboxed workspaces (Docker, E2B, etc.), AgentScope uses a Gateway Architecture to allow agents to interact with MCP servers that might be running outside the sandbox.
GatewayClient: A host-side facade that dispatches requests via backend.exec_shell [src/agentscope/workspace/_gateway_client.py:7-8].SHIM_SCRIPT: A minimal Python script injected into the sandbox that relays requests to the gateway via urllib.request [src/agentscope/workspace/_gateway_shim.py:48-96]._mcp_gateway_app.py: A FastAPI application running inside the workspace environment that manages a registry of MCPClient instances [src/agentscope/workspace/_mcp_gateway/_mcp_gateway_app.py:67-78].GatewayMCPTool: A ToolBase subclass used within the sandbox that relays __call__ requests to the gateway [src/agentscope/workspace/_gateway_client.py:57-64].Sources: [src/agentscope/workspace/_gateway_client.py:1-22], [src/agentscope/workspace/_gateway_shim.py:1-21], [src/agentscope/workspace/_mcp_gateway/_mcp_gateway_app.py:1-29]
The MCP Hub (e.g., GitHubMCPHub) allows browsing and installing servers from registries like GitHub's MCP catalog [src/agentscope/app/hub/_mcp/_github_hub.py:101-108].
MCPCard: A hub-provided template containing config_template and inputs_schema [src/agentscope/app/hub/_mcp/_card.py:11-20].render_mcp: Takes a card and user-supplied values (e.g., API keys) to produce a connectable MCPClient [src/agentscope/app/_service/_mcp_render.py:103-107].InstallMCPDialog: A React component in the Web UI that collects these values via a generated SchemaForm [examples/web_ui/frontend/src/components/dialog/InstallMCPDialog.tsx:44-50].The renderer uses string.Template to fill placeholders like ${api_key} in URLs, headers, or environment variables [src/agentscope/app/_service/_mcp_render.py:83-90]. Optional environment variables are omitted if their corresponding inputs are not provided [src/agentscope/app/_service/_mcp_render.py:32-42].
Sources: [src/agentscope/app/hub/_mcp/_github_hub.py:1-17], [src/agentscope/app/_service/_mcp_render.py:103-169], [examples/web_ui/frontend/src/components/dialog/InstallMCPDialog.tsx:122-130]
Refresh this wiki