企业官网建设流程全解析

1. Spring Boot 里把 MCP Server 跑起来，Key 却散落在三个文件里

如果你正在用 Spring Boot 写 Java 后端，又想给 AI 应用暴露一批工具（Tools）、资源（Resources）和提示（Prompts），那 Spring AI 的 MCP Server Boot Starters 基本是绕不开的。它做的事情很直白：把 Model Context Protocol 服务端的组件用 Spring Boot 自动配置的方式装配好，你只要加依赖、写注解、配几行 yml，一个能对外提供能力的 MCP Server 就起来了。适合谁？适合那些手里已经有一堆 Spring 服务、想让 AI 客户端（比如 Claude Code、各类 Agent 框架）通过标准协议调用这些能力的后端同学。

但真正落地时，麻烦往往不在 MCP 本身，而在“模型接入”这一层。MCP Server 负责暴露能力，可它背后要调用的模型、要切换的供应商、要管理的密钥，经常散落在application.yml、config.toml、settings.json好几个地方。多模型切换时，改一处漏一处，本地能跑、换个环境就 401。我试过把 Key 硬编码进配置，结果提交前忘了删，差点出事。

这篇就聚焦一个目标：用 TaoToken 做统一 Key 入口，把 Spring AI + MCP Server Boot Starters 的配置骨架一次性搭好，让你在多个模型之间切换时只改一个地方。下面从依赖、yml、config.toml、settings.json 到启动验证，一步步给可复制的片段。

2. TaoToken 前置：统一 Key 与接入地址

TaoToken 在这里扮演的角色是“统一入口”。你不需要为每个模型供应商单独维护一套 Key 和 Base URL，而是拿一个 TaoToken 的 Key，通过它的 API 地址去访问不同模型。对 Spring AI 来说，这意味着一件事：把base-url和api-key指向 TaoToken，模型名按需切换即可。

需要提前准备的东西不多：

• 一个 TaoToken 账号，登录后在控制台创建 API Key。控制台地址：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
• 记下 API 基础地址：https://taotoken.net/api （这个地址不加 UTM，直接用于配置）
• 想好你要接的模型名，比如对话模型、编码模型，后面在 yml 里作为model值填进去

创建 Key 的入口在 API Keys 页面：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。拿到形如sk-xxxx的字符串后，先别急着写进代码，放到环境变量里更稳妥，后面配置里用${TAOTOKEN_API_KEY}引用。

注意：Key 属于敏感信息，不要直接提交到 Git。本地用环境变量，CI/CD 用密钥管理，这是基本习惯。

如果你还没决定用哪个模型，可以先在模型对话页面手动试一下，确认 Key 和模型名都对得上：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。确认通了再回到 Spring Boot 里配，能省掉很多“到底是 Key 错还是代码错”的排查时间。

3. 可复制配置：依赖、application.yml、config.toml、settings.json

3.1 Maven 依赖：选对 Starter

MCP Server Boot Starters 按传输方式分了好几种。Web 场景下现在推荐用 Streamable-HTTP，SSE 从 2.0.0 起已弃用。下面以 WebMVC + Streamable 为例，pom.xml里加：

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

第一个是 MCP Server 的 WebMVC 启动器，第二个是模型接入用的 OpenAI 兼容 Starter——TaoToken 的 API 是 OpenAI 兼容格式，所以用它来接最省事。版本号跟着你项目的 Spring AI BOM 走，别自己乱填。

3.2 application.yml：MCP Server 与模型接入骨架

这是核心配置。MCP Server 部分用STREAMABLE协议，模型部分把base-url指向 TaoToken：

server: port: 8080 spring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-mini temperature: 0.7 mcp: server: protocol: STREAMABLE type: SYNC annotation-scanner: enabled: true capabilities: tool: true resource: true prompt: true

几个关键点解释一下。protocol: STREAMABLE对应 Streamable-HTTP 传输，服务端作为独立进程用 HTTP POST/GET 处理多客户端连接，必要时用 SSE 流式返回。type: SYNC表示用McpSyncServer，只注册同步的注解方法；如果你写的是响应式方法，就改成ASYNC，它会用McpAsyncServer并带上 Project Reactor 支持。annotation-scanner.enabled: true让自动配置去扫描带 MCP 注解的 Bean。

capabilities里三项默认都是启用的，写出来是为了让你知道可以按需关。关掉某项，服务端就不会向客户端注册对应能力。

3.3 config.toml：客户端侧连接 MCP Server

如果你用的是支持 MCP 的客户端（比如 Claude Code 这类），它通常读一个config.toml或类似配置文件来知道去哪连 MCP Server。Streamable-HTTP 的写法大致如下：

[[mcp_servers]] name = "spring-boot-mcp" transport = "streamable-http" url = "http://localhost:8080/mcp"

