MCP 与 Agent 生态集成

• 理解 Coding Agent 连接多个 MCP Server 的编排方式
• 掌握工具冲突与优先级解决
• 理解按任务场景选择工具

Coding Agent 通过配置文件（如 Claude Code 的 .mcp.json、Cursor 的设置）声明多个 MCP Server，启动时连接并用 tools/list 拉取各 Server 的工具，合并成一个工具集注入模型。编排要点：1) 能力域划分——Filesystem 处理文件读写、Git 处理版本控制、Playwright 处理浏览器自动化、Sentry 处理错误上报，各 Server 职责单一，减少重叠；2) 冲突解决——同名工具（如多个 Server 都有 read）用 namespace 前缀隔离（如 fs_read、git_read），或按优先级决定暴露哪个；3) 优先级——按任务场景/工具精度设定优先级，常用工具常驻，低频工具按需；4) 场景路由——Agent 根据当前任务（编译、测试、调试、CR）选择合适工具，避免跨域调用。Agent 还会在工具描述中标注来源 Server，让模型知道调用链。关键是把"多 Server 的工具"组织成对模型清晰、可区分、按场景可用的统一工具视图。

Coding Agent 编排多 Server 的核心是"能力域划分 + 冲突隔离 + 场景路由"。每个 Server 专职一类能力，同名工具用前缀隔离，模型按任务场景选择，避免跨域混乱。工具描述标注来源 Server 增强可追溯性。

• 理解 MCP（工具）与 A2A（Agent 间）的分工
• 掌握信任模型的衔接
• 理解状态管理与上下文传递

MCP 与 A2A 是互补的两层：MCP 连接 Agent 与本地/就近工具（文件、DB、API），A2A 连接 Agent 与远程 Agent（任务委托）。组合链路中，一个 Agent 先用 MCP 调用本地工具完成部分工作，遇到需要外部 Agent 的任务时通过 A2A 委托，接收结果后继续。信任模型衔接：MCP 的信任边界是"Agent-工具"（本地工具要最小权限、工具描述要防注入），A2A 的信任边界是"Agent-远程 Agent"（要验证 Agent Card、来源、认证、任务授权）。两者都要做身份认证与权限校验，但对象不同——MCP 校验工具权限，A2A 校验远程 Agent 身份与任务授权。状态管理衔接：MCP 工具调用是同步的、无状态的结果；A2A 任务是异步长任务（submitted/working/completed 状态机），Agent 需要把 A2A 任务状态与上下文保存，并在 MCP 工具调用与 A2A 委托之间传递共享上下文（如会话 ID、任务 ID、数据引用），保证整条链路可追踪、可恢复。

MCP 与 A2A 的衔接是"工具层 + 任务层"的组合。信任模型上，MCP 管工具权限、A2A 管远程 Agent 身份与授权；状态管理上，MCP 同步无状态、A2A 异步有状态，Agent 要协调两者并传递共享上下文。理解二者分工是 Agent 互操作的关键。

• 理解 Server 粒度的设计维度
• 掌握粗粒度与细粒度的取舍
• 理解按团队、领域与上下文设计粒度

Server 粒度决定 Agent 的能力边界与上下文开销。粗粒度大 Server：一个 Server 暴露大量工具（如"企业后端 Server"），优点是连接简单、工具集中、团队可共享；缺点是工具列表膨胀、上下文占用大、模型选择噪声大、权限与依赖耦合（一个 Server 变更影响面大）、故障半径大。细粒度单一职责 Server：一个 Server 只暴露一个领域/一种能力（如"订单查询 Server"、"Git 操作 Server"），优点是职责清晰、工具少而精、上下文省、权限最小化、故障隔离、可独立演进部署；缺点是 Server 数量多、连接管理复杂、跨 Server 协同需 Agent 编排。设计取舍：按"领域一致性 + 团队归属 + 上下文预算"划分——一个业务域/一个团队做一个 Server，每个 Server 聚焦单一职责，工具数量控制在模型可稳定选择的规模（如 <20）。避免"一个 Server 什么都管"和"一个工具一个 Server"两个极端。

Server 粒度是"能力聚合"与"隔离/上下文"的权衡。细粒度单一职责更符合"最小权限 + 上下文控制 + 故障隔离"，但需平衡 Server 数量。按领域/团队划分是常见实践，粒度以"模型可稳定选择 + 团队可独立维护"为准。

• 理解工具描述/Schema/结果占用上下文
• 掌握动态加载/卸载工具
• 理解上下文预算管理

