企业官网建设流程全解析

1. 为什么 MCP Server 跑起来了，客户端却连不上

很多人在 Spring Boot 里引入spring-ai-starter-mcp-server-webmvc之后，日志里能看到 Tomcat 起来了、SSE 端点也注册了，但用 MCP 客户端去连就是握手失败，或者工具列表拉不出来。问题往往不在 Spring AI 本身，而是两件事没对齐：一是settings.json里客户端要连的地址和传输方式跟服务端实际暴露的不一致，二是模型调用链路上的 API Key 没有统一出口，每个工具各自读环境变量，本地调试时经常漏配。

这篇就围绕 MCP Server Boot Starter 的接入配置展开，给你一份可以直接复制的settings.json骨架，把 TaoToken 的统一 Key 和 API 通道填进去，再走一遍启动后的连通性验证命令。适合正在本地快速跑通 MCP 服务、又想把 Key 管理收拢到一处的开发者。读完你能拿到三样东西：一份能跑的配置骨架、一条能验证服务端 SSE 是否正常的 curl 命令、以及一套排查握手失败的检查顺序。

MCP 全称 Model Context Protocol，你可以把它理解成模型和外部工具之间的“USB 接口协议”：服务端把工具、资源、提示模板按统一格式暴露出来，客户端按同一套格式去发现和调用。Spring AI 的 Boot Starter 做的事，就是把这套协议塞进 Spring Boot 的自动配置体系里，让你用几个@Bean和几行 yaml 就能起一个 MCP Server。

2. 前置准备：依赖、TaoToken Key 与通道位置

先把依赖定下来。本地调试我一般选 WebMVC 版本，因为它自带 web 容器，SSE 端点开箱即用，比 STDIO 更适合用 curl 直接验证。

<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId> </dependency>

如果你要的是命令行/桌面工具那种无 web 依赖的形态，换成spring-ai-mcp-server-spring-boot-starter，走 STDIO 传输。两者自动配置类不同，WebMVC 会激活McpWebMvcServerAutoConfiguration，同时把spring-boot-starter-web带进来。

接下来是 Key 和通道。TaoToken 在这里扮演的是统一 API 出口：你不需要在每个工具里散落不同的 Key，而是让 MCP Server 内部调用模型时都走同一个 base URL 和同一个 Key。控制台里创建 Key 的入口在 https://taotoken.net/console ，Key 列表页在 https://taotoken.net/api-keys 。API 通道地址是https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 base URL 使用。

我习惯把 Key 放在环境变量里，而不是写死在settings.json或 yaml 中，这样提交代码时不会泄露：

export TAOTOKEN_API_KEY="sk-你的Key"

然后在 Spring 配置里引用它。下面这份application.yml是 WebMVC + SYNC 的最小可用骨架，注意base-url和sse-message-endpoint这两项，它们直接决定客户端要连哪个路径。

server: port: 8080 spring: ai: mcp: server: name: demo-mcp-server version: 1.0.0 type: SYNC instructions: "本地调试用的 MCP 服务，暴露天气查询工具" sse-endpoint: /sse sse-message-endpoint: /mcp/message capabilities: tool: true resource: true prompt: true completion: true request-timeout: 30s

关于type，SYNC 用McpSyncServer，适合请求-响应式的直接调用；ASYNC 用McpAsyncServer，基于 Project Reactor，适合非阻塞场景。本地调试先用 SYNC，出问题好定位。

3. 可复制的 settings.json 骨架与工具注册

MCP 客户端侧的settings.json是连接配置的核心。不同客户端字段名略有差异，但结构一致：一个mcpServers对象，里面每个键是一个服务名，值是传输方式加地址。下面这份骨架以 SSE 传输为例，把 TaoToken 的通道信息也一并放进去，方便你在同一个文件里管理。

{ "mcpServers": { "demo-spring-boot": { "transport": "sse", "url": "http://localhost:8080/sse", "messageUrl": "http://localhost:8080/mcp/message", "headers": { "Authorization": "Bearer ${TAOTOKEN_API_KEY}" }, "env": { "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_API_KEY": "${TAOTOKEN_API_KEY}" }, "timeout": 30000 } } }

几个字段要重点核对。url对应服务端的sse-endpoint，默认是/sse；messageUrl对应sse-message-endpoint，默认是/mcp/message。如果你在 yaml 里改了base-url，比如设成/api/v1，那客户端这边两个地址都要加上前缀，变成http://localhost:8080/api/v1/sse和http://localhost:8080/api/v1/mcp/message。这是最常见的连不上的原因，改了一边忘了另一边。

headers里的 Authorization 是给需要鉴权的场景用的。TaoToken 的 Key 通过环境变量注入，settings.json里只写占位符，避免明文落盘。

