MCP协议、熔断器与OAuth——Agent接入外部世界的工程方案

MCP协议、熔断器与OAuth——Agent接入外部世界的工程方案《Claude Code 架构解密》精读笔记 · 第15篇覆盖章节第9章后半9.6-9.12, p.237-251主题8种MCP传输适配、分级熔断连接缓存、OAuth/XAA认证状态机、分区批处理编排、插件模块化组合导语从内部拦截到外部集成第14篇解析了 Hook 事件系统——Claude Code 的内部扩展骨架。但 Agent 的真正威力不仅来自能拦截什么更来自能连接什么。当 Agent 需要查询公司内部的知识库、调用云服务 API、读取设计稿里的组件定义、甚至控制智能家居设备时它需要一个统一的外部集成通道。这个通道就是MCPModel Context Protocol。但统一接入说起来容易做起来难。MCP 服务器可能跑在本地子进程里也可能部署在远程 HTTP 服务上还可能嵌在 IDE 的 WebSocket 连接里——8 种传输协议每种都有不同的连接方式、错误处理和安全约束。更麻烦的是这些连接会断开、会超时、会认证过期——Agent 不能每次都傻傻地报错而要有智能的故障恢复机制。本篇将深入 Claude Code 的 MCP 协议栈、连接管理体系、认证状态机以及把这一切打包分发的插件系统。这是 Agent 从产品走向平台的另一半故事。一、架构图解MCP 协议栈与插件全景┌─────────────────────────────────────────────────────────────────┐ │ MCP 协议栈 插件系统全景 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ 插件系统Plugin System │ │ │ │ Skills(.md) Commands(.md/.ts) Agents(.md) │ │ │ │ Hooks(hooks.json) MCP(.mcp.json) │ │ │ │ → 注册到各自子系统优先级999最低 │ │ │ └───────────────────────────────────────────────────────────┘ │ │ ▲ │ │ │ 插件安装时自动注册 │ │ ▼ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ 工具编排层Tool Orchestration │ │ │ │ 分区-批处理isConcurrencySafe → 并发/串行决策 │ │ │ │ 触发 PreToolUse/PostToolUse Hook │ │ │ └───────────────────────────────────────────────────────────┘ │ │ ▲ │ │ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ MCP 客户端层connectToServer 连接缓存 │ │ │ │ │ │ │ │ 8种传输适配器 │ │ │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │ │ │stdio │ │ http │ │ sse │ │ ws │ │ │ │ │ └──────┘ └──────┘ └──────┘ └──────┘ │ │ │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐ │ │ │ │ │sse-ide││ws-ide││ sdk ││claudeai- │ │ │ │ │ └──────┘ └──────┘ └──────┘ │proxy │ │ │ │ │ └──────────┘ │ │ │ │ │ │ │ │ 连接缓存memoize 本地/远程分组并发 │ │ │ │ 四层熔断指数退避 → 认证熔断 → 终端错误 → 会话过期 │ │ │ └───────────────────────────────────────────────────────────┘ │ │ ▲ │ │ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ 认证层OAuth State Machine │ │ │ │ pending → connected → failed / needs-auth │ │ │ │ 标准OAuth流程 XAA跨应用访问 │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘二、核心点拆解2.1 8 种 MCP 传输协议统一适配问题8 种协议1 个接口MCP 工具服务器可能运行在各种环境中——本地子进程通过标准输入输出通信远程服务通过 HTTP/SSE 连接IDE 通过 WebSocket 内嵌SDK 通过控制通道桥接。如何用统一的客户端接口屏蔽这些传输差异Claude Code 的connectToServer函数实现了8 种传输适配器统一收敛到 MCP SDK 的client接口传输类型适配器类连接方式特殊处stdioStdioClientTransport子进程 spawn本地最低开销sseSSEClientTransportServer-Sent Events OAuth远程流式httpStreamableHTTPClientTransport可流式 HTTP支持 POST 双向wsWebSocketTransportBun/Node 双运行时IDE 内嵌sse-ideSSEClientTransportSSE IDE Auth TokenToken 注入ws-ideWebSocketTransportWebSocket IDE Auth TokenToken 注入sdkSdkControlClientTransport控制消息桥SDK 集成claudeai-proxyStreamableHTTPClientTransportHTTP Claude.ai OAuth组织级认证这种设计的核心模式是**适配器模式Adapter Pattern**的极端版本——不是一个接口多种实现而是8种完全不同的通信协议统一到一个 Client 接口。每种适配器处理协议特有的连接建立、消息编解码、错误处理和断开重连。连接缓存与分组并发连接管理有两个关键优化连接缓存使用memoize确保同一配置只建立一次连接缓存键为${name}-${JSON.stringify(config)}。这避免了重复连接同一服务器的开销。本地/远程分组启动启动时按传输类型分组 本地传输stdio→ 低并发默认3避免子进程爆炸 远程传输http/ws→ 高并发默认20充分利用网络这种分组策略源于一个实际问题如果同时 spawn 20 个本地 MCP 服务器子进程在资源受限的机器上可能导致 OOM。但远程连接只是 TCP 握手20 个并发完全可以承受。InProcessTransport避免进程开销对于 Chrome MCP 和 Computer Use MCP 这样的重量级工具Claude Code 提供了InProcessTransport——直接在主进程内启动 MCP 服务器避免 325MB 的子进程开销。这是**“性能热路径特殊处理”**的典型实践。缓存失效onclose 的全面清理连接缓存最棘手的问题是失效。Claude Code 在onclose回调中执行全面清理// 连接关闭时清除所有相关缓存client.onclose(){memoizedConnect.cache.delete(cacheKey);// 连接缓存toolsCache.delete(name);// 工具列表缓存resourcesCache.delete(name);// 资源缓存commandsCache.delete(name);// 命令缓存// 确保下次调用重建连接};这种**“一次断开全面清理”**的策略确保了不会出现连接已断但缓存仍在导致的幽灵调用。2.2 四层渐进式故障恢复分级熔断MCP 连接可能因网络抖动、认证过期、服务器崩溃等原因断开。Claude Code 实现了四层故障恢复机制从轻到重逐层升级第一层指数退避重连 检测断开 → 检查是否禁用 → 更新为 pending → 等待退避时间 → 重连 1s → 2s → 4s → 8s → 16s (上限 30s) 最多5次失败后标记 failed 第二层认证缓存熔断 对返回401的服务器进行15分钟的短路缓存 const MCP_AUTH_CACHE_TTL_MS 15 * 60 * 1000; // 缓存命中时跳过连接注入 McpAuthTool 供用户手动认证 第三层终端错误计数 连续3次终端错误ECONNRESET/ETIMEDOUT/EPIPE/SSEdisconnected → 强制关闭 → 触发重连流程 第四层会话过期检测 HTTP 404 JSON-RPC -32001 (Session not found) → 清除连接缓存 → 重试一次 → 仍失败则报错这四层防御体现的核心模式是分级熔断Tiered Circuit Breaking故障级别触发条件恢复路径用户感知轻故障网络抖动自动重连最多5次无感中故障认证过期401熔断15分钟 注入McpAuthTool手动触发重新认证重故障终端错误连续3次标记 failed停止重试明确报错会话级HTTP 404 -32001清除缓存重试一次短暂延迟后恢复或报错每一级都有明确的触发条件和恢复路径避免了一刀切的粗暴策略。子进程的渐进式退出对于stdio类型的 MCP 服务器本地子进程Claude Code 实现了SIGINT → SIGTERM → SIGKILL的渐进式退出策略先礼貌请求退出再强制终止最后无条件杀死。每个阶段都有超时窗口确保子进程有机会做清理工作。2.3 OAuth 认证状态机Token 的完整生命周期连接状态的显式建模MCP 服务器的连接状态不是简单的连接/断开二值而是一个包含认证维度的复杂状态空间。Claude Code 将其建模为显式的状态机pending ─────→ connected │ │ │ ├── [onerror] ──→ pending重连 │ │ ├── [401] ──→ needs-auth │ │ ├── [失败超限] → failed │ └── [用户主动] → disabledMcpServerConnection使用**判别联合类型Discriminated Union**表达这些状态——每个状态携带不同的数据如needs-auth携带认证 URLfailed携带错误原因。这比一个状态字段 若干可选字段的类型设计更安全——编译器会强制处理每个状态分支。标准 OAuth 流程当 MCP 服务器返回 401 需要认证时Claude Code 启动标准 OAuth 流程RFC 8414/9728发现授权服务器元数据启动本地回调服务器随机端口避免端口冲突打开浏览器 → 用户授权 → 回调获取authorization_codecode PKCE(Proof Key for Code Exchange) →Access TokenToken 安全存储macOS Keychain / Windows Credential ManagerPKCE 是 OAuth 2.1 的必要安全机制防止授权码被中间人截获后使用。XAA 跨应用访问流程对于企业内部的跨应用场景Claude Code 还支持 **XAACross-Application Access**流程OIDC 登录 → 获取 id_token缓存复用避免重复登录 → RFC 8693 Token Exchange: id_token → ID-TAG → RFC 7523 JWT Bearer Grant: ID-TAG → access_token这是一个三步令牌变换链每一步都遵循标准 RFC 规范。XAA 的核心价值是用户只需登录一次OIDC就能访问多个内部系统无需每个系统都单独认证。Token 管理的细节Token 生命周期管理中有几个值得注意的实现细节Step-up 认证wrapFetchWithStepUpDetection处理权限不够需要更高级别认证的场景强制刷新重试createClaudeAiProxyFetch支持收到 401 后的一次性强制 Token 刷新重试——只重试一次避免死循环安全存储Token 不存放在文件中而是使用操作系统级的凭证管理器防止明文泄露2.4 分区批处理工具编排并发与正确性的精确平衡问题多工具调用的执行顺序LLM 可能在一次响应中返回多个工具调用。这带来一个关键问题哪些工具可以并发执行哪些必须串行直觉上文件读取是安全的——并发读 10 个文件不会相互影响。但文件编辑就不行——如果两个编辑操作修改同一个文件并发执行会导致冲突。Shell 命令更加复杂——git add . git commit -m fix这样的命令序列显然不能乱序执行。分区-批处理策略Claude Code 的toolOrchestration.ts实现了一种**分区-批处理编排模式**LLM 返回 tool_use[] → partitionToolCalls → Batch[] ├── 按 isConcurrencySafe 分区 ├── 连续安全工具 → 合并为一个并发批次 └── 不安全工具 → 单独作为串行批次并发批次Promise.all(runToolUseN)上限10 并发上下文修改延迟收集批次完成后按序应用串行批次逐个runToolUse上下文修改立即应用注意上下文修改的处理方式并发批次中的工具可能都会修改对话上下文但并发执行时无法确定顺序。Claude Code 的策略是延迟收集、按序应用——先并发执行所有工具收集各自的上上下文修改批次完成后按工具在原始数组中的顺序依次应用。Hook 集成工具编排与 Hook 系统紧密集成。每个工具执行前后都会触发PreToolUse/PostToolUseHookHook 可以修改工具输入参数做出权限决策allow/deny修改 MCP 工具的输出结果但权限决策遵循**“安全优先原则**Hook 返回的allow不能绕过settings.json中的deny/ask规则。这确保了 Hook 不能被用来越权”——一个恶意插件无法通过 Hook 给自己开放被系统禁止的工具。2.5 插件系统Skills、Commands 与 Agents 的模块化组合为什么 Hook 和 MCP 还不够Hook 是行为级扩展——在生命周期节点注入逻辑片段。MCP 是能力级扩展——接入外部工具和资源。但还有一类需求它们无法优雅满足工作流级扩展。考虑这样的场景团队需要一套标准化的代码审查流程——包含一个特定的 Agent 定义带专用 system prompt 和工具白名单、几个配套的斜杠命令如/review和/approve、一组 Hook提交前自动运行 lint、甚至自定义的输出样式。这些组件分属 Hook、MCP、Agent、Command 四个不同的子系统单独配置既繁琐又容易遗漏。这就是插件系统要解决的问题将分散在多个子系统中的组件打包为一个可分发、可安装、可管理的模块。插件的整体架构Claude Code 的插件系统由三种核心组件构成每种对应不同的扩展粒度组件定义格式运行时行为典型场景SkillsMarkdown Frontmatter注入 System Prompt不执行代码工作流模板如提交前必须跑测试Commands.md文件 / TypeScript 模块响应斜杠命令本地即时执行/review、/deploy等自定义命令AgentsMarkdown Frontmatter启动子 Agent拥有独立工具白名单代码审查 Agent、测试 Agent三种组件的设计哲学截然不同Skills是提示级扩展。本质上是结构化的 System Prompt 片段通过skillTool动态注入到对话上下文中。Skill 不执行任何代码它只改变 Agent 的思维方式。Commands是行为级扩展。分为三种类型PromptCommand最轻量.md文件即命令支持$ARGUMENTS占位符LocalCommand用于/compact、/clear等无 UI 操作LocalJSXCommand用于/config、/help等需要全屏界面的场景所有命令都采用懒加载load: () Promise确保未使用的命令不消耗启动时间。Agents是编排级扩展。通过 Markdown Frontmatter 定义 Agent 类型——正文作为 system promptYAML header 声明工具白名单、模型配置等元数据。插件的目录结构与清单Claude Code 通过约定优于配置的目录结构定义插件my-plugin/ ├── .claude-plugin/ │ ├── plugin.json # 插件清单PluginManifest │ └── marketplace.json # Marketplace 入口 ├── commands/ # 斜杠命令.md 文件或 TypeScript 模块 ├── agents/ # Agent 定义.md 文件 Frontmatter ├── skills/ # Skills子目录 SKILL.md ├── hooks/ # 生命周期钩子hooks.json ├── output-styles/ # 输出样式定制 ├── .mcp.json # 内嵌 MCP 服务器配置 └── .lsp.json # LSP 服务器配置plugin.json是插件的清单文件声明插件的名称、版本、依赖关系和能力矩阵。关键字段包括依赖声明指定插件依赖的其他插件支持版本约束能力声明列出插件提供的 Commands、Agents、Skills、Hooks 和 Output StylesMarketplace 归属标明插件来源的 Marketplace用于安全策略评估注意目录结构中包含了.mcp.json——这意味着插件可以内嵌 MCP 服务器配置。这是一个精巧的设计插件安装时自动注册其依赖的 MCP 服务器卸载时自动清理避免了手动管理 MCP 配置的麻烦。发现、加载与注册插件的生命周期包含三个阶段发现 → 加载 → 注册。发现阶段pluginLoader.ts扫描预定义的插件目录查找包含.claude-plugin/plugin.json的子目录。发现过程是递归的支持嵌套插件结构。加载阶段解析plugin.json清单验证格式和版本兼容性。这个阶段的关键是依赖解析——dependencyResolver.ts使用 **DFS深度优先搜索**遍历依赖闭包具有三个安全规则循环检测使用栈检测循环依赖 → 发现即报错跨 Marketplace 阻断默认阻止跨 Marketplace 依赖除非在allowCrossMarketplaceDependenciesOn中显式允许裸名解析无marketplace后缀的依赖继承声明插件的 Marketplace跨 Marketplace 阻断是一个重要的安全决策。想象一个场景企业内部 Marketplace 的插件 A 依赖了公共 Marketplace 的插件 B——如果 B 被恶意替换A 也会受到影响。默认阻断这种跨域依赖从源头切断供应链攻击。注册阶段加载完成的插件组件被注册到各自的子系统中插件加载完成 → 分发注册 ├── Commands → 合并到全局命令注册表loadPluginCommands ├── Agents → 合并到 Agent Type RegistryloadPluginAgents ├── Skills → 注册到 skill 发现目录子目录扫描 SKILL.md ├── Hooks → 合并到 Hook 配置优先级999 ├── MCP → 注入 dynamicMcpConfig复用现有连接管理 └── Output Styles → 注册到输出样式表注意 Hook 的注册优先级是999最低。这确保了用户设置优先级0、项目设置优先级1和企业策略优先级3都能覆盖插件提供的 Hook。插件永远是最低优先级的配置来源。插件安全模型插件加载到主进程地址空间比 MCP 的进程级隔离风险更大。Claude Code 通过三层安全机制进行防护第一层企业策略过滤pluginPolicy.ts企业管理员可以通过策略文件精确控制哪些插件允许安装策略评估链按优先级 1. blocklist — 明确阻止的插件黑名单优先 2. strictKnownMarketplaces — 仅允许已知来源的 Marketplace 3. hostPattern — 正则匹配允许的插件仓库域名 4. pathPattern — 正则匹配允许的插件路径这四层策略构成了一个先否后允的裁决链blocklist 一票否决strictKnownMarketplaces 限制来源hostPattern 和 pathPattern 提供细粒度的正则匹配。第二层信任边界隔离信任级别机制隔离方式适用场景低不可信MCP进程级隔离第三方工具服务中可信生态Plugin主进程 策略过滤社区贡献的扩展包高内部信任Skill纯 Prompt无代码执行团队工作流模板Skill 内容即使被恶意注入其影响范围也仅限于 Agent 的思考不会直接操作文件系统或网络。当然Agent 可能因为恶意 Prompt 而执行危险操作但这会被第5章的权限模型和第八章的安全纵深防御拦截。第三层Hook 命名空间隔离每个插件的 Hook 使用独立的命名空间通过\0空字符分隔符的复合键实现隔离。这确保了不同插件的 Hook 不会产生命名冲突也使得管理员可以精确地禁用或覆盖特定插件的特定 Hook。2.6 跨模式协作全景让我们退一步看看第9章解析的九个设计模式如何协同工作Agent 核心循环QueryEngine │ ┌─────────────────┼─────────────────┐ │ │ │ 工具编排(模式8) Hook事件总线(模式1) MCP工具(模式5/6/7) │ │ │ ├── 触发 Pre/PostToolUse Hook │ ├── 发起 MCP 工具调用 │ │ │ │ ▼ ▼ ▼ 分区批处理 多态执行器 传输适配器 (模式9) (模式2) (模式6) │ │ │ └─────────────────┼─────────────────┘ │ 分级配置合并(模式4) Hook 和 MCP 统一仲裁左侧是 MCP 外部集成线模式5/6/7从传输适配到连接管理到认证处理层层深入。右侧是 Hook 内部扩展线模式1/2/3从事件总线到执行器到会话隔离逐层细化。**模式4分级配置合并**横跨两侧为 Hook 和 MCP 提供统一的配置解析。**模式8工具编排**位于顶层既触发 Hook 事件又发起 MCP 工具调用是两条线的汇聚点。而插件系统模式9模块化组合容器则横跨两条线扮演组合容器的角色。插件将 Hook 定义、MCP 配置、Agent 类型、Skill 模板、Commands 打包成一个可分发的模块。插件不引入新的运行时机制——它的每个组件最终都注册到已有的子系统中运行。三、横向对比MCP 协议栈 vs 其他集成方案维度Claude Code MCPLSP语言服务器协议VS Code Extension APIOpenAI Function Calling协议类型JSON-RPC 2.0 over 8种传输JSON-RPC 2.0 over stdio/WebSocket直接 TypeScript API 调用JSON Schema 声明传输灵活性8种适配器统一接口2种stdio/WebSocket无进程内调用无HTTP API连接管理四层熔断 memoize 缓存简单的断开重连无扩展生命周期管理无每次请求独立认证OAuth 2.1 XAA 双流程无进程级隔离扩展自行处理API Key明文安全隔离进程级MCP/ 主进程Plugin进程级主进程无服务端验证扩展性插件系统打包分发无单个服务器Extension Pack无手动集成Claude Code 的 MCP 协议栈在传输灵活性和连接管理健壮性两个维度上显著超越其他方案。8 种传输适配器的设计虽然增加了复杂度但换来了同一个 MCP 服务器可以在任何环境下运行的灵活性——这是 Agent 系统需要支持多样化部署场景的必然选择。OpenAI Function Calling 最简单但也最脆弱——没有连接管理没有认证状态机每次请求都是独立的。这对于一次性工具调用足够但对于需要持久连接的 Agent 工作流则力不从心。四、实战启示启示一适配器模式的极端版本——协议无关性当你需要支持多种通信协议时不要试图统一协议这通常需要所有实现方同时升级而是适配协议——在客户端做协议转换让上层逻辑看到统一的接口。Claude Code 的connectToServer函数就是一个典范8 种传输协议统一收敛到一个 Client 接口。新增传输协议时只需添加一个适配器类不需要修改上层逻辑。启示二分级熔断比重试 N 次更智能简单的重试 N 次策略对待所有错误一视同仁——网络抖动重试5次认证失败也重试5次服务器崩溃还是重试5次。这是不对的。正确的设计是分级熔断轻故障网络抖动→ 自动重连用户无感中故障认证过期→ 熔断 提示用户操作重故障服务器崩溃→ 标记 failed停止重试每一级都有明确的触发条件和恢复路径。这比一刀切的粗暴策略更智能也比为每个错误类型写特殊逻辑更可维护。启示三判别联合类型比状态字段 可选字段更安全OAuth 状态机的类型定义如果用一个status字段 若干可选字段会出现忘记了处理某种状态的 bug而且编译器不会报错。用判别联合类型Discriminated Union编译器会强制处理每个状态分支。这是 TypeScript 中最强大的类型安全工具之一特别适合建模有多种可能状态每种状态携带不同数据的场景。启示四插件系统 约定目录结构 清单文件Claude Code 的插件系统没有用复杂的注册 API 或依赖注入框架而是用了最简单的文件系统约定——特定的目录结构就是注册表plugin.json就是清单。这种设计的好处是插件可以纯手工创建写一个目录 一个 JSON 文件也可以由工具生成插件的版本控制就是目录的版本控制插件的调试就是看目录结构对不对。VS Code 的 Extension 用了类似的思路但 Claude Code 更极致——连 Skill 都是一个.md文件开发者甚至不需要懂 TypeScript 就能创建 AI 命令。五、本篇小结概念一句话总结8种传输适配器stdio/sse/http/ws/sse-ide/ws-ide/sdk/claudeai-proxy统一收敛到 Client 接口连接缓存memoize 本地/远程分组并发 InProcessTransport 性能优化四层熔断指数退避 → 认证熔断(15min) → 终端错误计数(3次) → 会话过期检测OAuth状态机判别联合类型建模标准OAuth XAA跨应用访问Token操作系统级安全存储分区批处理isConcurrencySafe 分区 并发/串行混合 延迟收集按序应用上下文修改插件三组件Skills(Prompt级) Commands(行为级) Agents(编排级)约定目录结构打包插件安全三层企业策略过滤(4层裁决链) 信任边界隔离 Hook命名空间隔离配置优先级插件Hook固定999最低确保用户/企业策略可覆盖下期预告第16篇将深入第10章解析极简命令式 Store 与分层持久化——Agent 的记忆宫殿是如何构建的。30 行代码的 Store 实现、选择器驱动的细粒度订阅、单一 Diff 点的副作用闸门——这些设计体现了不要为你不需要的能力付出复杂度税的工程哲学。从扩展架构走向状态管理挑战从连接外部转向组织内部。本篇思考题插件系统将 Hook 优先级固定为999最低——这意味着用户和企业策略总能覆盖插件的 Hook 定义。你认为这个设计是否合理在什么场景下插件可能需要更高的优先级