这里的url路径取决于你的传输提供者注册的端点，WebMVC Streamable 默认挂在/mcp下。启动 Spring Boot 后，客户端就能通过这个地址发现你暴露的 Tools 和 Resources。

3.4 settings.json：TaoToken 统一 Key 片段

有些工具链（比如某些 Agent 框架或编辑器插件）用settings.json管理模型凭证。把 TaoToken 的 Key 和地址写进去，格式类似：

{ "model_providers": { "taotoken": { "base_url": "https://taotoken.net/api", "api_key": "${TAOTOKEN_API_KEY}", "models": ["gpt-4o-mini", "claude-3-5-sonnet"] } } }

这样无论上层是 Spring AI 还是别的客户端，Key 都从同一个环境变量取，切换模型只改models列表里的名字，不用动 Key。

4. 验证请求：写一个 Tool，启动后调一次

配置写完，得验证它真的通了。分两步：先写一个带@McpTool的 Bean，再启动应用发一个请求。

4.1 写一个可被扫描的 Tool

@Component public class CalculatorTools { @McpTool(name = "add", description = "将两个数字相加") public int add( @McpToolParam(description = "第一个数字", required = true) int a, @McpToolParam(description = "第二个数字", required = true) int b) { return a + b; } @McpResource(uri = "config://{key}", name = "配置") public String getConfig(String key) { return "value-of-" + key; } }

@McpTool会把方法标记成 MCP 工具，并自动生成 JSON Schema；@McpResource通过 URI 模板暴露资源。自动配置会扫描这些 Bean，创建对应规范并注册到 MCP Server。

4.2 启动并验证

启动类保持最简：

@SpringBootApplication public class McpServerApplication { public static void main(String[] args) { SpringApplication.run(McpServerApplication.class, args); } }

启动后，用 curl 走一次 Streamable-HTTP 的初始化请求，确认服务端在监听：

curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "curl-test", "version": "1.0"} } }'

如果返回里带serverInfo和capabilities，说明 MCP Server 起来了。接着调工具：

curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "add", "arguments": {"a": 3, "b": 4}} }'

预期返回里result.content包含7。到这一步，Spring AI 与 MCP 通道就算跑通了。模型侧是否通，可以在业务代码里注入ChatClient发一句测试，确认 TaoToken 的 Key 生效。

5. 本篇常见错排查

配置跑不通，八成是下面几个原因。按顺序查，能省不少时间。

启动报找不到 MCP 端点。检查spring.ai.mcp.server.protocol是否写成了STREAMABLE，以及依赖是不是spring-ai-starter-mcp-server-webmvc。如果用了 WebFlux 却引了 WebMVC 的 starter，传输提供者不会注册，端点自然不存在。

Tool 没被注册。先确认annotation-scanner.enabled: true，再确认type和方法的同步/异步属性匹配。SYNC只注册同步方法，ASYNC只注册异步方法，写反了方法会被静默忽略，不报错，很容易误判。

调用模型返回 401。大概率是api-key没读到环境变量。检查${TAOTOKEN_API_KEY}是否真的在运行环境里设置了，别只在 IDE 的 Run Configuration 里设、换到命令行就没了。另外确认base-url是https://taotoken.net/api，结尾不要多加/v1之类的路径，OpenAI 兼容 Starter 会自己拼。

Streamable 请求返回 406。多半是Accept头没带text/event-stream。Streamable-HTTP 允许用 SSE 流式返回多条消息，客户端要显式声明接受这种类型，否则服务端可能拒绝。

多模型切换后行为不对。检查model值是否在 TaoToken 支持的模型列表里。名字写错时，有的供应商返回 404，有的返回一个默认模型，表现不一致，最好先在模型对话页面确认模型名可用。

提示：排障时把日志级别调到 DEBUG，logging.level.org.springframework.ai=DEBUG，能看到 MCP 注册和模型请求的细节，比盲猜快得多。

6. 把 Key 收口到一处，后面切换才不痛

整套配置下来，最值得坚持的一点是：Key 只从环境变量取，模型名只在一处改。Spring AI 的 MCP Server Boot Starters 负责把能力暴露出去，TaoToken 负责把模型接入收口，两者职责分开，配置就不会互相污染。

如果你后面要长期跑编码类任务或 Agent，建议直接看 Coding Plan，它更适合持续性的编码场景：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。接入细节和参数说明都在文档里：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。Claude Code 相关的接入方式可以看：https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。

最后留一个我踩过的坑：config.toml里的 MCP Server 地址别写127.0.0.1又指望容器里的客户端能连上，跨容器时用服务名或宿主机地址。这种问题不报配置错，只表现为连接超时，查起来最费劲。