1. 为什么 Java 团队需要自己写 MCP ServerMCP Server 是什么一句话说清它把后端系统里已有的能力查库、调接口、看监控、读配置包装成 AI 客户端能直接调用的标准工具让 Claude、IDE 插件、Agent 框架不用为每个模型写一套私有适配层。适合谁适合手里已经有 Spring Boot 服务、想让 AI 真正操作业务系统而不是只聊天的 Java 团队。我见过太多团队卡在同一个地方模型能回答问题但一让它查一下订单状态就歇了。原因不是模型不行而是业务能力没有以模型能理解的方式暴露出来。传统做法是给每个模型写 Function Calling 适配换模型就重写一遍测试、部署、权限全得跟着改。MCP 把这件事标准化了——Tool 描述、参数结构、调用协议统一Server 端只关心我能安全地提供什么能力Client 端负责怎么让模型选对工具。从工程视角看MCP 就是 AI 世界的 OpenAPI 加 gRPCOpenAPI 负责描述能力gRPC 负责传输。Java 生态里落地 MCP Server 有三条路。Spring AI Alibaba 走注解驱动Tool加ToolParameter就能把方法暴露出去上手最快和 Spring 生态无缝。官方 Java SDKio.modelcontextprotocol.sdk:mcp更轻量没有框架依赖适合想深入协议细节或做底层封装的场景。Quarkus / Micronaut 走云原生路线内存占用低适合云函数或高并发场景。结论很直接90% 的 Java 开发者直接选 Spring AI Alibaba因为你的项目大概率已经是 Spring Boot依赖、配置、监控、K8s 探针全是现成的。想研究协议细节再去看官方 SDK。已经在用 Quarkus 的团队自然集成即可。生产环境 99% 用 SSE 传输而不是 STDIO。STDIO 是进程间通信适合本地工具和 IDE 插件SSE 是 HTTP 长连接能部署到 Docker / K8s可鉴权、可审计、可观测。你要做的是团队级服务不是个人小工具所以从第一天就按 SSE 设计。还有一个认知必须先纠正Tool 不是普通接口它是写给 AI 看的能力说明书。有清晰名称、有自然语言描述、有结构化参数、有稳定返回。描述质量直接决定 AI 调用成功率。你写getData(String s)模型根本不知道什么时候该调你写Tool(description 根据订单号查询订单当前状态和物流信息)模型才知道用户问我的包裹到哪了时该用它。2. TaoToken 统一 Key 接入Base URL 与模型配置在写 MCP Server 之前先把模型通道打通。很多团队在这一步踩坑每个模型一个 Key、一套 Base URL代码里到处硬编码换模型要改配置重新发版。TaoToken 的价值就是统一入口——一个 Key、一个 Base URL背后切换模型不用动业务代码。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置时直接用这个。先拿 Key。打开控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面创建一个新 Key。建议按环境分 Key开发一个、测试一个、生产一个出问题能快速定位和吊销。创建后立刻复制保存页面刷新后不再显示完整 Key。拿到 Key 后在 Spring Boot 的application.yml里配置。这里给一份可直接复制的片段路径和字段名与 Spring AI 官方一致spring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: claude-sonnet-4-20250514 temperature: 0.7生产环境不要把 Key 写死在配置文件里用环境变量注入。K8s 里就是 Secret 挂载apiVersion: v1 kind: Secret metadata: name: taotoken-secret type: Opaque stringData: TAOTOKEN_API_KEY: sk-你的实际Key然后在 Deployment 里引用env: - name: TAOTOKEN_API_KEY valueFrom: secretKeyRef: name: taotoken-secret key: TAOTOKEN_API_KEY模型 ID 怎么填TaoToken 的模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 有完整列表直接复制对应 ID。Claude 系列适合工具调用和长上下文推理做 MCP Server 的模型侧首选。如果你要长期跑编码类 Agent 任务可以看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 按量或包月都有。配置完先别急着写 MCP用 curl 验证通道是否通curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 OK}] }返回里有choices[0].message.content就说明通道正常。这一步过了再往下走能省掉后面一半的排障时间。3. Spring AI Alibaba 可复制配置与 Tool 注册现在进入正题。先建工程pom 依赖如下dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-server-webflux-spring-boot-starter/artifactId version1.0.0-M6/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-webflux/artifactId /dependency注意是webflux版本因为 SSE 传输基于响应式栈。如果你用 Servlet 栈换成对应的 starter但 SSE 长连接在 WebFlux 下更稳。application.yml完整配置server: port: 8080 spring: application: name: example-mcp-server ai: mcp: server: name: example-mcp-server version: 1.0.0 type: SYNC sse-endpoint: /sse sse-message-endpoint: /mcp/message openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: claude-sonnet-4-20250514sse-endpoint是客户端建立连接的地址sse-message-endpoint是后续消息回传地址两个都要配对。写第一个 Tool。建一个 Service用Tool注解暴露方法Service public class OrderQueryService { Tool(description 根据订单号查询订单当前状态、金额和物流信息仅用于客服场景) public String getOrderStatus( ToolParameter(description 订单号格式为 ORD 开头加 12 位数字例如 ORD202501011234) String orderId) { if (orderId null || !orderId.startsWith(ORD)) { return 订单号格式不正确请提供 ORD 开头的订单号; } return switch (orderId) { case ORD202501011234 - 订单已发货物流单号 SF1234567890预计明天送达; case ORD202501019999 - 订单待支付金额 299 元请在 30 分钟内完成支付; default - 未查询到该订单请确认订单号是否正确; }; } }这里有几个细节决定 AI 调用成功率。描述里写清仅用于客服场景模型就不会在无关对话里乱调。参数描述给了格式示例模型能正确提取用户输入里的订单号。返回用自然语言而不是 JSON模型更容易理解并转述给用户。再写一个运维场景的 Tool查 K8s Pod 列表Service public class KubernetesQueryService { private final KubernetesClient client new KubernetesClientBuilder().build(); Tool(description 查询指定命名空间下的 Pod 列表仅用于运维诊断不执行任何变更操作) public ListString listPods( ToolParameter(description 命名空间名称例如 default 或 production) String namespace) { return client.pods() .inNamespace(namespace) .list() .getItems() .stream() .map(pod - pod.getMetadata().getName() : pod.getStatus().getPhase()) .toList(); } }注意这里只做查询不做删除、扩缩容。AI 的价值在分析和解释不在执行操作。把写操作留给人工确认是生产级 MCP Server 的铁律。注册 Tool 到 MCP Server用配置类Configuration public class McpToolConfig { Bean public ToolCallbackProvider orderTools(OrderQueryService orderQueryService) { return MethodToolCallbackProvider.builder() .toolObjects(orderQueryService) .build(); } Bean public ToolCallbackProvider k8sTools(KubernetesQueryService k8sQueryService) { return MethodToolCallbackProvider.builder() .toolObjects(k8sQueryService) .build(); } }启动应用控制台会打印 MCP Server 注册的 Tool 列表。看到getOrderStatus和listPods就说明注册成功。4. curl 验证工具调用链路与 K8s 部署探针服务起来后先验证 SSE 连接。MCP 客户端连接地址是http://localhost:8080/sse。用 curl 看握手curl -N http://localhost:8080/sse-N关闭缓冲你会看到持续输出的事件流包含event: endpoint和data: /mcp/message?sessionIdxxx。这个 sessionId 后面发消息要用。拿到 sessionId 后发一个初始化请求curl -X POST http://localhost:8080/mcp/message?sessionId你的sessionId \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2024-11-05, capabilities: {}, clientInfo: {name: curl-test, version: 1.0} } }返回里result.serverInfo.name是example-mcp-server就对了。再列一下工具curl -X POST http://localhost:8080/mcp/message?sessionId你的sessionId \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:2,method:tools/list,params:{}}result.tools数组里能看到你注册的两个工具及其 inputSchema。最后调一次工具curl -X POST http://localhost:8080/mcp/message?sessionId你的sessionId \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 3, method: tools/call, params: { name: getOrderStatus, arguments: {orderId: ORD202501011234} } }返回result.content[0].text是订单已发货物流单号 SF1234567890预计明天送达整条链路就通了。接下来部署到 K8s。Dockerfile 用多阶段构建FROM maven:3.9-eclipse-temurin-21 AS build WORKDIR /app COPY pom.xml . RUN mvn dependency:go-offline COPY src ./src RUN mvn package -DskipTests FROM eclipse-temurin:21-jre WORKDIR /app COPY --frombuild /app/target/*.jar app.jar EXPOSE 8080 ENTRYPOINT [java, -jar, app.jar]Deployment 配置重点是探针。MCP Server 是 SSE 长连接探针不能打/sse否则会一直挂着连接。单独加一个健康检查端点RestController public class HealthController { GetMapping(/healthz) public MapString, String health() { return Map.of(status, ok); } }Deployment 里配探针livenessProbe: httpGet: path: /healthz port: 8080 initialDelaySeconds: 30 periodSeconds: 10 readinessProbe: httpGet: path: /healthz port: 8080 initialDelaySeconds: 20 periodSeconds: 5initialDelaySeconds给足Spring 启动加 MCP 初始化需要时间。SSE 连接本身不需要探针客户端断线会自己重连。ServiceAccount 权限要最小化。查 Pod 只需要get、list、watchapiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: mcp-reader rules: - apiGroups: [] resources: [pods] verbs: [get, list, watch]绝对不要给cluster-admin。MCP Server 是 AI 的能力边界权限失控等于把集群交给模型。5. 常见报错排查401、local proxy failed、reading choices排障这块我按真实遇到的报错来写每个都给定位方法和修复。401 Unauthorized。最常见。先确认 Key 有没有带对echo $TAOTOKEN_API_KEY如果为空说明环境变量没注入。K8s 里检查 Secret 是否挂载成功kubectl exec -it pod-name -- env | grep TAOTOKEN有值但还 401检查 Base URL 是不是写成了带 UTM 的地址。API 调用必须用https://taotoken.net/api不带任何参数。另外确认 Key 没有多余空格复制时容易带上换行。local proxy failed。这个报错通常出现在客户端连 MCP Server 时。检查三件事Server 是否真的在监听 8080kubectl get svc看 Service 端口映射对不对客户端配置的地址是不是http://服务名:8080/sse。如果是本地开发确认没有其他进程占用 8080。还有一种情况是 SSE 连接被中间层缓冲了Nginx 反代要加proxy_buffering off; proxy_cache off; proxy_read_timeout 3600s;reading choices 相关报错。这个出现在模型调用返回解析阶段通常是返回体不是预期的 OpenAI 格式。检查 Base URL 有没有多写/v1。Spring AI 的base-url配到/api就行框架自己会拼/v1/chat/completions。如果你手动配成https://taotoken.net/api/v1就会变成/api/v1/v1/chat/completions返回 404 或格式错误。另外确认模型 ID 拼写正确写错的模型 ID 有些通道会返回非标准错误体。OAuth 相关报错。如果你用 Claude Code 或某些 IDE 插件接入可能会遇到 OAuth 流程问题。这类客户端有时会走自己的认证流程和 API Key 模式冲突。解决方式是明确用 API Key 模式在客户端配置里填 Base URL 和 Key不要触发 OAuth 登录。Claude Code 的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各客户端的配置示例。Tool 调用返回空或模型不调用。这不是报错但更常见。检查Tool的 description 是否足够具体。模型选工具靠语义匹配描述太泛它就不选。另外确认 Tool 注册的 Bean 被 Spring 扫描到了启动日志里搜Registered tools看数量对不对。SSE 连接频繁断开。K8s 里检查 Ingress 的proxy-read-timeout默认 60 秒会掐断长连接。调到 3600 秒。客户端侧要有重连逻辑MCP 协议本身支持断线重连。6. 从能跑到好用生产级 MCP Server 的落地建议跑通 demo 只是开始。真正上生产有几件事必须做。第一Tool 粒度要设计。一个 Tool 做一件事不要写executeCommand(String cmd)这种万能入口。粒度太粗模型选不准权限也没法控。查 Pod 是一个 Tool查日志是另一个分析异常是第三个。每个 Tool 的 description 写清楚什么时候用和什么时候不用。第二所有 Tool 调用记审计日志。谁在什么时间调了什么工具、参数是什么、返回什么全落库。AI 的行为需要可追溯出问题能回放。日志里不要记敏感数据订单号可以记用户手机号要脱敏。第三只读优先写操作要人工确认。MCP Server 暴露的能力里查询类可以放开变更类必须走二次确认。可以让 Tool 返回建议执行 XXX 操作由人工在运维平台确认后执行而不是让 AI 直接调 K8s API 删 Pod。第四命名空间和资源白名单。listPods不能接受任意 namespace要校验是否在白名单里。生产集群的kube-system不该被 AI 随便查。白名单配置化改的时候不用发版。第五监控 MCP Server 本身。Tool 调用次数、成功率、平均耗时、模型侧的错误率都要有指标。Prometheus 加 Grafana 是标配。SSE 连接数也要监控连接泄漏会拖垮服务。第六版本管理。MCP Server 的 Tool 描述变更会影响模型行为改 description 相当于改 prompt。每次变更记 changelog重大变更要回归测试。客户端侧缓存了 tool list 的话Server 更新后要通知客户端刷新。最后说一个容易忽略的点MCP Server 的部署位置。它应该和它要访问的业务系统在同一个网络域减少延迟和跨域问题。但它不应该和业务系统同进程独立部署才能独立扩缩容和独立发布。K8s 里就是一个独立的 Deployment通过 Service 暴露 SSE 端点业务系统通过内网访问。这套结构跑下来你的 Java 团队就有了一个可复用的 AI 能力网关。新业务要接 AI不用重新造轮子写个 Service 加Tool注解注册进去就行。模型换不换、客户端换不换Server 端不用动。这才是 MCP 对 Java 团队真正的价值。