MCP 的三类内容都会占用上下文：工具描述与 Schema 在 tools/list 后注入模型，占用"常驻"预算；调用结果在每次调用后追加，占用"动态"预算。大量工具时，常驻描述会很快吃掉窗口。动态加载/卸载策略：1) 按需加载——只把当前任务相关的 Top-K 工具加载进上下文（语义检索/场景路由），不相关工具不注入；2) 卸载——工具用完或上下文超限时，从上下文移除早期/无关工具调用结果，保留摘要；3) 分层——常驻高频工具 + 按需召回低频工具；4) 结果压缩——工具结果截断/摘要/分页，控制动态预算；5) 预算监控——跟踪上下文 token 用量，超阈值时触发压缩/摘要/卸载。动态加载/卸载的关键是"模型在当前上下文始终能看到它需要的工具，且总数受控"，避免上下文膨胀导致选择噪声与超限。

上下文预算管理是"常驻工具 + 动态结果"的总量控制。动态加载/卸载让模型每个时刻只面对"够用的工具集合"，而非全量。配合结果压缩与预算监控，保证上下文不超限且模型选择准确。

• 理解官方 SDK 的选择与成熟度
• 掌握错误处理与日志规范
• 理解测试策略

MCP Server 开发最佳实践：1) SDK 选择——用官方 SDK（TypeScript @modelcontextprotocol/sdk、Python mcp 等），它们封装了协议、传输（stdio/Streamable HTTP）、能力协商与消息处理，避免手写协议细节；SDK 成熟度与团队语言栈匹配。2) 错误处理——工具调用返回结构化错误（错误码、分类、可恢复性），把错误转成 JSON-RPC 错误响应，区分"用户错误"（参数错误，可让模型修正）与"系统错误"（不可恢复），不抛裸异常。3) 日志规范——用结构化日志（JSON），记录请求 ID、工具名、耗时、状态、错误，关联 trace id，日志分级（debug/info/warn/error），不记录敏感参数。4) 测试策略——单元测试（Mock Transport 下测工具逻辑）、集成测试（真实 Server 进程跑通协议）、契约测试（Schema 兼容性、工具名/参数不破坏）。最佳实践还要求 Schema 定义清晰、描述精炼、工具命令幂等、权限最小化。

最佳实践围绕"协议正确 + 可维护 + 可测试"。官方 SDK 保证协议正确，结构化错误与日志保证可观测可恢复，分层测试（单元/集成/契约）保证质量和兼容性。这些是 Server 能长期稳定演进的基础。

• 理解框架 Tool 抽象与 MCP 的差异
• 掌握桥接模式（适配器/转换）
• 理解双向集成（框架工具→MCP、MCP Server→框架工具）

框架（LangChain/LlamaIndex/Semantic Kernel）有各自的 Tool 抽象（如 BaseTool、ToolDefinition），而 MCP 是传输协议。桥接有两种方向：1) 框架工具 → MCP Server：把框架的 Tool 封装成 MCP Server，暴露给其他 MCP Client（如把 LangChain 工具包装成 MCP Server 供 Claude Code 使用）；2) MCP Server → 框架工具：框架的 Tool 适配器把 MCP 的工具（tools/list 拉取）转换成框架的 Tool 对象，供框架 Agent 调用。桥接模式通常用"适配器/转换器"：把 MCP 的 Tool 定义（name、description、inputSchema）映射为框架的 Tool 元数据，把框架的调用参数映射为 MCP tools/call 的 JSON 参数，并处理结果/错误的转换。集成要点是"Schema 映射、参数转换、错误映射、传输管理"的统一封装，让框架能透明地使用 MCP 工具。官方 SDK 与框架（如 LangChain MCP adapter）提供现成桥接。

桥接的本质是"MCP 协议与框架 Tool 抽象之间的适配"。MCP 是传输层，框架是编排层，通过适配器把两者映射起来，让框架的 Agent 能调用 MCP 工具，也让 MCP 生态的工具能被框架复用。Schema 与参数的互相映射是核心。

• 理解三层测试策略的分工
• 掌握 Mock Transport、真实 Server 与契约测试
• 理解测试覆盖与 CI 集成

MCP Server 测试分三层：1) 单元测试——用 Mock Transport（模拟 JSON-RPC 消息收发）直接测工具逻辑，不启动真实进程，快且隔离，覆盖工具的正确性、参数校验、错误处理；2) 集成测试——启动真实 Server 进程（stdio 或 Streamable HTTP），用真实 Client 连接，跑通 initialize/初始化、tools/list、tools/call 的完整协议流程，验证传输、能力协商、消息格式正确；3) 契约测试——验证 Schema 兼容性（工具名、参数、返回结构不破坏），用 Schema 校验工具定义合法、参数符合 JSON Schema，并对比新旧版本 Schema 的向后兼容性，防止破坏性变更。三层测试配合 CI：单元测试快速反馈，集成测试验证协议，契约测试守护兼容性。测试还应覆盖异常路径（超时、错误、断连、并发）与安全（注入、权限）。

