MCP 生态与 Java 工程接入

• 理解 MCP Inspector 的功能与用途
• 掌握连接 Server 并检查各项能力
• 理解协议错误的排查

MCP Inspector 是官方调试工具，用于可视化检查和调试 MCP Server。用法：1) 启动 Inspector 并传入 Server 的启动命令（stdio）或连接 URL（streamable HTTP），连接后自动执行 initialize 握手；2) 检查初始化——在 Inspector 中查看 initialize 请求/响应，确认协议版本、capabilities、serverInfo 与 clientInfo 协商结果；3) 检查能力列表——查看 tools/list、resources/list、prompts/list 返回的工具/资源/提示模板，确认 Schema 与描述；4) 检查 Schema——查看每个工具的 inputSchema，验证参数定义正确；5) 资源读取——用 resources/read 读取资源 URI，验证内容与 MIME；6) 工具调用——用 tools/call 手动调用工具，传入参数，观察返回结果与错误；7) 协议错误——Inspector 能捕获 JSON-RPC 错误、非法消息、未协商的方法调用，帮助定位协议错误。Inspector 提供的交互式界面让开发者能单步验证协议交互，是 Server 开发与调试的必备工具。

MCP Inspector 是"协议层的调试工具"。它把 initialize、tools/list、tools/call 等交互可视化，让开发者能验证协议正确性、Schema 质量与错误处理，而不必写测试代码。它既用于本地开发调试，也用于复现生产请求。

• 理解最小能力设计
• 掌握幂等性与明确错误
• 理解版本兼容

封装订单/知识库服务为 MCP Server 时：1) 最小能力——只暴露业务真正需要的工具，不暴露"执行任意 SQL"这类宽能力；例如订单服务暴露 queryOrder、createOrder、cancelOrder，而非暴露整个数据库。2) 幂等性——写入类工具（createOrder、cancelOrder）用幂等键，重复调用返回相同结果而非重复执行；只读工具天然幂等。3) 明确错误——工具返回结构化错误（错误码、错误类型、可恢复性），区分"参数错误"（可让模型修正）与"系统错误"（不可恢复），不抛裸异常；错误信息对模型可读。4) 版本兼容——Schema 变更向后兼容（只增可选参数），用 SemVer 管理，拆分工具时保留旧工具兼容或弃用期。这些原则让封装后的工具安全、可预测、可长期演进。

封装业务服务的核心是把"内部能力"提炼为"安全、可预测、可演进的工具"。最小能力限风险，幂等防重复副作用，明确错误让模型可修正，版本兼容保证长期稳定。这与"面向模型设计工具"一脉相承。

• 理解 Schema 表达参数约束的方法
• 掌握封装时隐藏内部细节
• 理解面向模型与外部客户的 Schema 设计

封装 REST 服务为 MCP Tool 时，Schema 要"准确表达约束"且"不泄漏内部细节"。做法：1) 用 JSON Schema 表达参数约束——类型、必填、枚举、format、minimum/maximum、pattern，让模型正确构造参数；2) 用语义化命名与描述——参数名用业务语义（如 orderId、customerId），description 解释含义与取值，而不是暴露内部字段名或数据库列名；3) 隐藏内部细节——不暴露内部 token、内部端点、数据库结构、内部错误堆栈；只暴露对外契约（如订单状态枚举、金额格式）；4) 参数校验——Server 端按 Schema 校验并规范化为内部调用，把内部错误映射为对外可读错误；5) 敏感信息脱敏——返回结果中隐藏内部字段（如内部 ID、生产环境信息）。Schema 是"对外契约"，应面向模型与外部客户设计，把内部实现细节封装在 Server 内部。

Schema 是"对外的能力契约"，既要让模型准确构造参数，又要隐藏内部实现。用语义化命名 + 约束表达 + 校验规范化 + 脱敏，把内部 REST 的细节封装在 Server 内部，外部只看到干净、完整的工具契约。

