1. 从一次工具“消失”说起MCP Server 动态工具注册到底难在哪如果你正在用 Spring AI 做 MCP Server大概率遇到过这种场景本地写了一个BookServiceFacadeTool注解也加了启动日志里却看不到工具被注册或者工具注册上了但客户端调用时报“tool not found”。更麻烦的是当项目里 Facade 类越来越多每加一个工具就要改一次配置类维护成本直线上升。MCP Server 动态工具注册要解决的核心问题就是让工具类“自己被发现、自己注册”而不是靠人工在Bean里一个个列出来。Spring AI 提供了MethodToolCallbackProvider配合ApplicationContext扫描带Component的 Bean就能实现约定优于配置的注册方式。但真正落地时还有两个隐藏门槛一是多模型 Key 分散在各处调试时切来切去二是 MCP Server 本身要调用大模型做意图理解或结果润色Key 管理混乱会让排障变得非常痛苦。这篇内容面向需要统一管理多模型 Key 的大模型开发者交付可复制的settings.json与config.toml骨架演示通过 TaoToken 统一 Key/API 通道完成 MCP Server 工具注册并给出验证工具动态加载成功的具体动作。TaoToken 在这里的角色是统一 Key 通道你只需要在配置里写一个 API Key 和一个 Base URL就能让 MCP Server 在需要调用模型时走同一条通道不用为每个模型单独维护密钥。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 配置时注意区分。2. TaoToken 前置统一 Key 通道与 MCP Server 的关系2.1 为什么 MCP Server 需要统一 Key 通道MCP Server 本身是一个工具提供方它把业务能力比如图书检索、订单查询暴露成标准工具给 AI 客户端调用。但在实际开发中MCP Server 内部往往也需要调用大模型比如对用户自然语言参数做归一化、对检索结果做摘要、或者做多轮工具编排。如果每个模型都配一套 Key代码里就会出现大量if model a的分支配置也会散落在application.yml、环境变量、甚至硬编码里。TaoToken 的统一 Key 通道解决的就是这个问题一个 API Key一个 Base URLMCP Server 内部所有模型调用都走这个入口。这样你在调试动态工具注册时只需要关心工具本身有没有被扫描到而不用同时排查“是不是 Key 配错了”“是不是模型名写错了”。2.2 获取 Key 与确认通道地址进入控制台创建 API Key建议按项目维度创建方便后续轮换。创建完成后你会拿到一串以sk-开头的 Key。通道地址固定为https://taotoken.net/api注意这个地址不带任何查询参数直接作为 OpenAI 兼容的 Base URL 使用。如果你用的是 Claude Code 或 Anthropic 风格的客户端接入文档里有对应的配置说明地址在 https://taotoken.net/doc 。模型对话调试可以直接在 https://taotoken.net/model 里验证 Key 是否可用这一步建议在配置 MCP Server 之前先做避免把 Key 问题和工具注册问题混在一起排查。2.3 环境变量与配置文件的分工我的习惯是把 Key 放在环境变量里把模型名和 Base URL 放在配置文件里。这样本地开发和 CI 环境可以用不同的 Key但配置文件保持一致。环境变量名建议用TAOTOKEN_API_KEY避免和系统里已有的OPENAI_API_KEY冲突。下面两节分别给出settings.json和config.toml的骨架你可以按自己用的客户端选一个。3. 可复制配置settings.json 与 config.toml 骨架3.1 settings.json适合 Claude Code / MCP 客户端如果你用的客户端支持settings.json风格的 MCP 配置下面这个骨架可以直接复制。注意env里的TAOTOKEN_API_KEY要替换成你自己的 Keycommand和args按你的 MCP Server 启动方式调整。{ mcpServers: { book-management-server: { command: java, args: [ -jar, /path/to/your/mcp-server.jar ], env: { TAOTOKEN_API_KEY: sk-your-key-here, TAOTOKEN_BASE_URL: https://taotoken.net/api, SPRING_AI_MCP_SERVER_ENABLED: true, SPRING_AI_MCP_SERVER_NAME: book-management-server, SPRING_AI_MCP_SERVER_VERSION: 1.0.0 } } } }这个配置的关键点在于MCP Server 进程启动时会读取TAOTOKEN_API_KEY和TAOTOKEN_BASE_URLSpring AI 的模型客户端用这两个值初始化。工具注册逻辑本身不依赖 Key但工具执行过程中如果调用了模型就会走这条统一通道。3.2 config.toml适合需要更细粒度控制的场景有些客户端或本地开发环境更适合config.toml比如你需要同时配置多个 MCP Server或者需要给不同 Server 设置不同的超时。下面这个骨架把模型通道和 MCP Server 配置分开结构更清晰。[model_providers.taotoken] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model gpt-4o-mini [mcp_servers.book_management] command java args [-jar, /path/to/your/mcp-server.jar] enabled true [mcp_servers.book_management.env] SPRING_AI_MCP_SERVER_ENABLED true SPRING_AI_MCP_SERVER_NAME book-management-server SPRING_AI_MCP_SERVER_VERSION 1.0.0 SPRING_AI_MCP_SERVER_TYPE SYNC SPRING_AI_MCP_SERVER_SSE_MESSAGE_ENDPOINT /mcp/messageapi_key_env指向环境变量名而不是直接写 Key这样配置文件可以安全地提交到仓库。default_model按你实际用的模型填TaoToken 通道兼容主流模型名具体支持列表可以在模型对话页面确认。3.3 Spring AI 侧的动态注册配置MCP Server 的 Java 侧配置类保持约定优于配置的写法扫描以Facade结尾的 Bean。下面这段代码可以直接放进你的McpServerConfig。Configuration public class McpServerConfig { Bean public ToolCallbackProvider autoRegisterTools(ApplicationContext applicationContext) { String[] beanNames applicationContext.getBeanNamesForAnnotation(Component.class); ListObject facadeBeans new ArrayList(); for (String beanName : beanNames) { if (beanName.endsWith(Facade)) { facadeBeans.add(applicationContext.getBean(beanName)); } } return MethodToolCallbackProvider.builder() .toolObjects(facadeBeans.toArray()) .build(); } }对应的application.yml里加上 MCP Server 的基础配置端口和端点按需调整。server: port: 8085 spring: ai: mcp: server: enabled: true name: book-management-server version: 1.0.0 type: SYNC sse-message-endpoint: /mcp/messageMaven 依赖只需要spring-ai-starter-mcp-server-webmvc版本跟随你的 Spring AI BOM。dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server-webmvc/artifactId /dependency4. 验证请求确认工具动态加载成功4.1 启动日志里找注册痕迹MCP Server 启动后第一件事是看日志里有没有工具注册的输出。Spring AI 在注册ToolCallbackProvider时会打印工具数量和方法名。如果你看到类似Registered tools: [findBooksByTitle, findBooksByAuthor, ...]的日志说明动态扫描生效了。如果日志里工具数量为 0先检查 Facade 类是否被 Spring 扫描到也就是包路径是否在SpringBootApplication所在包的子包下。4.2 用 curl 直接请求 SSE 端点MCP Server 的 SSE 端点可以用来验证工具列表。启动服务后执行下面的命令观察返回的 JSON 里是否包含你定义的Tool名称。curl -N http://localhost:8085/mcp/message \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 1, method: tools/list, params: {} }如果返回结果里tools数组包含findBooksByTitle、findBooksByAuthor等名称说明动态工具注册成功。如果返回空数组回到第 5 节排查。4.3 通过模型对话验证工具调用链路工具列表正确只是第一步真正的验证是让模型调用工具。你可以在模型对话页面里发一条自然语言请求比如“帮我找一下书名包含‘Spring’的书”观察 MCP Server 日志里是否出现 调用工具: findBooksByTitle, 参数: Spring。这一步同时验证了统一 Key 通道是否可用如果模型调用失败但工具列表正常问题大概率在 Key 或 Base URL 上。4.4 验证动态扩展新增一个 Facade 类动态注册最大的价值是扩展性。你可以新建一个OrderServiceFacade加上Component和Tool注解重启服务后不修改任何配置类直接请求tools/list看新工具是否自动出现。如果出现了说明约定优于配置的注册链路完全打通。5. 本篇常见错排查5.1 工具数量为 0Bean 命名不符合约定最常见的原因是 Facade 类的 Bean 名称不以Facade结尾。Spring 默认用类名首字母小写作为 Bean 名称比如BookServiceFacade的 Bean 名称是bookServiceFacade以Facade结尾能被扫描到。但如果你用了Component(bookTool)显式指定名称就会漏掉。解决办法是保持默认命名或者把扫描条件改成按注解筛选。5.2 工具注册了但调用报错参数描述缺失ToolParam的description不是必填但缺失时模型可能无法正确构造参数。建议每个参数都加上描述尤其是枚举类型和日期类型。如果调用时报参数解析失败先检查ToolParam的description是否清晰再检查参数类型是否被 Jackson 正确反序列化。5.3 模型调用超时Base URL 或 Key 配置错误如果工具列表正常但模型调用一直超时优先检查TAOTOKEN_BASE_URL是否写成了https://taotoken.net/api注意末尾没有斜杠。Key 是否有多余空格环境变量是否被正确传递到 MCP Server 进程。可以在模型对话页面用同一个 Key 发一条测试消息确认 Key 本身可用。5.4 SSE 端点返回 404端点路径不匹配spring.ai.mcp.server.sse-message-endpoint配置的路径要和客户端请求的路径一致。默认是/mcp/message如果你改成了/mcp/sse客户端也要同步改。另外注意server.port是否被其他配置覆盖启动日志里会打印实际监听端口。5.5 动态注册导致启动变慢扫描范围过大getBeanNamesForAnnotation(Component.class)会扫描所有 Bean如果项目里 Bean 数量很多启动时会有一点开销。优化方式是把扫描范围限定在特定包或者用自定义注解替代Component只扫描带该注解的类。不过对于大多数项目这点开销可以忽略。6. 把统一 Key 通道用起来从调试到长期编码动态工具注册跑通之后下一步是把它用到日常开发里。如果你只是偶尔调试 MCP Server用模型对话页面验证工具调用就够了。但如果你要长期做编码和 Agent 开发建议把 TaoToken 的 Coding Plan 用起来地址在 https://taotoken.net/coding-plan 它适合需要频繁调用模型、又不想每次手动切 Key 的场景。接入文档在 https://taotoken.net/doc API Keys 管理在 https://taotoken.net/api-keys 。Claude Code 和 Anthropic 风格的配置可以参考 https://taotoken.net/claude-code 。我自己的习惯是本地开发用环境变量注入 KeyCI 环境用单独的 KeyMCP Server 的配置文件里只写 Base URL 和模型名。这样换 Key 的时候只需要改环境变量不用动代码和配置。最后留一个实用技巧在autoRegisterTools里加一行日志打印扫描到的 Facade Bean 名称和工具方法数量。这样每次启动时一眼就能看出哪些工具被注册了比翻文档快得多。工具注册这件事约定优于配置的核心不是省代码而是让新增工具的成本降到“只写业务类”这一步。