企业官网建设流程全解析

1. 为什么 MCP 集成测试总是跑不稳

如果你正在用 Spring AI 写 MCP Server，大概率遇到过这种场景：本地单测全绿，一上 CI 就随机挂；同一个用例今天过明天不过；权限拦截用例偶尔"漏网"，明明没权限却调通了。这类问题在面试里也是高频考点——面试官问的从来不是"你会不会写测试"，而是"你怎么让测试可重复、可追溯、可断言"。

MCP（Model Context Protocol）本质上是 Host 与 Server 之间的一套 JSON-RPC 约定，Server 暴露 Tool、Resource、Prompt 三类能力。集成测试的难点在于：它横跨了客户端、服务端、下游数据库、授权服务四个环节，任何一环状态漂移，结果就不可复现。传统只断言返回值的黑盒测试，看不到"权限校验到底有没有真的执行""下游 Span 有没有被误触发"，所以漏洞容易藏。

这篇要交付的是一套可跟做的方案：用 OpenTelemetry 把调用链变成断言依据，用 OAuth 2.1 测试授权服务覆盖权限场景，再通过 TaoToken 统一 Key/API 通道把模型侧调用稳定下来，避免测试因为 Key 轮换、额度波动而随机失败。适合正在做 Spring AI MCP Server、需要把集成测试接进 CI 的后端同学。下面从环境准备一路写到排障。

2. TaoToken 前置：统一 Key 通道解决测试抖动

MCP Server 的集成测试里，有一类失败特别隐蔽：测试用例本身逻辑没问题，但因为模型侧调用超时、Key 失效、额度耗尽而挂掉。你排查半天发现是环境问题，不是代码问题。这类抖动在 CI 里会被误判成回归失败，非常消耗信任。

我的做法是把模型侧调用收敛到一条统一通道。TaoToken 提供统一的 Key 与 API 入口，测试环境、预发环境、本地开发用同一套接入方式，Key 的轮换和额度管理在控制台集中处理，测试代码里不需要硬编码多个供应商的地址。这样集成测试关注的是 MCP 协议行为，而不是"今天哪个 Key 又过期了"。

具体接入分三步。第一步，在控制台创建测试专用 Key，和线上 Key 隔离，避免测试流量污染生产额度。第二步，把 API 基地址配置成https://taotoken.net/api，注意这个地址不带任何查询参数，保持干净。第三步，在 Spring AI 的配置里把模型客户端指向这个基地址，测试 profile 单独一份配置。

需要说明的是，TaoToken 在这里的角色是统一的模型调用通道，不是替代你的 MCP Server 或测试框架。MCP 协议行为、OAuth 授权、OpenTelemetry 采集这些核心逻辑，仍然由你自己的代码和测试基础设施负责。把通道统一之后，测试的变量就少了一个，可重复性自然提升。

如果你还没建 Key，可以先到控制台创建：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。建完之后建议立刻在本地跑一次最小请求验证通道是否通，别等到写完整套测试才发现连不上。

3. 可复制配置：settings.json 与 config.toml 骨架

配置是这套方案能不能落地的关键。我把它拆成两块：MCP 客户端侧的settings.json，和 Spring AI 服务侧的config.toml。两份配置都做了环境变量占位，方便在 CI 里注入不同环境的 Key。

先看 MCP 客户端侧的settings.json。这个文件描述 Host 如何连接 MCP Server，以及测试时如何注入 traceId 和 Authorization 头：

{ "mcpServers": { "internal-doc-server": { "transport": "streamable-http", "url": "http://localhost:8080/mcp", "headers": { "Authorization": "Bearer ${MCP_TEST_TOKEN}", "X-Trace-Id": "${MCP_TEST_TRACE_ID}" }, "timeoutMs": 8000 } }, "otel": { "exporter": "in-memory", "serviceName": "mcp-integration-test", "samplingRatio": 1.0 } }

这里有几个点值得展开。transport用streamable-http而不是 stdio，是因为集成测试需要跨进程、可并发，stdio 模式下 Server 的标准输出一旦被日志污染就会破坏 JSON-RPC 通信，这个坑后面排障章节会细说。X-Trace-Id由测试用例生成后注入，测试结束后用它去内存导出器里捞 Span。samplingRatio设成 1.0，保证测试期间不丢链路。

再看 Spring AI 服务侧的config.toml，重点是模型通道和 OAuth 资源服务器配置：

[spring.ai.openai] base-url = "https://taotoken.net/api" api-key = "${TAOTOKEN_API_KEY}" chat.options.model = "gpt-4o-mini" [spring.security.oauth2.resourceserver.jwt] issuer-uri = "http://localhost:9000" audiences = ["mcp-internal-doc"] [mcp.server] name = "internal-doc-server" transport = "streamable-http" tools = ["query_internal_knowledge", "download_approval_attachment"] [otel] exporter = "otlp" endpoint = "http://localhost:4317"

audiences这一项必须配。MCP 规范要求服务端校验 Token 的受众字段，防止 Token 混淆——也就是拿 A 服务的 Token 去调 B 服务。很多团队漏掉这一步，测试也测不出来，因为 mock 校验逻辑不会检查 audience。用真实授权服务就能覆盖到。

base-url指向 TaoToken 的 API 地址，Key 走环境变量注入。这样 CI 里只需要配置TAOTOKEN_API_KEY一个变量，不用为每个供应商维护一套配置。配置骨架就位后，下一步是把它跑起来并验证。