• 理解 MCP Server 的核心可观测指标
• 掌握工具调用、错误、客户端与 token 指标
• 理解指标与告警、容量分析

MCP Server 可观测性应采集的指标：1) 工具调用指标——tools/call 总数、耗时分布（P50/P95/P99）、按工具分组的调用量，识别慢工具与热点工具；2) 错误指标——错误率、按错误类型/工具分组的错误分布，识别失败路径；3) 客户端维度——客户端 ID、来源、连接的 Server 数，用于识别异常客户端与多租户分析；4) token 指标——每次调用的 prompt token、completion token、总 token，用于成本分析与上下文预算；5) 资源指标——CPU/内存/连接数/队列深度，用于容量评估；6) 协议指标——initialize 失败、tools/list 次数、能力协商结果。这些指标配合 trace 与日志，形成完整可观测性，支撑排障、性能优化、成本治理与 SLA 监控。

MCP Server 可观测性要覆盖"调用、错误、客户端、token、资源"多个维度。工具耗时与错误率反映质量，客户端 ID 反映使用与多租户，token 反映成本与上下文。指标 + trace + 日志三支柱支撑可观测与治理。

• 理解命名空间隔离
• 掌握授权与路由
• 理解互不信任数据源的隔离

多 Server 同名工具或互不信任数据源场景下，Host 要同时在命名空间、授权、路由三层隔离。1) 命名空间隔离——给每个 Server 的工具加 namespace 前缀（如 github_search、jira_search），Client 暴露给模型时全局唯一，转发 tools/call 时移除前缀，避免模型混淆；2) 授权——按 Server 与用户/租户做权限隔离，互不信任的 Server 各自鉴权，用户只能调用其授权范围内的 Server 工具；数据源间不共享凭据，凭据绑定到 Server。3) 路由——按工具名/Server 路由到正确的后端，路由时校验目标 Server 的授权；对互不信任的数据源，用独立的信任边界（进程/容器隔离、独立上下文、注入净化），防止一个数据源的恶意内容污染另一个。命名空间保证"名字不冲突"，授权保证"权限不越界"，路由保证"调用到正确目标"，数据源隔离保证"内容不污染"。

多 Server 隔离是"命名空间 + 授权 + 路由 + 数据源隔离"的组合。命名空间解决同名冲突，授权解决越权，路由解决调用目标，数据源隔离解决信任污染。Host 层统一管理，保证互不信任的数据源在模型面前清晰、隔离、可追溯。

• 理解日志与分布式追踪的落地
• 掌握权限审查与审计
• 理解 Schema 契约与跨版本兼容测试

为 MCP 做可观测性与质量保障：1) 日志——结构化日志（JSON），记录请求 ID、工具名、耗时、状态、错误、trace id，分级管理，不记敏感参数；2) 分布式追踪——用 OpenTelemetry 为工具调用与 LLM 建 span，trace context 传播，关联成端到端链路；3) 权限审查——记录审计日志（谁调用了什么、参数 hash、审批人、时间），对敏感操作审查，支撑合规；4) Schema 契约测试——用 Schema 校验工具定义合法、参数符合 JSON Schema，验证描述与 Schema 一致，防止错误描述导致模型幻觉调用；5) 跨版本兼容测试——用契约测试验证新旧 Client 对 Schema 的兼容性（新增可选参数不破坏、删除参数被判为破坏性），CI 中跑新旧版本组合。这些实践共同保证 MCP 可观测、可审计、可演进、不破坏兼容。

这是"可观测 + 质量 + 兼容"的工程化。日志/trace 管可观测，权限审查管审计，Schema 契约管定义质量，跨版本测试管兼容性。它们构成 MCP Server 在生产环境长期稳定运行的基础设施。

• 理解 Inspector 复现生产请求的配置
• 掌握鉴权头、Sampling、Elicitation 的复现
• 理解本地调试与生产行为的对齐

