1. 从一次真实踩坑说起Java 服务怎么就成了 Claude 的工具很多 Java 开发者第一次接触 MCPModel Context Protocol时脑子里冒出的问题都差不多我写好的 Spring Boot 接口怎么才能让 Claude 或者 Manus 这类 AI 应用直接调用难道要把业务逻辑重写一遍答案是不用。MCP 就是给 AI 和你的 Java 服务之间架的一座标准桥桥的两头分别是 MCP ClientAI 应用侧和 MCP Server你的 Java 服务侧。我试过最直接的做法把一个查询天气的 Spring 服务包装成 MCP Server然后让 Claude Desktop 通过配置文件把它当成一个可调用的工具。整个过程不需要改业务代码只需要加依赖、加注解、加一段 JSON 配置。跑通之后你在 Claude 里输入“北京今天天气怎么样”它会自动判断该调用你写的getWeatherForecastByLocation方法把经纬度参数传进去拿到结果再组织成自然语言回复。这套链路适合谁适合已经有 Spring Boot 项目、想把现有能力开放给 AI 应用的 Java 开发者也适合想用 Spring AI Alibaba 做 Agent 编排、需要动态挂载工具的后端同学。核心检索词就三个Spring AI Alibaba、MCP Server、Claude 集成。下面我从服务发布讲到客户端调用再到 OpenManus 里的实际使用每一步都给可复制的配置和命令。2. TaoToken 前置准备模型接入与 Key 获取在跑通 MCP 之前你得先有一个能用的模型服务。Spring AI Alibaba 默认走 DashScope但如果你想让 Claude 或 Manus 侧调用或者想用统一的 API 入口管理多个模型可以先把 TaoToken 的接入配置准备好。它的 API 地址是https://taotoken.net/api控制台在https://taotoken.net/consoleAPI Keys 管理页在https://taotoken.net/api-keys。你需要做的第一件事是拿到一个可用的 Key。登录控制台后在 API Keys 页面创建一个新 Key复制出来备用。这个 Key 后面会用在 Spring AI 的application.yml里也会用在 Claude Desktop 的 MCP 配置中作为环境变量。注意不要把它硬编码到代码里提交到仓库用环境变量或者本地配置文件管理。第二步是确认模型 ID。TaoToken 支持多种模型你在模型对话页面可以看到当前可用的模型列表。对于 MCP 场景建议选一个支持工具调用Function Calling的模型因为 MCP 的本质就是让模型决定“什么时候调用哪个工具”。如果模型不支持工具调用MCP 的 Tool 注册了也不会被触发。第三步是理解 Base URL 的写法。Spring AI Alibaba 的 OpenAI 兼容模式需要你配置base-url和api-key。Base URL 填https://taotoken.net/api不要加多余的路径。Key 填你刚才创建的那串。Model ID 填你在模型对话页看到的名称比如claude-3-5-sonnet或gpt-4o这类。这三件套配好之后你的 Spring 应用就具备了调用大模型的能力接下来才是把 MCP Server 挂上去。如果你还没决定用哪个模型可以先在模型对话页面发一条测试消息确认 Key 和网络都通。这一步花两分钟能省掉后面很多排查时间。对于长期做编码和 Agent 开发的场景Coding Plan 提供了更稳定的配额和更低的延迟适合把 MCP 集成到日常开发流里。3. 可复制配置Spring AI Alibaba 发布 MCP Server 的完整片段这一节是全文的核心。我会给出 stdio 和 SSE 两种模式的完整配置包括依赖坐标、application.yml、工具类代码和启动命令。你直接复制到项目里就能跑。3.1 stdio 模式适合本地轻量工具stdio 模式的 MCP Server 以独立进程运行通过标准输入输出和客户端通信。它适合工具逻辑不重、不需要独立部署的场景。先加依赖dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-server-spring-boot-starter/artifactId /dependency然后在application.yml里配置spring: main: web-application-type: none banner-mode: off ai: mcp: server: stdio: true name: my-weather-server version: 0.0.1注意web-application-type: none是必须的因为 stdio 模式不需要 Web 容器。接下来写工具类用Tool和ToolParameter注解标记方法Service public class OpenMeteoService { private final WebClient webClient; public OpenMeteoService(WebClient.Builder builder) { this.webClient builder.baseUrl(https://api.open-meteo.com/v1).build(); } Tool(description 根据经纬度获取天气预报) public String getWeatherForecastByLocation( ToolParameter(description 纬度例如39.9042) String latitude, ToolParameter(description 经度例如116.4074) String longitude) { String response webClient.get() .uri(uriBuilder - uriBuilder .path(/forecast) .queryParam(latitude, latitude) .queryParam(longitude, longitude) .queryParam(current, temperature_2m,wind_speed_10m) .queryParam(timezone, auto) .build()) .retrieve() .bodyToMono(String.class) .block(); return 当前位置纬度 latitude 经度 longitude 的天气信息\n response; } }然后在启动类里注册ToolCallbackProviderSpringBootApplication public class McpServerApplication { public static void main(String[] args) { SpringApplication.run(McpServerApplication.class, args); } Bean public ToolCallbackProvider weatherTools(OpenMeteoService service) { return MethodToolCallbackProvider.builder().toolObjects(service).build(); } }打包命令mvn clean package -DskipTests打包后你会得到一个 jar 文件记住它的全路径后面 Claude Desktop 配置里要用。3.2 SSE 模式适合远程部署和多客户端复用SSE 模式通过 HTTP 协议通信适合把 MCP Server 部署到服务器上让多个客户端远程调用。依赖换成dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-server-webflux-spring-boot-starter/artifactId /dependencyapplication.yml配置server: port: 8080 spring: ai: mcp: server: name: my-weather-server version: 0.0.1工具类代码和 stdio 模式完全一样启动类里额外加一个WebClient.Builder的 BeanBean public WebClient.Builder webClientBuilder() { return WebClient.builder(); }启动命令mvn spring-boot:run服务会在http://localhost:8080启动。SSE 模式的好处是你可以把同一个 MCP Server 同时挂给 Claude、Manus 和自研的 Spring 客户端不用每个客户端都本地起一个进程。3.3 客户端侧配置让 Spring 应用调用 MCP Server如果你想让自己的 Spring 应用作为 MCP Client 去调用上面发布的 Server加这个依赖dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-client-spring-boot-starter/artifactId /dependency然后在application.yml里配置模型和 MCP 连接spring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: claude-3-5-sonnet mcp: client: stdio: servers-configuration: classpath:/mcp-servers-config.jsonmcp-servers-config.json放在resources目录下{ mcpServers: { weather: { command: java, args: [ -Dspring.ai.mcp.server.stdiotrue, -Dspring.main.web-application-typenone, -jar, /absolute/path/to/your/mcp-server.jar ], env: {} } } }注意 jar 路径必须是全路径相对路径在客户端启动子进程时会找不到。启动类里注入ToolCallbackProvider并挂到ChatClient上Bean public CommandLineRunner predefinedQuestions( ChatClient.Builder builder, ToolCallbackProvider tools, ConfigurableApplicationContext context) { return args - { var chatClient builder.defaultTools(tools).build(); String input 北京的天气如何; System.out.println( QUESTION: input); System.out.println( ASSISTANT: chatClient.prompt(input).call().content()); context.close(); }; }运行mvn spring-boot:run你会看到日志里 MCP Server 被调用返回了天气数据。4. 验证请求从 Claude Desktop 到 OpenManus 的端到端调用配置写完了怎么确认真的通了分三步验证。第一步在 Claude Desktop 里测试 stdio 模式。找到配置文件macOS~/Library/Application Support/Claude/claude_desktop_config.jsonWindows%APPDATA%\Claude\claude_desktop_config.json加入你的 Java MCP Server{ mcpServers: { weather: { command: java, args: [ -Dspring.ai.mcp.server.stdiotrue, -Dspring.main.web-application-typenone, -Dlogging.pattern.console, -jar, /absolute/path/to/mcp-server.jar ], env: {} } } }重启 Claude Desktop你会看到工具列表里多了getWeatherForecastByLocation。输入“查询今天北京的空气质量”Claude 会自动触发你写的工具返回结果。第二步在 Spring 客户端里测试 SSE 模式。启动 SSE 模式的 MCP Server 后客户端application.yml改成spring: ai: mcp: client: sse: connections: server1: url: http://localhost:8080然后运行客户端启动类。如果你遇到Multiple tools with the same name报错在启动类上加排除SpringBootApplication(exclude { org.springframework.ai.autoconfigure.mcp.client.SseHttpClientTransportAutoConfiguration.class })这个报错的原因是 Spring AI 的SseHttpClientTransportAutoConfiguration和SseWebFluxTransportAutoConfiguration两个自动配置类同时加载导致同一个 Tool 被注册两次。排除其中一个即可。第三步在 OpenManus 里测试 MCP 集成。OpenManus 是 Spring AI Alibaba 社区里的 Agent 实现它通过ToolCallbackProvider把 MCP 工具挂到ChatClient上。你只需要在LlmService构造方法里注入public LlmService(ChatModel chatModel, ToolCallbackProvider toolCallbackProvider) { this.chatClient ChatClient.builder(chatModel) .defaultTools(ToolBuilder.getManusAgentToolCalls()) .defaultTools(toolCallbackProvider) .build(); }然后在mcp-servers-config.json里配置百度地图 MCP{ mcpServers: { baidu-map: { command: npx, args: [-y, baidumap/mcp-server-baidu-map], env: { BAIDU_MAP_API_KEY: your_baidu_ak } } } }启动 OpenManus输入“使用百度地图规划从北京市到上海市的路线”你会看到它先调用地理编码获取经纬度再调用路线规划计算距离和耗时。实测下来北京到上海驾车约 1223 公里预计 12 小时 45 分钟。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth集成过程中最容易卡住的几个报错我按出现频率排一下。401 Unauthorized这个通常出现在模型调用侧不是 MCP 侧。检查你的api-key是否正确Base URL 是否写成了https://taotoken.net/api而不是带多余路径。如果你用的是环境变量确认变量名和application.yml里的占位符一致。另外Key 如果被撤销或过期也会返回 401去控制台重新生成一个。local proxy failed这个报错一般出现在客户端启动 MCP Server 子进程时。stdio 模式下客户端会用command和args去启动一个 Java 进程。如果 jar 路径不对、Java 不在 PATH 里、或者-Dspring.main.web-application-typenone没加都会导致子进程启动失败。排查方法是把command和args拼成一条命令在终端里手动执行一遍看能不能跑起来。reading choices 相关报错这个通常出现在模型返回结构不符合预期时。如果你用的模型不支持工具调用或者返回的 JSON 里没有choices字段Spring AI 在解析时会抛异常。解决办法是换一个支持 Function Calling 的模型或者在ChatClient调用时显式关闭工具执行。另外如果你在application.yml里同时配了多个模型提供商确认spring.ai.openai.chat.options.model指向的是正确的模型 ID。OAuth 相关报错如果你接入的 MCP Server 需要 OAuth 认证比如某些 GitHub 或企业内网服务客户端配置里需要额外加auth字段。Spring AI 目前对 OAuth 的支持还在演进中建议先用 Personal Access Token 的方式绕过。在mcp-servers-config.json的env里把 Token 传进去服务端从环境变量读取。Tool 重复注册前面提过的Multiple tools with the same name除了排除SseHttpClientTransportAutoConfiguration还有一种情况是你同时在application.yml里配了connections又在 JSON 文件里配了servers-configuration两者二选一即可。Claude Desktop 不加载工具重启 Claude 后如果工具列表没变化先检查 JSON 格式是否合法不能有注释、不能有尾逗号。然后看 Claude 的日志macOS 在~/Library/Logs/Claude/下。常见原因是 jar 路径里有空格没转义或者 Java 版本太低。6. 语义一致 CTA把 MCP 集成落到日常开发流跑通一次端到端调用只是开始。真正让 MCP 产生价值的是把它挂到你的日常开发流里让 Claude Code 通过 MCP 调用你的内部工具让 OpenManus 通过 MCP 操作数据库和地图服务让自研的 Spring Agent 通过 MCP 动态加载业务能力。如果你在排障和接入阶段卡住了先去 API Keys 页面确认 Key 状态再看接入文档里的 Base URL 和 Model ID 写法。文档里有完整的application.yml示例和mcp-servers-config.json模板对照着改比盲猜快得多。想先验证模型本身能不能正常对话和工具调用去模型对话页面发几条消息确认返回结构里有tool_calls字段。这一步过了再回来调 MCP 配置能排除掉一半的变量。如果你打算把 MCP 集成到长期的编码和 Agent 工作流里Coding Plan 提供了更稳定的调用配额和更低的延迟。MCP 的 Tool 调用对响应时间敏感模型侧慢一秒整个 Agent 链路就可能超时。选一个稳定的接入点比反复调超时参数省事。最后提醒一句MCP Server 的工具描述Tool里的description写得越清楚模型判断该不该调用、传什么参数就越准。别写“获取数据”这种模糊描述写“根据经纬度获取未来七天天气预报返回温度和风速”。模型不是人它只能靠描述来决策。