1. 存量 Java 微服务接入 MCP Server 的真实痛点MCP Server 封装存量 Java 微服务本质是在 Spring Boot 应用和 AI 工具之间加一层“能力适配层”让订单、库存、支付这些跑了多年的业务接口变成模型能理解、能安全调用的 Tool。它适合手里已经有一堆 Spring Boot 微服务、想让 Cursor、Claude Code 这类 AI 工具直接调用业务能力的后端团队。我试过把一个订单查询服务包成 MCP Tool最大的感受是难点从来不在“怎么写注解”而在“怎么让模型不把退款接口当查询接口乱调”。很多团队第一反应是直接把现有 OpenAPI 丢给 Agent或者干脆重写一套“AI 专用后端”。前者的问题在于传统 REST 接口是给前端和系统集成用的接口名、参数枚举、异常语义对模型完全不透明模型只能靠猜后者的问题更严重等于把线上验证过多年的业务规则又抄一遍最后两套口径、两套治理维护成本翻倍。更合理的做法是在微服务和 Agent 之间加一层 MCP Server 能力适配层对上暴露可发现、可描述、可组合的 Tool对下复用现有 Spring Boot 的 Service、事务、权限和审计中间补齐模型场景必须有的语义描述、调用约束、幂等和风险分级。这一层不是替代微服务而是把微服务升级成 Agent 能安全消费的能力面。下面按“工程模式分层 → TaoToken 统一通道配置 → 本地跑通验证 → 排障”的顺序给出一套可以直接复制的骨架。2. TaoToken 前置统一 Key 与 API 通道在写 MCP Server 之前先把模型调用通道固定下来。原因是 MCP Server 本身只负责“暴露能力”真正驱动 Tool 调用的模型请求需要一个稳定的入口。TaoToken 在这里扮演的是统一 Key 和 API 通道的角色你不需要在每台开发机、每个 Agent 里分别配置不同厂商的 Key而是通过一个兼容 OpenAI 协议的地址统一接入。官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址不带 UTMhttps://taotoken.net/api需要提前准备的东西只有两样一个可用的 API Key以及确认你的 MCP Server 或 AI 工具走的是 OpenAI 兼容协议。Key 在控制台的 API Keys 页面创建控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite注意Key 只创建一次并妥善保存不要写进会提交到 Git 的配置文件里。建议用环境变量注入后面 config.toml 和 settings.json 都会用到。如果你只是想先验证模型通道是否通可以直接用模型对话页面发一条消息模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite确认通道可用后再进入 MCP Server 的工程配置。这样排障时能快速区分是“模型通道问题”还是“MCP Tool 问题”。3. 可复制配置Spring Boot 工程模式与 config.toml / settings.json 骨架3.1 工程模式分层即使是同进程嵌入模式也不要把Service方法原样暴露成 Tool。推荐四层MCP Transport 层 ↓ Tool Facade 层 ← 面向模型的能力设计层 ↓ Application Service 层 ← 现有业务逻辑 ↓ Domain / Repository / External Client真正暴露给 LLM 的只有 Tool Facade。它负责参数规整、风险检查、权限校验和结果裁剪领域服务保持原样不动。3.2 Spring Boot 依赖与 Tool 骨架在pom.xml里加入 MCP 相关依赖以 Spring AI 生态为例dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server/artifactId /dependencyTool Facade 层示例注意requestId显式进入入参用于幂等DTO 与领域命令分离Component Validated public class OrderMcpTools { private final OrderApplicationService orderApplicationService; private final ToolAccessGuard toolAccessGuard; public OrderMcpTools(OrderApplicationService orderApplicationService, ToolAccessGuard toolAccessGuard) { this.orderApplicationService orderApplicationService; this.toolAccessGuard toolAccessGuard; } Tool(name query_order_detail, description 查询订单详情。适用于确认订单状态、金额、商品列表和退款状态。) public Object queryOrderDetail(String orderId) { toolAccessGuard.checkReadPermission(query_order_detail); return orderApplicationService.getOrder(orderId); } Tool(name refund_order, description 发起订单退款。前置条件订单已支付且满足退款规则。高风险操作需人工确认。) public Object refundOrder(Valid RefundOrderToolRequest request) { toolAccessGuard.checkWritePermission(refund_order); return orderApplicationService.refundOrder( new RefundOrderCommand(request.requestId(), request.orderId(), request.amount(), request.reason())); } }3.3 config.toml 骨架MCP Server 的config.toml负责声明服务名、传输方式和模型通道。把 TaoToken 的 API 地址和 Key 通过环境变量注入[mcp] name order-capability-server version 0.1.0 transport stdio [model] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model claude-sonnet [tools] expose [query_order_detail, refund_order] risk_level { query_order_detail READ_ONLY, refund_order WRITE_HIGH_RISK }3.4 settings.json 骨架如果 AI 工具侧如 Claude Code 类客户端需要settings.json注册 MCP Server骨架如下{ mcpServers: { order-capability: { command: java, args: [-jar, target/order-mcp-server.jar], env: { TAOTOKEN_API_KEY: your-key-here, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }提示command和args按你实际打包方式调整。本地开发也可以直接用mvn spring-boot:run配合 wrapper 脚本。4. 验证请求与成功结果配置写完后先本地启动 Spring Boot 应用export TAOTOKEN_API_KEYyour-key-here mvn spring-boot:run启动日志里应该能看到 MCP Server 注册的 Tool 列表类似Registered MCP tools: [query_order_detail, refund_order] MCP server started on stdio transport然后用一个最小请求验证 Tool 是否可被调用。如果走 HTTP 调试可以用 curl 模拟一次 Tool 调用curl -X POST http://localhost:8080/mcp/invoke \ -H Content-Type: application/json \ -d { tool: query_order_detail, arguments: { orderId: ORD-202605300001 } }成功返回应该是一个结构化 JSON包含订单状态、金额和商品列表{ orderId: ORD-202605300001, status: PAID, amount: 199.00, items: [{ skuId: SKU-1001, quantity: 1 }], refundable: true }如果这一步通了说明“Spring Boot → MCP Tool → 模型通道”的最小链路已经跑通。接下来可以在 AI 工具里让它调用query_order_detail观察模型是否能正确选择工具并构造参数。5. 本篇常见错排查5.1 Tool 注册成功但模型不调用最常见原因是description写得太模糊。模型选工具靠的是描述语义不是方法名。把“查询订单”改成“查询订单详情返回订单状态、金额、商品列表和退款状态”命中率会明显提升。5.2 启动报 API Key 为空检查环境变量是否在启动前导出。config.toml里的${TAOTOKEN_API_KEY}是占位符不会自动读取.env文件需要你在 shell 里export或通过 IDE 的运行配置注入。5.3 写操作被重复执行如果refund_order这类有副作用的 Tool 没有幂等键模型重试时会重复退款。务必把requestId作为必填入参并在 Tool 层做幂等校验。5.4 模型通道 401 / 403先确认 Key 是否有效再确认base_url是否写成了https://taotoken.net/api不要漏掉/api。如果还是不通去模型对话页面单独发一条消息排除是 MCP 配置问题还是通道问题。5.5 返回值里出现内部字段不要把 JPA Entity 或数据库行对象直接返回。Tool 层必须做输出裁剪去掉内部 ID、敏感字段把状态码转成业务可读语义。6. 下一步把通道和编码链路固定下来最小链路跑通后建议尽快做两件事一是把读操作和写操作分级治理读 Tool 和写 Tool 分线程池、分限流二是把 Tool Registry 做成可配置的控制面而不是散落在代码注解里。如果你准备长期用 AI 工具做编码和 Agent 开发可以把模型通道固定到 Coding Plan避免每次换工具都重新配 KeyCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入细节和协议说明统一看文档避免配置漂移接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你用的是 Claude Code 这类客户端Anthropic 兼容配置参考ClaudeCodeAnthropichttps://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite把通道固定下来之后MCP Server 的工程模式才有稳定的运行底座后面扩 Tool、加治理、上平台都不会因为底层通道反复变动而返工。