MCP Inspector 复现生产请求需配置与生产对齐的上下文：1) 鉴权头——在 Inspector 中配置 Authorization 头（携 OAuth token 或 API Key），模拟生产认证，验证鉴权逻辑；2) Sampling 请求——若 Server 会发起 Sampling（请求 Host 调 LLM），Inspector 可模拟 Host 的 Sampling 响应，验证 Server 处理 Sampling 的路径；3) Elicitation——若 Server 发起 Elicitation（向用户请求信息），Inspector 可模拟用户提供信息，验证 Elicitation 流程；4) 其他——配置产物、会话头、cookie、环境变量与生产一致，复现具体的请求参数。Inspector 的交互界面让开发者能手动输入生产场景的参数、头与上下文，把生产请求的"输入"复现到本地，观察 Server 行为与协议交互，从而定位生产问题。关键是把"生产上下文"（鉴权、Sampling、Elicitation、参数）完整复现。

Inspector 复现生产请求的关键是"上下文对齐"。鉴权头、Sampling 响应、Elicitation 输入都是生产特有的上下文，Inspector 提供手动配置这些上下文的能力，让本地调试能重现生产行为。这比"只跑一个简单示例"更能暴露生产环境的问题。

• 理解 OpenAPI 到 MCP 的转换
• 掌握参数命名、必填与安全标记的保留
• 理解转换的忠实性与信息损失

OpenAPI 转 MCP Server 时，要忠实保留契约信息：1) 参数命名——保留 OpenAPI 的 operationId 与参数名（或按语义映射为工具名），参数保持原命名，避免转换后歧义；2) 必填——把 OpenAPI 的 required 数组映射为 Schema 的 required，保留参数必填性，防止模型漏传必填参数；3) 安全标记——把 OpenAPI 的 security 定义（OAuth/OAuth2/Bearer/API Key）映射为 MCP 的认证要求，保留哪些端点需要哪些 scope/认证，避免工具未经认证暴露；4) 数据类型与枚举——保留 type、enum、format、default 等约束；5) 描述——保留 summary/description 作为工具描述。转换工具（如 OpenAPI→MCP 转换器）应能忠实映射这些字段，转换后做契约对比测试验证信息无损。对无法自动映射的（如复杂的 auth 流程、内部实现），需人工补充。

OpenAPI 转 MCP 的挑战是"契约映射的忠实性"。参数命名、必填、安全标记、类型约束都要保留，否则模型会传错参数或越权调用。转换后做契约对比验证，确保信息无损，是自动转换的工程保障。

• 理解 Server 选择的路由维度
• 掌握按用户、租户、场景选择
• 理解优先级与兜底

自研与公共 Server 共存时，Host 要能自动选择合适 Server。选择维度：1) 按用户——高权限/企业用户优先用自研 Server（数据不出域、更可控），外部/低权限用户可能用公共 Server；2) 按租户——租户数据隔离要求自研 Server，公共 Server 用于无租户敏感数据的场景；3) 按场景——高频/核心业务用自研 Server（性能、功能、合规），低频/通用能力（如网络搜索、天气）用公共 Server；4) 按数据敏感性——敏感数据（用户信息、订单）强制走自研 Server（数据不出域），非敏感走公共。实现上，Host 维护"Server 路由规则"（用户/租户/场景 → Server），为工具打分排序，选择得分最高者；对同一意图的多个 Server 做优先级与兜底。选择要可审计（记录为何选此 Server），并支持灰度切换。

自动选择 Server 的本质是"路由策略 + 多维度打分"。用户、租户、场景、数据敏感性决定哪个 Server 合适，Host 用规则路由到最优 Server，并对敏感数据强制走自研保证合规。可审计与灰度保证选择可控。

• 理解 MCP 与 API Gateway 的关系
• 掌握暴露策略（全量 vs 精选）
• 理解暴露权衡