服务端这边，工具通过ToolCallbackProvider注册，自动配置会扫描所有ToolCallback类型的 bean 并合并：

@Service public class WeatherService { @Tool(description = "根据城市名查询天气") public String getWeather(String cityName) { return cityName + " 今天晴，气温 22 度"; } } @SpringBootApplication public class McpServerApplication { public static void main(String[] args) { SpringApplication.run(McpServerApplication.class, args); } @Bean public ToolCallbackProvider weatherTools(WeatherService weatherService) { return MethodToolCallbackProvider.builder() .toolObjects(weatherService) .build(); } }

工具按名称去重，同名工具只保留第一个出现的。如果你有多个 bean 提供工具，自动配置会把它们合并成一个列表，不用手动聚合。

4. 启动与连通性验证：curl 命令与预期返回

配置写完，启动应用：

./mvnw spring-boot:run

看到 Tomcat 在 8080 端口启动、日志里出现 MCP Server 初始化相关的行，就说明服务端起来了。接下来验证 SSE 端点是否真的在推事件。开一个终端执行：

curl -N -H "Accept: text/event-stream" http://localhost:8080/sse

-N关闭缓冲，让你能实时看到推送。预期返回类似：

event: endpoint data: /mcp/message?sessionId=8f3a1c2e-...

这行endpoint事件就是服务端告诉客户端“后续消息往这个地址发”。拿到sessionId之后，再开一个终端发一条初始化请求：

curl -X POST "http://localhost:8080/mcp/message?sessionId=8f3a1c2e-..." \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "curl-test", "version": "1.0.0"} } }'

如果服务端正常，第一个终端会推回一条message事件，内容是 initialize 的结果，包含serverInfo和capabilities。看到capabilities.tools非空，说明工具已经注册成功。再发一条tools/list就能拉到工具清单：

curl -X POST "http://localhost:8080/mcp/message?sessionId=8f3a1c2e-..." \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

预期在 SSE 流里看到getWeather这个工具名。到这一步，服务端和协议层就通了。如果你还想在浏览器里直接跟模型对话验证工具调用效果，可以打开 https://taotoken.net/model-chat ，把同一个 Key 填进去试一轮。

5. 本篇常见错排查

握手失败，curl 连/sse直接断开。先确认依赖是 WebMVC 版本而不是 STDIO 版本。STDIO 版本不监听端口，curl 当然连不上。再看spring.ai.mcp.server.enabled是不是被误设成 false。

SSE 能连上，但 POST 消息返回 404。九成是sse-message-endpoint和客户端messageUrl不一致。默认值/mcp/message容易被记成/mcp/messages，多一个 s 就 404。核对 yaml 和settings.json两边。

工具列表为空。检查capabilities.tool是否为 true，以及ToolCallbackProviderbean 有没有被扫描到。如果用了@Tool注解但没注册 provider，自动配置不会凭空发现它。另外确认工具方法所在类是被 Spring 管理的 bean。

请求超时。request-timeout默认 20 秒，工具内部如果调用了外部模型接口，链路慢的时候容易超。本地调试可以调到 30 到 60 秒。注意这个超时对所有请求生效，包括工具调用、资源读取和提示操作。

改了base-url后客户端连不上。base-url是前缀，会拼在sse-endpoint和sse-message-endpoint前面。设成/api/v1后，客户端两个地址都要带这个前缀，漏改一个就连不通。

Key 读取不到。环境变量在启动应用的 shell 里 export，而不是在另一个终端。用echo $TAOTOKEN_API_KEY确认当前 shell 能看到。settings.json里的${TAOTOKEN_API_KEY}是占位符，需要客户端支持环境变量替换，不支持的话得用客户端自己的密钥管理方式。

6. 把 Key 收拢到一处之后

配置跑通之后，你会发现真正省事的地方在于 Key 不再散落。MCP Server 内部调用模型走https://taotoken.net/api这一个通道，客户端连接走settings.json里的一份配置，环境变量只维护一个TAOTOKEN_API_KEY。后面加新工具、换模型，改的都是同一处。

如果你打算把这个 MCP Server 长期挂在本地做编码辅助或者 Agent 实验，建议顺手看一下 Coding Plan 的额度管理方式，入口在 https://taotoken.net/coding-plan ，把长期调用的配额和临时调试的 Key 分开，避免调试时把额度跑光。接入文档在 https://taotoken.net/doc ，里面有各语言 SDK 的调用示例，需要换语言实现时可以直接对照。

最后留一个我踩过的坑：settings.json改完记得重启客户端，很多 MCP 客户端只在启动时读一次配置，热改不生效，会让你误以为配置写错了。