手把手教你用 Spring Boot 搭建一个 MCP Server：TaoToken 统一 Key 接入与配置骨架

1. 为什么后端团队需要一个自己的 MCP ServerMCP Server 说白了就是一层“工具网关”它把你们内部已有的能力查订单、读配置、跑脚本、拉监控指标包装成 AI 客户端能看懂的结构化接口让 Claude、Cursor、各类 Agent 框架在对话里直接调用而不是靠人肉复制粘贴。Spring Boot 做这件事有天然优势——你团队现有的 Service、Mapper、鉴权体系几乎可以原样复用不用为了接 AI 再学一套新语言。这篇面向的是已经写过 Spring Boot、想把本地工具能力暴露给 AI 客户端的后端开发者。我会从零给出一套能跑通的工程骨架pom.xml依赖、application.yml配置、工具注册中心、/mcp/tools与/mcp/call-tool两个核心端点最后用 TaoToken 的统一 Key 通道把模型侧接入补齐并用curl验证整条链路。目标很明确服务能启动、工具能列出、调用能返回结果、AI 客户端能连上。技术栈固定为 Spring Boot 3 Java 17 Maven Spring Web Jackson不引入额外重型框架保证你复制过去就能编译。2. TaoToken 前置准备统一 Key 与通道配置在写代码之前先把模型侧的入口准备好否则后面验证工具调用时没有可用的对话通道。TaoToken 在这里扮演的是统一 Key 与 API 通道的角色你只需要申请一个 Key就能在模型对话、编码 Agent、接口调试之间共用同一套凭证不用为每个客户端单独配一遍。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号进入控制台。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在里面找到 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 新建一个 Key 并复制保存。这个 Key 后面会同时用在 MCP 客户端的settings.json和curl验证里。第二步确认你的 API 基地址。TaoToken 的 API 入口是 https://taotoken.net/api 注意这个地址不带任何查询参数配置时直接填这一行即可。如果你用的是 Claude Code 这类编码 Agent可以参考 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里的接入说明如果只是想在网页里先验证模型是否通直接进模型对话页 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 发一条消息即可。注意Key 只显示一次建议存进密码管理器。不要把它硬编码进 Git 仓库后面我会用环境变量注入。到这里前置就绪一个 Key、一个 API 基地址、一个可用的对话入口。接下来进入 Spring Boot 工程本身。3. 可复制配置pom.xml 与 application.yml 骨架先建一个标准 Maven 工程groupId用com.exampleartifactId用mcp-server。pom.xml里只需要 Web、Lombok、Jackson 三块父级用 Spring Boot 3.2.xparent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version relativePath/ /parent properties java.version17/java.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId scopeprovided/scope /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId /dependency /dependenciesapplication.yml保持极简端口和日志级别够用就行同时把 TaoToken 的 Key 通过环境变量占位避免明文server: port: 8080 mcp: server: name: my-company-tools version: 1.0.0 taotoken: api-base: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY:} logging: level: com.example.mcpserver: DEBUG启动时用export TAOTOKEN_API_KEY你的Key注入Windows 下用set。这样配置骨架就完成了接下来写工具模型和注册中心。4. 工具注册与 MCP Controller 实现MCP 的核心抽象就两个动作列出工具、调用工具。先定义工具接口任何实现类只要被 Spring 扫描到就会自动进注册中心public interface McpTool { String getName(); String getDescription(); MapString, Object getInputSchema(); Object invoke(MapString, Object input); }写一个示例工具返回当前时间方便验证链路Component public class TimeTool implements McpTool { Override public String getName() { return get_current_time; } Override public String getDescription() { return Returns the current time in ISO8601 format.; } Override public MapString, Object getInputSchema() { return Map.of(type, object, properties, Map.of()); } Override public Object invoke(MapString, Object input) { return Map.of( time, Instant.now().toString(), timezone, ZoneId.systemDefault().getId() ); } }注册中心用构造器注入收集所有McpToolBeanService public class ToolRegistry { private final MapString, McpTool tools new ConcurrentHashMap(); public ToolRegistry(ListMcpTool toolList) { for (McpTool tool : toolList) { tools.put(tool.getName(), tool); } System.out.println(registered tools: tools.size()); } public CollectionMcpTool getTools() { return tools.values(); } public McpTool getTool(String name) { return tools.get(name); } }Controller 暴露两个端点GET /mcp/tools返回工具清单POST /mcp/call-tool接收调用请求RestController RequestMapping(/mcp) RequiredArgsConstructor public class McpController { private final ToolRegistry toolRegistry; GetMapping(/tools) public ResponseEntityListMcpTool listTools() { return ResponseEntity.ok(toolRegistry.getTools().stream().toList()); } PostMapping(/call-tool) public ResponseEntityListToolResult callTools(RequestBody ToolCallRequest request) { ListToolResult results request.getToolCalls().stream().map(call - { String name (String) call.get(name); MapString, Object input (MapString, Object) call.getOrDefault(input, Map.of()); McpTool tool toolRegistry.getTool(name); if (tool null) { return new ToolResult(name, tool not found, true); } try { return new ToolResult(name, tool.invoke(input), false); } catch (Exception e) { return new ToolResult(name, e.getMessage(), true); } }).toList(); return ResponseEntity.ok(results); } }ToolCallRequest里放一个ListMapString, Object toolCallsToolResult放toolName、result、isError三个字段用 Lombok 的Data即可。到这里服务端骨架完整可以启动了。5. 验证请求curl 跑通工具调用链路先启动应用mvn spring-boot:run看到控制台打印registered tools: 1说明工具注册成功。第一个验证动作是列出工具curl http://localhost:8080/mcp/tools预期返回一个 JSON 数组里面包含get_current_time及其inputSchema。第二个动作是真正调用curl -X POST http://localhost:8080/mcp/call-tool \ -H Content-Type: application/json \ -d { toolCalls: [ { name: get_current_time, input: {} } ] }返回结果里isError为falseresult.time是 ISO8601 时间戳result.timezone是你机器的时区。如果这两步都通了说明 MCP Server 本身没问题。接下来把服务注册到 AI 客户端。以支持 MCP 的客户端为例settings.json片段如下{ mcpServers: { my-company-tools: { url: http://localhost:8080/mcp, apiKey: ${TAOTOKEN_API_KEY} } } }如果你用的是编码类 Agent长期跑建议走 Coding Plan 通道配置方式见 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。想先在网页里确认模型侧能正常对话直接进 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 发一条消息即可。Claude Code 的接入细节在 https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 有完整说明。6. 本篇常见错排查启动报 8080 端口占用改application.yml里的server.port或者先lsof -i:8080找到进程杀掉。别硬扛端口冲突是最常见的第一次失败原因。/mcp/tools返回空数组说明McpTool实现类没被扫描到。检查实现类是否加了Component以及是否在com.example.mcpserver包路径下。Spring 默认只扫描主启动类所在包及其子包。调用返回tool not found请求体里的name必须和getName()返回值完全一致大小写敏感。建议先用/mcp/tools拿到准确名称再拼请求。JSON 反序列化报错ToolCallRequest的字段名要和请求体对齐。如果你把字段写成tool_calls请求里也得用下划线Jackson 默认不做驼峰转换。客户端连不上本地服务localhost在容器或远程客户端里指向的是它自己。本地调试用127.0.0.1跨机访问用局域网 IP并确认防火墙放行。Key 没生效检查环境变量是否在启动进程的 shell 里导出echo $TAOTOKEN_API_KEY确认非空。如果为空application.yml里的占位会解析成空字符串后续请求会鉴权失败。中文返回乱码Spring Boot 3 默认 UTF-8一般不会出问题。如果客户端显示乱码检查Content-Type是否带了charsetUTF-8。排查顺序建议固定先确认服务启动日志、再确认工具列表、最后确认调用返回。三步定位比盲目改代码快得多。7. 接入文档与后续扩展服务跑通之后下一步通常是把真实业务工具接进来。做法和TimeTool一样实现McpTool接口在invoke里调用你现有的 ServicegetInputSchema里描述参数结构。Spring 会自动把它注册进ToolRegistry不需要改 Controller。接入过程中如果遇到鉴权、通道、Key 相关的问题优先查接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面覆盖了 API 基地址、Key 管理和常见错误码。需要新建或轮换 Key 时去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。长期跑编码 Agent 或自动化任务Coding Plan 通道 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 更合适配额和稳定性都更可控。一个实用建议给每个工具加独立的超时和异常兜底别让某个慢查询把整个/mcp/call-tool拖死。工具粒度尽量小一个工具只做一件事AI 客户端编排起来更灵活。