MCP 与传统 API Gateway 不是替代关系，而是互补：API Gateway 是"所有 API 的统一入口"（认证、限流、路由、治理），MCP 是"面向 Agent 的工具抽象层"。MCP Server 通常作为 API Gateway 之上的封装，把内部 API 提炼为模型可用的工具，仍可复用 Gateway 的认证/限流/审计。并非所有内部 API 都应暴露为 MCP：应只暴露"高频、低敏感、适合 Agent 调用"的操作——即模型确实会用、且暴露风险可控的能力。低频、高敏感、复杂流程的操作不应暴露为 MCP（或用更严格授权）。暴露权衡：MCP 工具是模型可自主调用的能力，暴露面越大，误用与安全风险越大；且工具注入占上下文。因此"精选暴露"优于"全量暴露"——只把模型需要、且安全可控的操作封装为工具，其余仍走传统 API。

MCP 与 API Gateway 是"能力层"与"入口层"的关系。MCP 复用 Gateway 的治理，但暴露策略要精选——只暴露高频、低敏感、Agent 真正需要的操作。全量暴露会放大安全面与上下文占用，精选暴露是工程上更优的选择。

• 理解错误传播层级
• 掌握用户友好提示与调试信息保留
• 理解错误分类与脱敏

MCP 错误传播要分层：Server 端把工具错误/内部异常规范化为结构化 JSON-RPC 错误（错误码、错误类型、可恢复性、用户可读消息），区分"用户可恢复错误"（参数错误、权限不足）与"系统错误"（内部异常）。Client 端处理：1) 用户友好提示——把结构化错误映射为面向用户的清晰提示（如"订单号格式不正确，请检查"），用可读语言而非技术堆栈；2) 保留调试信息——把调试细节（错误堆栈、内部上下文、trace id）单独记录到日志/观测，关联 trace id，不直接展示给用户；3) 脱敏——用户提示不含内部细节（DB 地址、堆栈、密钥），调试信息也脱敏敏感字段；4) 可恢复性——对可恢复错误，Client 可让模型修正参数重试或引导用户；对系统错误，提示"服务暂时不可用"并告警。核心是"给用户可读的提示"与"给工程师完整的调试信息"分离，通过 trace id 关联。

错误传播的关键是"用户可读 + 调试可溯源"的分离。Server 把错误结构化，Client 把用户可读消息与调试信息分别处理，用 trace id 关联。用户提示不暴露内部细节，调试信息完整保留供排障。

• 理解不同来源的信任差异
• 掌握信任级别的判定
• 理解第三方目录的审查门槛

官方 SDK、参考 Server 与第三方目录（mcp.so、glama.ai 等）的信任级别不能等同，原因：1) 官方 SDK——由 MCP 组织维护，协议实现经过严格验证、更新同步、文档完善、有明确治理，信任级别最高；2) 参考 Server——官方提供的示例实现，展示最佳实践，质量较高但多为示例性质，可能非生产级；3) 第三方目录——mcp.so、glama.ai 等是社区聚合目录，收录大量第三方 Server，只做"收录/展示"，不保证每个 Server 的安全性、质量与维护，甚至可能收录恶意或低质 Server。第三方目录的"收录"不等于"背书"，其 Server 的代码审计、依赖安全、权限声明、活跃度都要企业自行审查。信任级别应判定为：官方 SDK > 参考 Server > 第三方目录中的 Server（需严格审查）。第三方目录可作为"发现入口"，但不可作为"信任来源"。

信任级别差异源于"来源与治理"。官方 SDK 有严格治理与验证，参考 Server 展示最佳实践，第三方目录只是聚合展示，无审查背书。因此第三方目录的 Server 必须经企业自查（源码、依赖、行为、权限）才能信任，不能因其"被收录"而等同官方。

• 理解 MCP 与 Skills 的差异
• 掌握运行时发现 vs 预定义能力包
• 理解组合使用的划界

