就像电脑的 USB 接口——任何设备插上就能用。MCP 让 Agent 连接任意外部工具,无需修改核心代码。
想象你的电脑只有内置功能:不能接鼠标、不能插U盘、不能连显示器。MCP 就是给 Agent 装上 USB 接口——标准化的即插即用协议,让任何外部工具都能无缝接入。
JSON-RPC 2.0 通信格式,所有工具遵循同一套调用规范
连接后自动获取可用工具列表,无需硬编码
运行时动态添加/移除工具服务器,Agent 无需重启
| 概念 | 说明 |
|---|---|
| MCPServer | 提供工具的服务端——注册工具、处理调用 |
| MCPClient | 连接外部工具的客户端——发现工具、发起调用 |
| Transport | 通信层——stdio(本地进程)、HTTP(远程)、SSE(实时流) |
| Tool | 一个可调用的功能单元,有名称、描述、参数定义 |
tool_name
{"jsonrpc":"2.0","method":"tools/call","params":{...}}
MCPServer 是工具的"房东"——它注册工具定义、处理来自客户端的调用请求。核心三件套:register_tool、list_tools、call_tool。
import json, sys class MCPServer: def __init__(self, name: str): self.name = name self.tools = {} # { "tool_name": handler_func } self.tool_defs = {} # { "tool_name": {description, parameters} } def register_tool(self, name, description, parameters, handler): """注册一个工具:定义 + 处理函数""" self.tool_defs[name] = { "name": name, "description": description, "parameters": parameters # JSON Schema } self.tools[name] = handler def list_tools(self): """返回所有已注册工具的定义列表""" return list(self.tool_defs.values()) def call_tool(self, name, arguments): """查找并执行工具""" if name not in self.tools: return {"error": f"Tool '{name}' not found"} return self.tools[name](**arguments) def handle_request(self, request: dict) -> dict: """处理 JSON-RPC 2.0 请求""" method = request["method"] req_id = request.get("id") if method == "tools/list": result = self.list_tools() elif method == "tools/call": params = request["params"] result = self.call_tool(params["name"], params.get("arguments", {})) else: return {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": req_id} return {"jsonrpc": "2.0", "result": result, "id": req_id}
所有 MCP 通信都遵循 JSON-RPC 2.0 格式:
请求:{"jsonrpc":"2.0", "id":1, "method":"tools/call", "params":{...}}
响应:{"jsonrpc":"2.0", "id":1, "result":{...}}
id 用于匹配请求和响应,method 标识操作类型。
MCPClient 是 Agent 侧的"翻译官"——它连接远端的 MCPServer,发现可用工具,并把调用请求转发出去。
Pythonclass MCPClient: def __init__(self, name: str): self.name = name self.servers = {} # { "server_name": transport } self.tools = {} # { "prefixed_tool_name": tool_def } async def add_server(self, server_name: str, transport): """连接一个 MCP Server 并自动发现工具""" self.servers[server_name] = transport # 1. 请求工具列表 response = await transport.send({ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }) # 2. 注册发现的工具(加前缀避免冲突) for tool in response["result"]: prefixed = f"{server_name}__{tool['name']}" self.tools[prefixed] = {"server": server_name, **tool} async def call_tool(self, tool_name: str, arguments: dict): """调用工具:路由到对应的 server""" tool_info = self.tools[tool_name] server_name = tool_info["server"] transport = self.servers[server_name] original_name = tool_name.split("__", 1)[1] response = await transport.send({ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": original_name, "arguments": arguments} }) return response["result"] def list_tools(self): """列出所有可用工具(Agent 用来决定调用哪个)""" return [ {"name": name, "description": t["description"], "parameters": t.get("parameters",{})} for name, t in self.tools.items() ]
使用 server_name__tool_name 双下划线前缀:
filesystem__read_file、database__query、weather__forecast
避免不同 Server 注册同名工具时产生冲突。
MCP 最优雅的设计:连接后自动获取工具定义,无需预先硬编码。
# 工具发现的完整流程 # Step 1: 创建 Client client = MCPClient("my_agent") # Step 2: 连接 Server(自动完成发现) transport = StdioTransport("python", "mcp_server.py") await client.add_server("filesystem", transport) # Step 3: 查看发现的工具 for tool in client.list_tools(): print(f" {tool['name']}: {tool['description']}") # 输出: # filesystem__read_file: Read file contents # filesystem__write_file: Write content to file # filesystem__list_dir: List directory contents # Step 4: 直接调用! result = await client.call_tool("filesystem__read_file", {"path": "data.txt"})
通过子进程 stdin/stdout 通信,零网络延迟,适合本地工具。
标准 HTTP POST 请求-响应,适合远程 API 和云服务。
Server-Sent Events 流式推送,适合长时间运行的实时任务。
from mcp.server import MCPServer import os server = MCPServer("filesystem") @server.register_tool( name="read_file", description="Read the contents of a file", parameters={ "type": "object", "properties": {"path": {"type": "string", "description": "File path"}}, "required": ["path"] } ) def read_file(path): with open(path, "r") as f: return {"content": f.read()} @server.register_tool( name="write_file", description="Write content to a file", parameters={ "type": "object", "properties": { "path": {"type": "string"}, "content": {"type": "string"} }, "required": ["path", "content"] } ) def write_file(path, content): with open(path, "w") as f: f.write(content) return {"success": True, "bytes": len(content)} server.run_stdio()
import sqlite3 from mcp.server import MCPServer server = MCPServer("database") db = sqlite3.connect("app.db") @server.register_tool( name="query", description="Execute a read-only SQL query", parameters={ "type": "object", "properties": {"sql": {"type": "string", "description": "SQL SELECT statement"}}, "required": ["sql"] } ) def query(sql): # 安全检查:只允许 SELECT if not sql.strip().upper().startswith("SELECT"): return {"error": "Only SELECT queries allowed"} cursor = db.execute(sql) columns = [desc[0] for desc in cursor.description] rows = cursor.fetchall() return {"columns": columns, "rows": rows, "count": len(rows)} @server.register_tool( name="list_tables", description="List all tables in the database", parameters={"type": "object", "properties": {}} ) def list_tables(): cursor = db.execute("SELECT name FROM sqlite_master WHERE type='table'") return {"tables": [row[0] for row in cursor.fetchall()]} server.run_stdio()
import httpx from mcp.server import MCPServer server = MCPServer("weather_api") client = httpx.AsyncClient() @server.register_tool( name="get_weather", description="Get current weather for a city", parameters={ "type": "object", "properties": { "city": {"type": "string", "description": "City name"}, "units": {"type": "string", "enum": ["metric", "imperial"], "default": "metric"} }, "required": ["city"] } ) async def get_weather(city, units="metric"): resp = await client.get( f"https://api.weather.example/v1/{city}", params={"units": units} ) data = resp.json() return { "city": data["name"], "temp": data["main"]["temp"], "condition": data["weather"][0]["description"] } server.run_http(port=8080>)
最终目标:让 Agent 天然支持 MCP。继承 Agent,加入 MCP Client 能力。
class AgentWithMCP(Agent): """继承 Agent,自动集成 MCP 工具发现和调用""" def __init__(self, name, model, mcp_servers=None, **kwargs): super().__init__(name=name, model=model, **kwargs) self.mcp_client = MCPClient(name) self.mcp_configs = mcp_servers or [] async def initialize(self): """启动时连接所有 MCP Server""" for config in self.mcp_configs: if config["transport"] == "stdio": transport = StdioTransport(*config["command"]) elif config["transport"] == "http": transport = HttpTransport(config["url"]) await self.mcp_client.add_server(config["name"], transport) self.tools.register_external(self.mcp_client.list_tools()) print(f"✅ Connected to MCP server: {config['name']}") async def execute_tool(self, tool_name, arguments): """覆写:MCP 工具走 client,本地工具走原逻辑""" if "__" in tool_name: return await self.mcp_client.call_tool(tool_name, arguments) return await super().execute_tool(tool_name, arguments) # 使用方式 agent = AgentWithMCP( name="assistant", model="gpt-4", mcp_servers=[ {"name": "filesystem", "transport": "stdio", "command": ["python", "fs_server.py"]}, {"name": "database", "transport": "stdio", "command": ["python", "db_server.py"]}, {"name": "weather", "transport": "http", "url": "http://localhost:8080"}, ] ) await agent.initialize() await agent.run("读取 config.yaml 并查询今天的天气")
AgentWithMCP = Agent + MCPClient。
本地工具走 tools.register,远程工具走 mcp_client。
execute_tool 自动路由:双下划线 → MCP,否则 → 本地。
Server-Sent Events (SSE) 不同于普通 HTTP 请求-响应,它维持一个长连接,服务端可以持续推送事件。
Protocol// SSE 传输的 MCP 通信示例 // 1. Client 发起 SSE 连接 GET /mcp/sse HTTP/1.1 Accept: text/event-stream // 2. Server 推送事件流 data: {"jsonrpc":"2.0", "method":"progress", "params":{"percent":30}} data: {"jsonrpc":"2.0", "method":"progress", "params":{"percent":60}} data: {"jsonrpc":"2.0", "id":1, "result":{"done":true}} // 3. Client 发送请求(通过独立 HTTP POST) POST /mcp/message HTTP/1.1 Content-Type: application/json {"jsonrpc":"2.0", "id":2, "method":"tools/call", "params":{...}}
适合场景:长时间运行的工具(代码编译、模型推理)、需要进度报告的任务。
MCP Server 是天然的安全沙箱——每个 Server 在独立进程中运行,权限范围由 Server 本身控制。
Security Patternclass SandboxedServer(MCPServer): """带权限控制的 MCP Server""" def __init__(self, name, allowed_paths=None): super().__init__(name) self.allowed_paths = allowed_paths or [] def check_permission(self, path): return any(path.startswith(p) for p in self.allowed_paths) def call_tool(self, name, arguments): # 额外的安全检查 if name == "read_file" and not self.check_permission(arguments["path"]): return {"error": "Permission denied: path not allowed"} return super().call_tool(name, arguments)
最佳实践:每个 MCP Server 只暴露最小必要权限,Agent 无法绕过 Server 的安全检查。
真正强大的场景:一个 Agent 协调多个 MCP Server 完成复杂任务。
Orchestration# 示例:Agent 执行 "分析销售数据并生成报告" # Step 1: database Server — 查询数据 data = await mcp.call_tool("database__query", { "sql": "SELECT * FROM sales WHERE month='2025-06'" }) # Step 2: 本地计算 — 数据分析(不需要 MCP) analysis = analyze_sales(data["rows"]) # Step 3: filesystem Server — 写入报告 await mcp.call_tool("filesystem__write_file", { "path": "reports/june_2025.md", "content": format_report(analysis) }) # Step 4: notification Server — 发送通知 await mcp.call_tool("notification__send", { "channel": "slack", "message": "6月销售报告已生成 ✅" })
Agent 作为"指挥家",各 MCP Server 是"乐手",协同演奏出复杂的业务流程。