FDE W7D3 学习手册 · Spring AI MCP Client / Server 与 Observability

W7 周级拆解 Day3 · A 级（必须掌握，面试核心）· 约 4h · 学完能讲清"用 Spring AI 既能调 MCP Server、又能把 Java Tool 暴露成 MCP，并打通可观测 Trace"

一、MCP 协议回顾（W2 写过的保单 / 规则 Server）

1.1 什么是 MCP

MCP（Model Context Protocol）是 Anthropic 提出的开放协议，统一了"模型 / Agent 如何连接外部数据源和工具"。它把"工具、资源、提示"标准化成一套协议，Client 和 Server 按协议通信，不再为每个工具写专属适配。

1.2 与 W2 的关系

W2 我们把"保单查询、理赔规则校验"做成工具服务，当时是自定义协议/HTTP。MCP 就是把这些工具标准化——任何兼容 MCP 的 Client 都能发现并调用，不必关心内部是 Java 还是 Python 实现。

二、MCP Client：调用已有 MCP Server

2.1 能力

Spring AI 的 McpSyncClient / McpAsyncClient 连接远端 MCP Server，自动发现对方暴露的 tools，并把这些 tools 转成 Spring AI 的 ToolCallback，从而让 ChatClient 直接调用——和 W7D2 的本地 @Tool 体验一致，只是工具来自远端。

2.2 与本地 @Tool 的区别

三、MCP Client 配置（Stdio / HTTP transport）

3.1 两种传输

• Stdio：Client 启动 Server 子进程，通过标准输入输出通信。适合"同机、随用随起"的本地工具（如一个 Python 脚本）。
• HTTP / SSE：Client 通过 HTTP 连已部署的 Server。适合"独立部署、多 Client 共享"的生产服务（保险保单 Server 应选这个）。

// HTTP 方式连接已部署的保单 MCP Server
McpClientTransport transport = HttpClientSseClientTransport.builder("http://mcp-policy-svc:8081").build();
McpSyncClient client = McpClient.sync(transport).build();
client.initialize();
List<ToolCallback> callbacks = client.listTools(null).tools().stream()
    .map(t -> new McpToolCallback(t, client)).toList();
chatClient = ChatClient.builder(chatModel).defaultTools(callbacks).build();

四、MCP Server：用 Spring AI 暴露 Java Tool 为 MCP

4.1 能力

反过来，我们也可以把现有 Java 方法通过 Spring AI 的 @Tool + MCP Server starter 暴露成标准 MCP 协议，供任何 MCP Client（不限于 Spring AI）调用。

@Tool(description = "查询保单当前状态与保障范围")
public String queryPolicy(@ToolParam(description="保单号") String policyNo) { ... }

// 启动类加 @EnableMcpServer，starter 自动把 @Tool 暴露为 MCP tools
@SpringBootApplication
@EnableMcpServer
public class PolicyMcpServer { public static void main(String[] a){ SpringApplication.run(a); } }

4.2 价值

• 保单系统团队的 Java 资产，零改造暴露成 MCP，被 Python/JS/Spring 各类 Agent 复用。
• 统一治理：Server 侧可独立加鉴权、审计、限流。

五、同时做 Client 与 Server 的架构

一个 AI 平台应用常同时是：Client（调保单/规则 MCP Server）+ Server（把自己的特药推理能力暴露给上游）。

六、Observability 概览（Micrometer / Actuator）

6.1 三大支柱

6.2 为什么 AI 应用更需要可观测

• LLM 调用不可预测（时延高、可能失败、输出随机），必须有完整 Trace。
• 成本来自 token，必须按 trace/model 统计（呼应 W4 cost 字段）。
• 工具调用链长（模型→工具→回灌），需链路串联定位问题。

七、Trace 埋点（trace_id / model / tool）

7.1 要埋哪些字段

呼应 W4 定义的 Trace 字段，AI 调用至少要记：

7.2 在 Advisor 里埋

public class TraceAdvisor implements Advisor {
  public AdvisedResponse adviseCall(AdvisedRequest req, CallAdvisorChain chain){
     String tid = MDC.get("trace_id"); // 由网关/入口传入
     long t0 = System.nanoTime();
     AdvisedResponse resp = chain.nextAroundCall(req);
     Metrics.timer("ai.call", "model", currentModel, "tool", currentTool)
             .record(System.nanoTime()-t0, TimeUnit.NANOSECONDS);
     return resp;
  }
}

八、与 W4 Trace 字段打通

九、Metrics 指标（token、延迟、调用次数）

9.1 关键指标

9.2 结合大数据背景

把 Micrometer 指标导出到 Prometheus，再接 Kafka + 数仓做"按用户/按场景"的成本与质量分析——这正是 36 岁大数据候选人的优势落点。

十、候选人视角：企业 AI 平台可观测性定位

• 统一 Trace：所有 AI 调用经 Advisor 埋点，trace_id 贯穿 Gateway→应用→工具，对接现有 APM。
• 成本可控：token/cost 指标进数仓，按业务线/场景核算（保险各险种 AI 成本透明）。
• 质量可查：工具错误率、拒答率、幻觉率进监控大盘，异常告警。
• 合规可审：日志含 trace_id + 用户标识，理赔决策全程可追溯（监管刚需）。

十一、学习资源（中文 / 官方）

• Spring AI MCP 文档（docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html）——Client / Server / transport 精读。
• MCP 官方规范（modelcontextprotocol.io）——理解协议本身（tools/resources/prompts/transport）。
• Spring AI Observability 文档（docs.spring.io/spring-ai/reference/observability.html）——Micrometer 集成。
• B站：Spring AI 全套 84 集（BV1GfyGBqEm6）——MCP、可观测相关集。

十二、面试达标线①：Spring AI 怎么同时做 MCP Client 和 Server

十三、面试达标线②：Observability 怎么接 W4 的 Trace 字段

1. 字段对齐：W4 定义的 trace_id / model / tool / token / cost / latency / status 字段，在 W7D3 通过 Advisor 埋点 + Micrometer 上报实现——W4 是"规范(Why)"，W7D3 是"实现(How)"。
2. trace_id 贯穿：入口（Gateway/Controller）生成 trace_id，Advisor 里只取不新建，贯穿 Gateway→应用→工具，且要和 W7D4 Gateway 出口的 trace_id 一致。
3. 工具链路：工具调用要展开成子 span（模型→tool→回灌），不能扁平记一条；token/cost 取 ChatResponse 真实 Usage。
4. 对接现有监控：Micrometer 导出 Prometheus + 链路追踪，接数仓做成本/质量分析（呼应大数据背景）。

十四、W7D3 自测清单

十五、高频面试题速记卡