MCP 与 Skills 是两种不同的能力机制。MCP 是"运行时发现协议"：通过 tools/list 在运行时动态发现工具，能力可动态变化、跨进程/Server 互操作，是协议。Skills 是"预定义能力包"：把一组提示词、指令、工具调用模板打包成可复用的能力（如 Claude 的 Skills），在客户端本地加载，不依赖运行时发现协议，是静态定义的能力包。差异：MCP 强调跨进程动态发现与互操作，Skills 强调本地预定义、可复用、灵活的特性（系统性能力）。组合使用的划界：MCP 用于"需要动态发现、跨进程/远程的工具/资源"；Skills 用于"本地预定义、可复用的方法论/工作流"。当一个能力需要动态工具调用时用 MCP，需要固定流程/知识时用 Skills；两者可组合（Skills 内部可调用 MCP 工具）。划界原则是"能力是否需运行时发现/跨进程"。

MCP 与 Skills 的差异是"协议 vs 能力包"。MCP 是动态发现协议，Skills 是预定义能力包。组合时按"是否需运行时发现/跨进程"划界——远程动态工具用 MCP，本地复用流程用 Skills，可嵌套组合。

• 理解只读模式（dry-run）的价值
• 掌握 dry-run 的实现方式
• 理解 dry-run 与真实执行的结合

MCP Server 支持只读模式（dry-run）有明确价值：让用户/模型在生产环境"先预览效果"再实际执行写操作，降低误操作风险。设计：1) dry-run 模式返回"将要执行什么、会产生什么影响"（如将要删除的数据、将要创建的订单、影响的金额），但不真正执行副作用；2) 实现方式——工具加 dryRun 参数，或提供独立的"预览"工具/Server 只读模式；3) 展示影响——dry-run 返回结构化"影响预览"，让用户确认后再调用真实版本；4) 与 HITL 结合——高风险写操作先 dry-run 预览，用户确认后执行真实操作。只读模式在生产环境尤其有价值（避免误删、误下单），但要注意 dry-run 也需鉴权与审计（预览本身可能透露数据）。对只读工具天然无副作用，无需 dry-run；对写操作推荐提供 dry-run 预览。

dry-run 的价值是"把不可逆操作变成可预览操作"。通过预览影响、用户确认、再执行，把高风险写操作的试错成本降到最低。它承接了 HITL 的安全理念，特别适合生产环境的破坏性/高影响工具。

• 理解 Schema 自动测试的价值
• 掌握避免幻觉式调用的方法
• 理解 CI 中 Schema 校验

MCP Server 的 Schema 应在 CI 中自动测试，因为 Schema 与描述直接决定模型的调用行为，错误 Schema 会导致模型"幻觉式调用"（传错参数、选错工具、调用不存在的工具）。CI 中自动测试的内容：1) Schema 合法性——用 JSON Schema 校验每个工具的 inputSchema 合法、类型/必填/枚举正确；2) 描述一致性——校验描述与 Schema 一致（描述提到的参数在 Schema 中有定义、语义匹配），发现矛盾；3) 参数覆盖——用 Schema 生成/校验测试参数，验证模型常见的调用参数能通过校验；4) 工具名唯一性——校验工具名合法唯一，避免冲突；5) 兼容性——契约测试验证 Schema 向后兼容，防止破坏性变更。通过 CI 自动测试，能提前发现"描述误导模型"或"Schema 不合法"的问题，避免上线后模型幻觉式调用。错误描述与 Schema 是模型误用的根源，CI 测试是防线。

模型幻觉式调用的根源之一是"Schema/描述质量差"。CI 自动测试作为"质量闸门"，在发布前校验 Schema 合法性、描述一致性、参数有效性、兼容性，把"会导致模型误用的缺陷"挡在 CI 内，而非上线后暴露。

• 理解不能假设最小权限的原因
• 掌握 Client 校验 capability 的方法
• 理解主动校验与防御