三层测试覆盖"逻辑正确、协议正确、兼容性守护"三个层次。Mock Transport 隔离协议测逻辑，真实 Server 测协议，契约测试守护向后兼容。契约测试尤其重要，防止 Schema 变更破坏已发布的 Client。

• 理解 Tool/Resource/Prompt 三类原语的语义
• 掌握 Server 的职责边界划分
• 理解按团队与领域拆分

MCP Server 可以暴露三类原语：Tool（动作，模型可调用）、Resource（URI 数据，应用可读取）、Prompt（参数化模板，组织可复用）。职责边界设计：一个 Server 应围绕"一个领域/一种能力"组织，把该领域相关的工具、资源、提示模板聚合，避免混入无关能力的原语。判断"暴露什么"的准则：可执行的动作归 Tool；可读取的数据归 Resource（URI 形式）；可复用的提示/工作流归 Prompt，避免语义混用（如把只读数据暴露成 Tool 会造成误用）。按团队与领域拆分：一个业务域/一个团队负责一个 Server，每 Server 聚焦单一职责，遵循"高内聚、低耦合"——Server 内部工具高内聚，Server 间低耦合。粒度以"团队可独立维护 + 模型可稳定选择 + 领域边界清晰"为准。

Server 职责边界是"按领域聚合 + 按语义分原语"。Tool 是动作、Resource 是数据、Prompt 是模板，Server 把某领域的三者聚合，且不混入其他领域。按团队/领域拆分保证高内聚、可独立演进，也避免 Server 过胖或过碎。

• 理解三种传输的适用场景
• 掌握本地进程、远程服务与无状态网关的匹配
• 理解选型建议

传输选型匹配部署形态：1) stdio——适合本地子进程/单机工具（文件系统、本地 CLI、桌面应用），Server 与 Host 同机，通过标准输入输出通信，简单、无网络、最高本地隐私；不适合远程与多租户。2) Streamable HTTP——适合远程服务、无状态网关、多租户 SaaS、需水平扩展与标准 HTTP 基础设施（LB、限流、缓存）的场景，单端点 POST/GET + 可选 SSE，是目前推荐的标准远程传输。3) 旧 HTTP+SSE——历史远程方案，SSE 长连接在网关/负载均衡、断线重连、伸缩上有缺陷，已弃用，应迁移到 Streamable HTTP。选型原则：本地进程用 stdio，远程服务用 Streamable HTTP，避免新用旧 HTTP+SSE。无状态网关场景尤其适合 Streamable HTTP，因为它兼容 HTTP 语义、可无状态化、易被网关路由。

传输选型本质是"部署形态的匹配"。本地/单机用 stdio（无网络、简单），远程/可扩展用 Streamable HTTP（HTTP 语义、无状态、可网关化），旧 HTTP+SSE 因长连接缺陷被弃用。选型要避免"能用但难扩展/难运维"的组合。

• 理解 stdio 子进程的启动与生命周期
• 掌握崩溃重启与资源回收
• 理解防止孤儿进程与泄漏

stdio 模式下 Server 是 Host 的子进程，生命周期管理要点：1) 子进程启动——Host 用 spawn 启动 Server，传入环境变量与参数，连接 stdin/stdout；2) 心跳与健康——监测子进程是否存活，超时/无响应时判定异常；3) 崩溃重启——子进程崩溃或异常退出时，Host 按策略重启（指数退避），重启后重新 initialize 与拉取工具列表；4) 资源回收——Host 退出/关闭时，向子进程发送终止信号，等待退出，超时强制 kill，防止孤儿进程；5) 防止泄漏——对长时间运行的 Server 监控 CPU/内存/文件句柄，超限回收或重启；避免"僵尸进程"（Host 未 wait 子进程）。工程上把子进程生命周期纳入 Host 的进程管理器（如 Node 的 child_process 管理、守护进程），统一处理启动、重启、回收、退避，避免资源泄漏与孤儿进程。

stdio 子进程生命周期管理是"进程健康"工程。崩溃重启保证可用性，资源回收保证不泄漏（孤儿/僵尸进程），退避防止频繁重启。Host 作为父进程要负责子进程的完整生命周期，而非只负责通信。

