1. 为什么要在本地跑一个 MCP 天气服务如果你正在用 Spring AI 做 Agent 或者工具调用大概率会遇到一个很现实的问题模型本身不知道今天杭州下不下雨它需要一个能查实时天气的工具。MCPModel Context Protocol就是干这个的你可以把它理解成 AI 应用和外部数据源之间的 USB-C 接口插上就能用不用为每个模型单独写一套适配。这篇要落地的事情很具体用 Spring AI 搭一个 MCP 天气服务本地能跑通客户端能连上查一次真实天气能返回结构化结果。同时把模型调用的 Key 统一走 TaoToken 的 API 通道省得在多个模型供应商之间来回切换配置。适合谁适合已经写过 Spring Boot、想快速把 MCP Server 跑起来验证链路的 Java 开发者不需要你提前精通 MCP 协议细节。我试过把天气查询直接写死在业务代码里后面换模型、加工具的时候改得头皮发麻。MCP 的价值就在于工具和模型解耦天气服务独立成一个 Server客户端按需接入。下面从环境准备到 config.toml 骨架再到验证和排错一步步来。2. TaoToken 前置准备统一 Key 与 API 通道在写代码之前先把模型调用的通道准备好。TaoToken 在这里扮演的角色是统一入口你拿到一个 Key就能通过它的 API 通道访问不同模型不用为每个供应商单独维护一套鉴权和地址。对 MCP 天气服务来说模型负责理解用户意图、决定调用哪个工具工具本身查天气两者通过 MCP 协议通信。你需要做两件事。第一注册并登录 TaoToken 官网拿到 API Key地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 登录后在控制台里创建 Key。第二记住 API 的基础地址是 https://taotoken.net/api 后面配置里会用到注意这个地址不带任何查询参数。Key 的管理建议单独放一个环境变量别硬编码进代码。你可以先在控制台把 Key 复制出来后面 config.toml 里用占位符引用。如果你还没创建 Key直接进控制台页面操作https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建完顺手在 API Keys 页面确认一下 Key 的状态是启用。注意Key 只显示一次创建后立刻保存到安全的地方。后面所有模型调用都靠它丢了只能重新生成。3. 可复制的 config.toml 配置骨架MCP 客户端连接 Server 的时候通常需要一个配置文件来描述 Server 的启动方式和参数。不同客户端比如 Claude Desktop、Cherry Studio、Cline用的配置格式略有差异但核心字段是一致的。下面给一份通用的 config.toml 骨架你可以直接复制改。# MCP 客户端配置骨架 # 用于连接本地 Spring AI 天气 MCP Server [mcp_servers.weather] # 启动方式本地进程用 command远程 SSE 用 url command java args [ -jar, /path/to/mcp-weather-server.jar, --server.port8081 ] # 环境变量把 TaoToken 的 Key 注入进去 env { TAOTOKEN_API_KEY sk-你的Key, TAOTOKEN_BASE_URL https://taotoken.net/api } # 如果走 SSE 远程模式改用下面这段 # [mcp_servers.weather_sse] # url http://localhost:8081/sse # transport sse # 模型调用通道配置供 Spring AI 客户端使用 [ai.openai] base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} chat_model gpt-4o-mini这份骨架里几个关键点。command和args决定 Server 怎么启动本地 jar 包方式最直接。env把 TaoToken 的 Key 和 Base URL 传进去Server 内部调用模型时读这两个变量。如果你用的是 SSE 模式Server 启动后暴露/sse端点客户端用url字段连不用管进程启动。Spring AI 侧的application.yml也要对应配一下把模型通道指向 TaoTokenspring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-mini temperature: 0.3这样模型请求走 TaoToken 的统一通道天气工具通过 MCP 协议暴露两边职责清晰。配置改完记得重启客户端很多连接失败其实是配置没重新加载。4. 天气 MCP Server 的核心实现配置骨架有了接下来看 Server 端怎么写。核心就三块依赖、工具方法、数据模型。依赖用 Spring AI 的 MCP Server starterdependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-server-webflux-spring-boot-starter/artifactId /dependency主应用类里注册工具回调把 WeatherService 暴露成 MCP 工具SpringBootApplication public class McpWeatherApplication { public static void main(String[] args) { SpringApplication.run(McpWeatherApplication.class, args); } Bean public ToolCallbackProvider weatherTools(WeatherService weatherService) { return MethodToolCallbackProvider.builder() .toolObjects(weatherService) .build(); } }WeatherService 里用Tool注解描述工具能力模型靠这段描述决定什么时候调用Service public class WeatherService { private final RestClient restClient; public WeatherService() { this.restClient RestClient.builder() .baseUrl(https://wttr.in) .defaultHeader(Accept, application/json) .build(); } Tool(description 查询中国城市的当前天气输入城市名例如 杭州、上海) public String getWeather(String cityName) { WeatherResponse resp restClient.get() .uri(/{city}?formatj1, cityName) .retrieve() .body(WeatherResponse.class); if (resp null || resp.getCurrent_condition() null || resp.getCurrent_condition().isEmpty()) { return 无法获取天气请检查城市名或稍后重试; } CurrentCondition c resp.getCurrent_condition().get(0); return String.format(城市:%s 天气:%s 温度:%s°C 湿度:%s%% 风速:%s km/h, cityName, c.getWeatherDesc().get(0).getValue(), c.getTemp_C(), c.getHumidity(), c.getWindspeedKmph()); } }数据模型用简单的 POJO 接住 JSON 就行字段名和 wttr.in 返回的对齐。CurrentCondition里放temp_C、humidity、windspeedKmph、weatherDesc这些WeatherResponse里放current_condition列表。注意temp_C这种带下划线的字段Jackson 默认能映射如果不行加JsonProperty(temp_C)。打包成 jar 之后用java -jar启动默认端口 8081。启动日志里看到 MCP Server 注册成功的提示说明工具已经暴露出来了。5. 验证一次天气查询请求Server 跑起来之后别急着接客户端先用最直接的方式验证工具本身能不能返回数据。启动 jarjava -jar mcp-weather-server.jar --server.port8081看到类似MCP server started on port 8081的日志后用 curl 测一下 SSE 端点是否存活curl -N http://localhost:8081/sse如果返回一串event: endpoint开头的事件流说明 SSE 通道正常。接着在客户端里配置好 config.toml重启客户端在工具列表里应该能看到weather这个 Server 和getWeather工具。然后在对话里发一句「杭州现在天气怎么样」。模型会通过 TaoToken 通道理解意图决定调用getWeather工具参数是「杭州」。工具返回结构化天气文本模型再组织成自然语言回复。整个过程你能在客户端日志里看到工具调用的记录。实测下来从发消息到返回结果大概两三秒取决于模型响应速度。如果工具被调用了但返回空先检查 wttr.in 是否可达再检查城市名有没有传对。验证通过后这个天气服务就可以挂到你的 Agent 工作流里了。6. 常见报错排查清单跑 MCP 天气服务最容易卡在几个地方按下面顺序排查能省不少时间。连接被拒绝客户端报Connection refused先确认 Server 进程还在跑端口没被占用。lsof -i:8081看一下。如果 Server 启动就崩了多半是依赖没下全或者 JDK 版本不对Spring AI 1.0 需要 JDK 17 以上。工具列表为空客户端连上了但看不到getWeather。检查Tool注解的类有没有被ToolCallbackProvider注册主应用类里的Bean方法名和参数别写错。另外确认 starter 用的是 webflux 版本用错 starter 会导致 MCP 端点不暴露。模型调用 401TaoToken 的 Key 没生效。检查TAOTOKEN_API_KEY环境变量有没有正确注入config.toml 里的env字段拼写对不对。Key 前后别带空格复制的时候容易多带一个换行。天气返回空wttr.in 偶尔抽风换个城市名再试。如果一直空把formatj1换成formatjson看看原始返回确认字段名和你的 POJO 对得上。SSE 连不上客户端配的是url模式但 Server 没开 SSE 端点。确认 starter 是 webflux 版本并且没有把spring.ai.mcp.server.stdio之类的配置开成 stdio 模式。stdio 和 SSE 是两种传输方式别混用。排错的时候优先看 Server 端日志工具调用失败、参数解析错误都会打出来。客户端日志看模型请求和工具调用链两边对照基本能定位。7. 把通道和工具接进你的工作流天气服务只是 MCP 的一个最小验证。真正有价值的是这套结构可以复制每加一个工具就多一个Tool方法客户端配置里多一个 Server 条目模型通道始终走 TaoToken 的统一 Key。你不需要为每个工具单独配一套模型鉴权。如果你打算长期跑编码类 Agent 或者多工具工作流建议把模型调用统一收敛到 TaoToken 的 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 这样 Key 管理和额度都在一个地方看。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有针对 Spring AI 的配置示例遇到 base-url 或者模型名对不上的情况可以直接对照。想先验证模型对话通不通用模型对话页面发一条消息就行https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Key 管理在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你用 Claude Code 做开发Anthropic 兼容通道的配置在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 把 base_url 换成 TaoToken 的地址就能接。最后留一个实用技巧config.toml 里的路径和 Key 尽量用环境变量别写死。团队协作的时候每个人本地环境不同写死路径会导致别人拉下来跑不起来。把TAOTOKEN_API_KEY和 jar 路径都抽成变量换机器只改变量值配置骨架不用动。