不能假设所有 MCP Server 都遵循最小权限原则，因为：1) Server 是外部代码，可能声明了远超所需的能力（如普通查询工具却声明了写权限）；2) 恶意 Server 可能故意声明高风险能力或注入恶意描述；3) 第三方 Server 质量参差，其"声明"不代表"实际安全"。因此 Client 端应主动校验 Server 返回的 capability：1) 能力声明校验——核对 tools/list 返回的工具名称、Schema、annotations 是否合理，拒绝可疑声明（如工具名冲突、描述含注入、能力超范围）；2) 权限校验——对 Server 声明的能力做最小权限审查，只启用 Client 认可的、需要的工具，高风险工具（destructive、openWorld）默认禁用或需审批；3) 调用时校验——每次 tools/call 前校验目标工具是否在"已授权清单"内，不在则拒绝；4) 行为监控——对 Server 的实际行为做审计与告警，发现越权行为则隔离。Client 把 Server 的"声明"当作"待校验的输入"，而非"可信的契约"。

Server 的 capability 声明是"外部输入"，不可信。Client 要主动校验：能力声明是否合理、权限是否最小、工具是否在授权清单、行为是否越权。把"声明"与"授权"分离，Server 声明什么不等于 Client 允许什么，这是防御式集成的关键。

• 理解 Spring AI 2.0 的 MCP 能力
• 掌握选型考量（Spring AI vs 官方 Java SDK）
• 理解接入 Spring 安全边界

Spring AI 2.0 内置了 MCP Client/Server 支持，与官方 Java SDK 是两种接入方式。选型考量：Spring AI 的 MCP 组件与 Spring 生态深度集成（自动配置、依赖注入、与 Spring AI 的 Agent/Tool 抽象整合），适合已在 Spring Boot 的 AI 项目；官方 Java SDK（io.modelcontextprotocol:java-sdk）是协议层 SDK，更底层、更贴近协议，适合需要精细控制协议细节或非 Spring 项目。接入现有 Spring 安全边界：1) 复用 Spring Security——MCP Client 的认证复用现有 Spring Security 上下文（用户、角色、权限），工具的调用鉴权基于当前登录用户；2) 权限校验——在 MCP Client 调用工具前做权限校验（基于 Spring Security 的授权），只允许授权用户调用授权工具；3) 审计——用 Spring 生态的审计机制记录工具调用；4) 配置管理——MCP Server 的连接配置走 Spring 配置（application.yml），密钥走 Spring 的配置加密/Vault。选型原则：深度 Spring 集成用 Spring AI MCP，精细协议控制用官方 SDK，且两者都要接入 Spring Security 做统一鉴权。

选型是"生态集成深度 vs 协议精细度"的权衡。Spring AI MCP 与 Spring 生态深度集成、自动配置、复用安全边界，适合 Spring 项目；官方 Java SDK 更底层。无论哪种，接入 Spring Security 复用现有鉴权是安全的关键。

• 理解 Spring AI 的 MCP Client 自动发现
• 掌握多 Server 注册（stdio + HTTP）
• 理解配置驱动的注册

Spring AI 通过配置与自动配置机制让 MCP Client 自动发现并注册多个 Server。方式：1) 配置驱动——在 application.yml 中声明多个 MCP Server 的连接信息（stdio 用 command 与 args，Streamable HTTP 用 url 与认证），Spring AI 启动时自动为每个 Server 创建 Client 并注册；2) 自动配置——Spring AI 的 McpClientAutoConfiguration 读取配置，为每个 Server 创建 McpClient，并注册到 Spring 容器；3) 工具注册——Spring AI 把每个 Client 的工具拉取并注册为 Spring AI 的 Tool，供 Agent 使用；4) 命名空间——多 Server 下可通过配置给每个 Server 加前缀/命名空间，避免工具冲突。示例配置可同时声明 stdio（如 npx 启动的本地 Server）与 Streamable HTTP（远程 URL）Server，Spring AI 统一管理其生命周期与工具注册。这样"声明式配置"就能自动发现并注册多个 Server，无需手写连接代码。

Spring AI 的自动发现是"配置驱动的声明式注册"。application.yml 声明多个 Server（stdio/HTTP），Spring AI 自动创建 Client、拉取工具、注册到容器与 Agent。这降低了多 Server 接入的样板代码，是 Spring AI 生态集成 MCP 的价值。