• 理解不同语言开发 MCP Server 的性能差异
• 掌握生态与部署的取舍
• 理解选型考虑

Go、Rust、Java 开发 MCP Server 各有取舍。性能：Rust 原生性能最高、内存占用低、无 GC 停顿，适合高并发/低延迟/资源受限场景，但开发成本高、生态相对新；Go 性能好、并发模型优秀（goroutine）、编译为单二进制部署简单，适合高并发网络服务，是 MCP Server 推荐的编译语言之一；Java 性能好、生态成熟（Spring AI 提供 MCP 集成）、GC 成熟，适合企业级复杂业务，但内存占用高、启动慢/部署较重。生态：TypeScript/Python 官方 SDK 最成熟，Go/Rust/Java 也有官方或社区 SDK，但工具链与文档成熟度不一。部署：Go/Rust 编译为静态二进制，部署轻量（单一可执行文件）；Java 依赖 JVM，部署较重（需 JRE/容器/内存）。取舍：无官方 SDK 的语言（Rust/Go 早期）需付出协议实现成本；选型要结合性能需求、团队栈、生态成熟度与部署形态。

跨语言取舍是"性能、生态、部署"的权衡。Rust 高性能但成本高，Go 平衡性能与部署简单，Java 生态成熟但部署重。官方 SDK 的成熟度（TypeScript/Python 最成熟）也影响选型。选型要匹配团队与部署场景。

• 理解 MCP 的演进方向
• 掌握多模态、流式、Server 间通信与 Registry
• 理解对工程的影响

MCP 的未来演进围绕几个方向：1) 多模态 Tool——协议扩展支持图像、音频、视频等二进制数据的输入输出（如 audio data、image blob），让 Agent 能处理多模态工具；2) 流式 Resource——Resource 支持流式传输（持续推送更新而非一次性读取），配合 notifications/resources/updated 提供实时数据；3) Server 间通信——从"Client-Server 一对一"扩展到 Server 之间的协作/委托，让 Server 能互相调用或编排；4) 标准化 Registry——统一工具/Server 的发现与发布标准（如统一注册、版本、签名、搜索），让工具可被标准化发现与信任。这些演进在稳定核心之上作为扩展（draft extension）逐步完善，产品设计要用"能力协商 + 扩展隔离"接住新能力，避免破坏稳定核心。对工程的影响是：底层原语更丰富、可发现性更强、信任机制更标准化，但需持续跟踪协议版本与兼容性。

MCP 演进是"稳定核心 + 实验扩展"的叠加。多模态、流式、Server 间通信、Registry 都是扩展方向，解决"能力更丰富、数据更实时、协作更复杂、发现更标准"。工程上要隔离实验能力，靠能力协商安全接入，避免破坏稳定核心。

• 理解工具权限与凭证存储
• 掌握传输加密与认证
• 理解 Host 对远程 Server 的信任机制

MCP 安全边界要从工具权限、凭证、传输、信任四方面管理。工具权限：Server 只暴露最小权限工具，Host 对远程 Server 的工具做权限校验与审批（只读/高风险工具分级）。凭证存储：Server 的凭据（API Key、数据库密码）用密钥管理（Vault、KMS、Secret）存储，不作为环境变量明文暴露，不落日志；工具调用时按需注入最小凭据。传输加密：远程进行 TLS 加密，企业级用 mTLS 或 OAuth 2.1+PKCE 认证，防止窃听与冒充。Host 信任远程 Server：通过授权发现（OAuth 2.1）、Server 签名/来源验证、能力协商（只启用 Server 声明的可信能力）、以及"默认拒绝 + 工具级审批"来建立信任。Host 不应无条件信任远程 Server，而应把信任建立在"认证 + 签名 + 最小权限 + 审计"之上。

安全边界是"权限 + 凭据 + 传输 + 信任"的完整闭环。工具权限限能力，凭据管理防泄露，传输加密防窃听，信任机制防冒充。Host 对远程 Server 采取"默认拒绝 + 显式信任"，把信任建立在可验证的认证与签名上。

• 理解官方 SDK、参考 Server 与社区 Server 的定位
• 掌握成熟度评估维度
• 理解第三方 Server 引入审查