4. 验证请求：从授权到链路断言

配置写完不能直接信，得一步步验证。我习惯按"授权 → 调用 → 链路"三段来验，每段都有明确的成功标志。

第一段，验证 OAuth 2.1 测试授权服务能签发 Token。测试环境启动一个轻量授权服务，预置三类用户：普通员工只有knowledge:read，审批员有attachment:download，未授权用户无任何 scope。用 curl 拿一个普通员工的 Token：

curl -X POST http://localhost:9000/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id=mcp-test-client" \ -d "client_secret=test-secret" \ -d "scope=knowledge:read"

成功标志是返回体里有access_token和scope字段，且scope只包含knowledge:read。如果返回的 scope 多了，说明授权服务配置有问题，先修这里再往下走。

第二段，用这个 Token 调 MCP Tool。MCP 的 Tool 调用走tools/call方法，请求体里带上工具名和参数：

curl -X POST http://localhost:8080/mcp \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "X-Trace-Id: test-trace-001" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "query_internal_knowledge", "arguments": {"keyword": "年假规则"} } }'

成功标志是返回result里包含预期文档内容，且 HTTP 状态码 200。如果返回 401 或 403，先检查 Token 的 audience 是否匹配、scope 是否足够。

第三段，验证链路。测试结束后用 traceId 去内存导出器捞 Span，断言链路结构。正常调用应该有三层 Span：MCP Client → MCP Server → 知识库数据库，且所有 Span 状态为 OK。权限拦截用例则应该只有两层：MCP Client → MCP Server，Server 层 Span 带auth.error=insufficient_scope标签，且不触发下游数据库 Span。这个断言是整套方案的核心价值——它能看到黑盒测试看不到的逻辑分支。

把这三段串成一个 JUnit 用例，结构大致如下：

@Test void testNormalKnowledgeQuery() { String token = oauthTestServer.issueToken("user_001", Set.of("knowledge:read")); McpResponse resp = mcpTestClient.call("query_internal_knowledge", Map.of("keyword", "年假规则"), token, "test-trace-001"); assertTrue(resp.getResult().contains("年假上限10天")); List<Span> spans = otelExporter.getSpans("test-trace-001"); assertEquals(3, spans.size()); assertTrue(spans.stream().allMatch(s -> s.getStatus().isOk())); }

跑通这个用例，说明授权、调用、链路三段都通了。接下来是排障，这部分是面试和实战里最能拉开差距的地方。

5. 本篇常见错排查

错误一：stdio 模式下 Server 日志污染标准输出。现象是客户端收到一堆非 JSON 内容，解析直接失败。原因是 stdio 传输用标准输出传 JSON-RPC 消息，Server 里任何System.out.println都会混进去。解决方式是把日志重定向到标准错误或文件，Spring Boot 里配置logging.file.name或调整 logback 的 appender。集成测试建议直接用 streamable-http，从根上避开这个坑。

错误二：Token audience 校验缺失导致权限绕过。现象是权限拦截用例偶尔通过，也就是没权限的请求居然调通了。排查时先看服务端有没有配audiences，再看授权服务签发的 Token 里aud字段是否正确。MCP 规范明确要求校验受众，mock 校验逻辑很容易漏掉这一项，所以核心权限用例必须用真实授权服务。

错误三：测试数据未重置导致用例互相污染。现象是单跑通过、全量跑失败，或者用例执行顺序一变结果就变。根因是知识库测试表里残留了上一个用例的数据。解决方式是用容器化启动依赖中间件，每个用例前清空测试表并插入固定数据，保证输入输出完全一致。

错误四：OpenTelemetry Span 丢失导致断言失败。现象是getSpans返回空列表或数量不对。先检查 SDK 是否正确注入、采样率是否为 1.0，再检查测试并发是否导致 Span 被丢弃。兜底方案是加超时断言：超过业务阈值没返回就直接判失败，同时打印当时的 Span 列表辅助定位。

错误五：模型通道 Key 失效导致随机失败。现象是用例逻辑没问题但间歇性超时。这类问题最容易被误判成代码回归。把模型调用收敛到 TaoToken 统一通道后，Key 管理集中在控制台，测试环境用独立 Key，能大幅减少这类抖动。如果还是偶发，检查 CI 环境变量有没有正确注入。

6. 语义一致 CTA：把方案接进你的项目

这套方案的核心思路是通用的：容器化保证环境一致，OpenTelemetry 提供链路级断言，OAuth 2.1 真实授权服务覆盖安全场景，统一 Key 通道消除模型侧抖动。换成 Python 的 MCP SDK 也一样，替换客户端和采集器即可，断言逻辑不变。

落地时建议按这个顺序推进：先把模型通道统一到 TaoToken，拿到测试专用 Key，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各语言的最小接入示例。然后建 Key 并验证通道，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。通道通了之后，再搭 OAuth 测试授权服务和 OpenTelemetry 采集，最后写链路断言用例。

如果你还在选型阶段，想先验证模型通道能不能满足测试场景，可以直接在模型对话里试一轮：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 。长期做编码和 Agent 集成的团队，Coding Plan 会更省心：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。

最后留一个我踩过的坑：别在测试用例里硬编码 traceId，用UUID.randomUUID()生成后注入，测试结束按这个 ID 捞 Span。硬编码会导致并发跑用例时 Span 串台，断言结果完全不可信。这个细节很小，但直接决定测试能不能在 CI 里稳定跑。