S19｜MCP 与插件：多 Agent 平台 —— 外部能力总线，让外部工具安全接入

在前十八章我们的 Agent 已经拥有完整的内部能力体系循环、工具、计划、子代理、技能、压缩、权限、Hook、记忆、提示词流水线、错误恢复、任务系统、后台任务、定时调度、多 Agent 团队、团队协议、自主代理、Worktree 隔离所有工具都写在本地代码里。但真实系统走到一定阶段会遇到一个自然的需求能不能让外部程序也把工具接进来而不用每次都改主程序这一章 S19我们给 Agent 加上MCP 与插件系统让外部工具通过统一协议安全接入和本地工具处在同一控制面实现 “外部能力总线”让工具不再局限于本地硬编码。本章核心信息核心闭环插件配置发现 → MCP Server 启动 → 工具标准化注册 → 统一路由分发 → 权限检查 → 结果回流主循环工具数量4 个核心思想外部能力系统不该是外挂它们应和原生工具一起处在同一控制面上先看懂本章所有名词MCPModel Context Protocol一套让 Agent 和外部工具程序对话的统一协议定义了如何发现工具、调用工具、接收结果的标准方式。MCP Server提供外部工具能力的独立进程通过 MCP 协议暴露工具列表和调用接口Agent 通过连接 Server 使用这些工具。插件Plugin负责外部工具配置的声明文件告诉主程序如何发现、启动和连接 MCP Server包含插件名、版本、Server 配置等信息。工具前缀规则区分本地工具和外部 MCP 工具的命名约定格式为mcp__{server}__{tool}避免命名冲突一眼就能识别工具来源。统一路由器负责分发工具调用请求的核心组件判断是本地工具还是 MCP 工具分别交给对应的处理器处理。外部能力总线所有外部工具通过 MCP 接入后和本地工具共享同一套权限检查、结果处理、主循环回流逻辑形成统一的能力接入体系。这一章到底要解决什么问题到 S18Agent 的所有工具都写在本地代码里存在明显的局限性新增工具必须修改主程序扩展性差外部程序无法直接提供能力只能通过硬编码集成工具来源单一无法复用成熟的第三方服务能力无法统一管理本地和外部工具的权限、调用和结果本章要解决的核心问题把工具来源从 “本地硬编码” 升级为 “外部可插拔”让外部工具通过统一协议安全接入和本地工具共享同一控制面实现系统的可扩展能力。最小心智模型外部工具接入的三层结构LLM | | 发起工具调用请求 v Agent 工具路由器 | -- 本地工具 → 交给本地 Python 处理器执行 | -- MCP 工具 → 交给 MCP Client 转发给外部 Server | v MCP Server 执行工具并返回结果一句话MCP 不是独立的外挂系统而是外部工具接入 Agent 的统一协议最终和本地工具汇入同一套执行逻辑。关键数据结构本章灵魂1. 插件配置文件plugin.json{ name: my-db-tools, version: 1.0.0, mcpServers: { postgres: { command: npx, args: [-y, modelcontextprotocol/server-postgres], env: {} } } }它本质上是一份配置声明告诉主程序如何发现和启动 MCP Server。2. MCP Server 配置server_config { command: npx, args: [-y, modelcontextprotocol/server-postgres], env: {} }定义了启动外部 Server 的命令、参数和环境变量。3. 标准化后的工具定义{ name: mcp__postgres__query, description: Run a SQL query on PostgreSQL, input_schema: { type: object, properties: { query: {type: string} } } }把 MCP Server 暴露的工具转成 Agent 能看懂的统一格式加上mcp__前缀区分来源。4. MCP Client 注册表clients { postgres: mcp_client_instance }记录已连接的 MCP Client 实例方便路由器快速查找和转发请求。最小实现代码极简可运行第一步实现一个基础的 MCPClientclass MCPClient: def __init__(self, server_config): self.config server_config self.process None self.tools [] def connect(self): # 启动外部Server进程 self.process subprocess.Popen( [self.config[command]] self.config[args], stdoutsubprocess.PIPE, stderrsubprocess.PIPE, textTrue ) # 建立连接并获取工具列表 self.tools self.list_tools() def list_tools(self): # 向Server请求工具列表 # 教学版简化实际按MCP协议通信 return [{name: query, description: Run SQL query}] def call_tool(self, tool_name, arguments): # 转发工具调用请求给Server # 教学版简化实际按MCP协议通信 return {status: ok, preview: Query executed successfully}核心能力连接 Server、获取工具列表、转发调用请求。第二步把外部工具标准化为 Agent 工具格式def normalize_mcp_tools(server_name, raw_tools): normalized [] for tool in raw_tools: # 加上mcp__前缀格式mcp__{server}__{tool} prefixed_name fmcp__{server_name}__{tool[name]} normalized.append({ name: prefixed_name, description: tool[description], input_schema: tool.get(input_schema, {}) }) return normalized关键通过前缀规则区分本地和外部工具避免命名冲突。第三步实现统一工具路由器class ToolRouter: def __init__(self, native_tools, mcp_clients): self.native_tools native_tools self.mcp_clients mcp_clients # key: server_name, value: MCPClient def route(self, tool_name, arguments): # 判断是否为MCP工具 if tool_name.startswith(mcp__): # 解析server名和工具名mcp__postgres__query parts tool_name.split(__, 2) server_name parts[1] tool_name parts[2] # 转发给对应的MCP Client client self.mcp_clients[server_name] return client.call_tool(tool_name, arguments) else: # 本地工具交给本地处理器 return self.native_tools[tool_name](arguments)路由器只做一件事根据工具名分发请求不区分工具来源。第四步MCP 工具必须经过同一条权限管道def check_permission(tool_name, arguments, mode): # 权限检查逻辑和本地工具完全一致 # 即使是MCP工具也不能绕开权限闸门 if tool_name.startswith(mcp__): # 提取server和工具信息进行权限检查 if is_dangerous_mcp_tool(tool_name): return deny, Dangerous MCP tool call blocked # 本地工具权限检查 return native_permission_check(tool_name, arguments, mode)关键外部工具也必须经过统一的权限检查不能成为安全后门。第五步结果标准化回流主循环def normalize_tool_result(tool_name, raw_result): if tool_name.startswith(mcp__): parts tool_name.split(__, 2) server_name parts[1] return { source: mcp, server: server_name, tool: parts[2], status: raw_result.get(status, ok), preview: raw_result.get(preview, ) } else: # 本地工具结果格式 return { source: native, tool: tool_name, status: raw_result.get(status, ok), preview: raw_result.get(preview, ) }无论本地还是外部工具结果都要转成主循环能统一处理的格式。插件、MCP Server、MCP Tool 三层关系初学者很容易把这三个概念混在一起这里用表格帮你理清边界层级它是什么它负责什么Plugin Manifest一份配置声明文件告诉系统要发现和启动哪些 MCP ServerMCP Server一个外部进程 / 连接对象对外暴露一组工具能力MCP ToolServer 暴露的一项具体调用能力真正被模型点名调用的功能一句话总结Plugin 负责 “发现”Server 负责 “连接”Tool 负责 “调用”。如何接到前面章节的系统里MCP 不是孤立的外挂而是接入 Agent 已有体系的扩展层完整链路如下启动时PluginLoader 读取插件配置 - 解析并获取MCP Server配置 - 启动Server并建立连接 - 获取Server的工具列表 - 标准化工具名并合并进主程序工具池运行时LLM 生成工具调用请求 - 统一权限闸门检查和本地工具完全一致 - 工具路由器分发请求本地/MCP - 执行工具并返回结果 - 结果标准化后回流主循环关键进入方式不同但进入后必须回到同一条控制面和执行面。初学者最容易被带偏的 3 个坑一上来就讲太多协议细节不要一开始就陷入 transports、auth、resources 等复杂概念主线只有一句话外部工具也能像本地工具一样接进 Agent。把 MCP 当成一套完全不同的工具系统它最终仍然汇入你原来的工具体系一样要注册、一样要过权限、一样要返回 tool_result不是独立的外挂。忽略命名与路由规则没有统一前缀和路由本地和外部工具会混在一起系统很快就会混乱无法区分工具来源。S18 → S19 升级了什么模块S18S19工具来源本地硬编码工具本地工具 外部可插拔 MCP 工具扩展性新增工具需修改主程序外部工具通过插件配置接入无需修改主程序能力边界仅依赖开发者手写的工具可复用第三方成熟服务能力如数据库、浏览器等控制面统一权限、路由、结果处理本地和外部工具共享同一控制面无安全后门架构地位多 Agent 并行隔离执行层系统外部能力扩展层本章教学边界本章先停在 “tools-first” 的主线不展开协议细节不深入讲 transports、认证、连接恢复等复杂协议内容不展开 resources、prompts 等 MCP 扩展能力只讲清外部工具如何被发现、命名、路由、过权限、回流主循环这些扩展内容可以放到后续平台桥接文档中展开正文先聚焦主线避免读者失焦。一句话总结本章MCP 的本质不是协议名词堆砌而是把外部工具安全、统一地接进你的 Agent。它让工具不再局限于本地硬编码通过插件和 MCP 协议让外部能力成为系统的可扩展总线和本地工具共享同一控制面实现真正的可扩展 Agent 平台。