MCP 生态的成熟度分层：官方 SDK——由 MCP 组织维护，协议最准确、更新同步、文档完善，是首选；参考 Server（reference servers）——官方提供的示例实现，展示最佳实践，质量较高但可能非生产级；社区 Server——第三方贡献，质量参差不齐，需审查。成熟度评估维度：协议实现正确性、维护活跃度、测试覆盖、文档、依赖安全、权限声明、社区反馈。第三方 Server 引入前审查包括：1) 源码审计（异常网络/命令/敏感访问）；2) 依赖扫描（CVE、SBOM）；3) 沙箱运行验证行为；4) 权限与能力声明核对（是否过度索取）；5) Schema 与描述质量（是否会导致模型误用）；6) 维护活跃度（是否持续更新、有维护者）；7) 版本与签名验证。审查通过后才准准入，且持续监控。第三方 Server 的信任级别不能等同官方，因此审查门槛更高。

生态成熟度评估是"来源分层 + 实质审查"。官方 SDK 与参考 Server 可信度高，社区 Server 需严格审查。审查覆盖代码、依赖、行为、权限、Schema、活跃度，把"引入第三方 Server"作为受控的信任决策。

• 理解业务系统封装为 MCP Server 的鉴权要求
• 掌握幂等与审计要求
• 理解对敏感操作的保护

将数据库、文件系统、第三方 API 封装为 MCP Server 时，鉴权、幂等与审计是硬性要求。鉴权：Server 对接入方做身份认证与权限校验（用户/租户/工具级），数据库用最小权限账号，文件系统用路径白名单，第三方 API 用受控的凭据与 scope；读写操作区分权限。幂等：写入类工具（下单、更新、删除）需幂等键与去重，防止重试造成重复副作用；只读工具天然幂等。审计：记录谁调用了什么工具、参数、时间、结果、审批人，敏感操作（删除、金额变更、外部 API 调用）强制审计并可能需 HITL 审批。三者结合：鉴权保证"谁能调"，幂等保证"重复调用安全"，审计保证"调用可追溯"。对外部 API 的封装还要做参数校验、错误映射、数据脱敏与 rate limit。

业务系统集成 MCP 后，工具调用就代表真实业务副作用，因此必须"鉴权 + 幂等 + 审计"齐备。鉴权管边界，幂等防重复副作用，审计管追溯。这是把"内部 API 的安全要求"带到 MCP 工具层。

• 理解三种认证授权方式的适用场景
• 掌握部署形态与认证方式匹配
• 理解令牌最小化

三种认证方式适用于不同部署形态。OAuth 2.1：适合面向用户的远程服务，支持授权码+PKCE、scope 细分、刷新/撤销，适合多用户、需用户授权的场景；是 MCP 远程 Server 的推荐授权标准。API Key：简单、适合服务间/内部调用、机器对机器，无需用户授权，但缺少用户粒度与 scope 细分，适合低风险内部工具或网关的简单认证。mTLS：双向证书认证，适合企业内网/高安全环境、服务间强身份认证，防冒用，但证书管理复杂、不适合公网大规模用户。选型：公网多用户用 OAuth 2.1+PKCE，内部服务间用 API Key 或 mTLS，企业内网高安全用 mTLS。令牌最小化：只申请当前工具/Server 需要的 scope，令牌短时效、最小权限、按资源限定，避免令牌被用于其他资源（配合 Resource Indicators 绑定资源）。

认证选型匹配"部署形态与信任模型"。OAuth 2.1 面向用户授权，API Key 面向服务间，mTLS 面向高安全内网。令牌最小化是"最小权限 + 短时效 + 资源绑定"，防止令牌过度授权或被滥用。

• 理解断线重连与会话恢复
• 掌握会话持久化与状态同步
• 理解重放避免重复副作用

MCP Client 会话恢复设计：1) 断线重连——检测断线后指数退避重连，重连成功重新 initialize 与拉取工具列表；transport 用 session id（Streamable HTTP 的 Mcp-Session-Id）或标准重连（Last-Event-ID）恢复会话。2) 会话持久化——在无状态模式下，会话状态由 Client 持久化（存 DB/内存），Server 不保存长期状态；Client 在重连后恢复上下文（对话历史、任务进度、已调用工具）。3) 状态同步——Client 与 Server 重新协商能力、同步工具列表与订阅状态（notifications 重订阅）。4) 避免重放副作用——重连后的重放要防重复副作用：对写入工具用幂等键，重放携带同一幂等键让 Server 去重；Client 记录已确认的请求 ID，重放时跳过已确认的请求；对 in-flight 未确认的请求，重放需明确"是否已执行"（幂等或查询状态）。核心是"重连恢复上下文 + 幂等防重复副作用"。

会话恢复的关键是"不丢状态 + 不重副作用"。断线重连恢复连接，持久化恢复上下文，幂等键/请求去重防止重放副作用。无状态模式下 Client 负责状态管理，重放安全靠幂等保证。