AI Agent 学习day5：MCP 协议入门与实践，把 Spring AI 的 endpoint 改到 TaoToken

1. 从 Function Call 到 MCP工具规模化后的管理难题如果你正在学 AI Agent大概率已经写过 Function Call 的 demo定义几个 JSON Schema模型返回tool_calls代码里 if-else 路由到对应函数。两个工具的时候很爽二十个工具的时候就开始难受了。我试过在一个 Spring Boot 项目里手写十几个工具的 Schema改一个参数名要同步改三处Schema 定义、路由分支、执行方法。更麻烦的是工具发现——新同事接手时根本不知道系统里有哪些工具可用只能翻代码。这就是 Function Call 的边界它解决的是模型能不能调用工具但不解决工具多了怎么管。MCPModel Context Protocol模型上下文协议要解决的就是后者。你可以把它理解成大模型世界的 USB 接口工具只要实现 MCP Server任何支持 MCP 的 HostClaude Desktop、Cursor、你自己的 Spring AI 应用都能调用它不用为每个工具单独写适配代码。MCP 的架构分三层。Host 是用户直接使用的 AI 应用负责接收输入、调用模型、协调工具调用Client 是 Host 内部的通信组件负责和 Server 建立连接、获取工具列表、发送调用请求Server 是真正提供工具的一方声明自己有哪些工具、执行逻辑、返回结果。一个 Host 可以挂多个 Client每个 Client 连一个 Server这样就能把 HR 系统、订单系统、知识库的能力组合起来。MCP 定义了三种核心能力Tools工具调用最常用、Resources资源访问偏读取资料、Prompts提示词模板可复用。实际项目里 Tools 占九成以上Resources 和 Prompts 了解即可。传输方式有两种。Stdio 走本地进程标准输入输出适合个人开发和本地工具不暴露端口、安全性高Streamable HTTP 走远程 HTTP 服务适合团队共享和生产环境能利用 HTTP 生态做认证、监控、负载均衡。个人本地用 Stdio团队和生产用 Streamable HTTP这是基本判断。MCP 和 Function Call 不是替代关系。Function Call 是发动机让模型能输出调用意图MCP 是整车负责工具定义、发现、通信、复用。Spring AI 则是 MCP 协议的一种 Java 实现方式——MCP 是标准Spring AI 是方便你写 MCP Server 的框架类比 HTTP 协议和 Spring MVC 的关系。这一篇的目标很具体把 Spring AI 的 endpoint 从默认地址改到 TaoToken 统一通道完成一次 MCP 工具调用闭环。你会拿到可复制的application.yml配置、curl 验证命令以及常见报错的排查路径。适合正在学 AI Agent、手上有 Java 项目、想把工具调用跑通的开发者。2. TaoToken 前置准备统一 Key 与 API 通道配置在动手改 Spring AI 配置之前先把 TaoToken 这边的准备工作做完。这一步不复杂但顺序别搞反否则后面调试会多花时间。首先打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号。注册流程就是常规的邮箱加密码不展开。登录后进入控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在 API Keys 页面创建一个新的 Key。创建时建议给 Key 起个能认出来的名字比如spring-ai-mcp-dev方便后面区分环境。Key 创建后只显示一次复制下来存到安全的地方。如果你用.env文件管理可以写成TAOTOKEN_API_KEYsk-xxxx的形式如果直接写进application.yml注意别把配置文件提交到公开仓库。接下来确认你要用的模型 ID。在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以试跑一下确认模型能正常返回。常用的模型 ID 比如claude-sonnet-4-20250514、gpt-4o这类具体以控制台里列出的为准。MCP 工具调用对模型的 function calling 能力有要求选支持工具调用的模型。Base URL 统一用https://taotoken.net/api注意这个地址不加 UTM 参数直接写进配置即可。完整的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各语言 SDK 的接入示例Java 部分可以参考。如果你打算长期跑编码类 Agent 任务可以看一下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 按套餐走比按量计费更划算。只是做 MCP 入门验证的话按量付费就够了。这里有个容易踩的坑Key 的权限范围。创建 Key 时如果选了受限权限可能只能调部分模型。MCP 工具调用需要模型支持 function calling如果 Key 绑定的模型不支持后面会报模型能力相关的错误。建议先用默认权限跑通再按需收紧。准备工作清单注册并登录 TaoToken在 API Keys 页面创建 Key 并保存在模型对话页面确认模型 ID 可用记下 Base URLhttps://taotoken.net/api确认 Key 有调用目标模型的权限这些做完就可以进入 Spring AI 的配置环节了。3. 可复制配置application.yml 与 MCP Client 接入这一节是核心操作部分。Spring AI 从 1.0 版本开始提供了 MCP Client 的 starter我们用它来连接 MCP Server同时把模型 endpoint 指向 TaoToken。先看依赖。在pom.xml里加入 Spring AI 的 MCP Client starter 和 OpenAI 兼容的模型 starterdependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-client/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency版本管理用 Spring AI 的 BOM在dependencyManagement里引入spring-ai-bom版本选 1.0.0 或更高。MCP Client starter 会自动带上 MCP 协议实现和 Stdio/HTTP 两种传输的支持。然后是application.yml。这是最关键的一段路径和字段名要和 Spring AI 的约定一致spring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: claude-sonnet-4-20250514 temperature: 0.7 mcp: client: enabled: true name: spring-ai-mcp-client version: 1.0.0 type: SYNC request-timeout: 30s stdio: connections: hr-server: command: java args: - -jar - ./mcp-servers/hr-server.jar streamable-http: connections: order-server: url: http://localhost:8081 endpoint: /mcp几个字段说明一下。base-url指向 TaoToken 的 API 地址注意结尾不要多加斜杠。api-key用环境变量注入避免硬编码。model填你在控制台确认过的模型 ID。mcp.client.type选SYNC表示同步调用入门阶段够用如果要异步可以改ASYNC。stdio.connections下面配本地 MCP Servercommand是启动命令args是参数。这里假设你有一个打包好的hr-server.jar它实现了 MCP 协议、暴露了getUserAnnualLeave等工具。streamable-http.connections配远程 MCP Serverurl加endpoint拼出完整地址。如果你用的是 Claude Code 或 Cline 这类工具配置格式会不一样。Claude Code 的 MCP 配置在~/.claude/claude_desktop_config.json或项目级.mcp.json里格式是{ mcpServers: { hr-server: { command: java, args: [-jar, ./mcp-servers/hr-server.jar] }, order-server: { url: http://localhost:8081/mcp } } }Cline 的 MCP 配置在 VS Code 的settings.json里走cline.mcpServers字段结构类似。Codex 的auth.json则是另一套主要配 API Key 和 Base URLMCP 部分在config.toml里。这三件套的核心都是 Base URL、Key、Model ID 三个要素只是载体不同。回到 Spring AI。配置写完后写一个配置类把ChatClient和 MCP 工具注册进去Configuration public class McpConfig { Bean public ChatClient chatClient(ChatClient.Builder builder, ToolCallbackProvider toolCallbackProvider) { return builder .defaultToolCallbacks(toolCallbackProvider) .build(); } }ToolCallbackProvider是 Spring AI 自动装配的它会从 MCP Client 拉取所有已连接 Server 的工具列表转成 Spring AI 的ToolCallback。这样模型在对话时就能看到这些工具并按需调用。注意defaultToolCallbacks这个方法名不同小版本可能有差异以你引入的 Spring AI 版本为准。如果编译报错找不到方法去接入文档里核对一下当前版本的 API。配置阶段最容易出问题的地方是 YAML 缩进。spring.ai.mcp.client下面的层级比较深缩进错了启动时会报绑定失败。建议用 IDE 的 YAML 插件校验或者启动后看日志里有没有McpClientAutoConfiguration相关的报错。4. 验证请求curl 与 MCP 工具调用闭环配置写好了怎么确认真的通了分两步先用 curl 验证 TaoToken 通道本身能通再跑 Spring AI 应用验证 MCP 工具调用闭环。第一步curl 验证模型通道。这条命令直接打 TaoToken 的 chat completions 接口curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [ {role: user, content: 你好请回复 OK} ] }正常返回是一个 JSONchoices[0].message.content里会有模型回复。如果返回 401说明 Key 不对或没带上如果返回 404检查 base-url 后面有没有多写/v1——TaoToken 的 base-url 是https://taotoken.net/apiSDK 会自动拼/v1/chat/completionscurl 手动拼的时候要写全。第二步验证带工具调用的请求。这条 curl 模拟模型看到工具定义后返回 tool_calls 的场景curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [ {role: user, content: 帮我查一下 user_123 还剩几天年假} ], tools: [ { type: function, function: { name: getUserAnnualLeave, description: 查询用户年假余额, parameters: { type: object, properties: { userId: {type: string, description: 用户ID} }, required: [userId] } } } ] }如果模型支持 function calling返回的choices[0].message里会有tool_calls字段function.name是getUserAnnualLeavearguments里是{userId: user_123}。这说明模型正确识别了工具并输出了调用意图。第三步跑 Spring AI 应用。启动你的 Spring Boot 项目日志里应该能看到 MCP Client 连接 Server 的记录类似Connected to MCP server: hr-server以及拉取到的工具列表。然后写一个简单的 Controller 或 CommandLineRunner 触发对话RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient chatClient) { this.chatClient chatClient; } GetMapping(/chat) public String chat(RequestParam String message) { return chatClient.prompt() .user(message) .call() .content(); } }访问http://localhost:8080/chat?message帮我查一下user_123还剩几天年假观察返回。如果 MCP 工具调用成功返回内容里会包含年假天数同时日志里能看到 MCP Client 向 Server 发送tools/call请求、Server 返回结果的记录。整个闭环是用户提问 → Spring AI 把工具列表发给模型 → 模型返回 tool_calls → Spring AI 通过 MCP Client 调用 Server → Server 执行工具返回结果 → Spring AI 把结果回传给模型 → 模型生成最终回答。这条链路跑通MCP 入门就算完成了。验证阶段建议开 DEBUG 日志在application.yml里加logging: level: org.springframework.ai: DEBUG io.modelcontextprotocol: DEBUG这样能看到 MCP 协议的完整交互过程对理解协议细节很有帮助。5. 常见报错排查401、local proxy failed 与 OAuth 问题跑不通的时候报错信息往往不够直白。这一节把几个高频错误和排查路径列出来。401 Unauthorized。最常见的原因是 Key 没传对。检查三处环境变量TAOTOKEN_API_KEY有没有导出、application.yml里${TAOTOKEN_API_KEY}有没有被正确解析、Key 有没有多余空格。如果是 curl 报 401确认Authorization头是Bearer sk-xxx格式Bearer 后面有一个空格。还有一种情况是 Key 被禁用或过期去控制台 API Keys 页面确认状态。local proxy failed / connection refused。这个报错通常出现在 MCP Client 连本地 Server 的时候。如果是 Stdio 传输检查command和args能不能在命令行里手动跑通——先java -jar ./mcp-servers/hr-server.jar看能不能启动。如果是 Streamable HTTP检查url和endpoint拼出来的地址能不能 curl 通。端口被占用也会报这个错换个端口试试。reading choices 相关报错。比如Error reading choices from response或choices is null。这通常是响应体格式和 SDK 预期不一致。先看 curl 返回的原始 JSON 结构确认choices字段存在且是数组。如果 curl 正常但 SDK 报错检查 Spring AI 版本和 OpenAI 兼容层的匹配度。TaoToken 的接口是 OpenAI 兼容格式Spring AI 的 OpenAI starter 应该能直接解析。如果用的是其他 starter可能需要调整。OAuth 相关报错。比如OAuth token endpoint returned 400或invalid_client。MCP 的 Streamable HTTP 传输支持 OAuth 认证如果你的 Server 配了 OAuth 但 Client 没配对应的 client_id/secret就会报这个。入门阶段建议先用无认证的本地 Server 跑通再逐步加认证。如果 Server 端不需要 OAuth检查 Client 配置里有没有误开 OAuth 相关选项。工具列表为空。MCP Client 连上了 Server但ToolCallbackProvider拉不到工具。检查 Server 端有没有正确声明工具——MCP 协议要求 Server 在初始化时返回tools/list的结果。如果 Server 是用 Spring AI 写的确认Tool注解的方法所在的类被注册成了 Bean。另外spring.ai.mcp.client.enabled要设为true否则自动装配不生效。模型不返回 tool_calls。curl 带 tools 参数但模型只返回普通文本。这通常是模型不支持 function calling或者 tools 参数格式不对。确认你选的模型在 TaoToken 控制台里标注了支持工具调用。另外有些模型对 tools 的 JSON Schema 有要求parameters必须是合法的 JSON Schematype必须是object。排查通用思路先 curl 验证通道再单独验证 MCP Server最后合起来跑。分层排查比一上来就调整个链路快得多。日志级别开到 DEBUGMCP 协议的交互过程会打出来能看到具体是哪一步断了。如果 401 和连接问题都排除了但工具调用还是不通去接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 核对一下当前版本的配置示例有时候是 starter 版本和配置字段对不上。6. 继续深入从 MCP 入门到 Agent 实战跑通一次 MCP 工具调用闭环之后下一步可以往几个方向深入。一是多 Server 组合。把 HR Server、Order Server、Knowledge Server 都挂上让模型根据问题自动选择调用哪个。这时候你会遇到工具命名冲突、权限隔离、调用链路追踪的问题这些正是 MCP 相比裸 Function Call 的优势所在——Server 端可以独立管理自己的工具和权限Client 端只负责发现和调用。二是传输方式切换。本地开发用 Stdio 很方便但团队共享要换成 Streamable HTTP。把 Server 部署成一个 HTTP 服务加上认证和监控Client 端改一下streamable-http.connections的配置就行。这个切换过程能帮你理解 MCP 协议的分层设计。三是和 RAG 结合。用户问我的订单 12345 能不能退需要同时查订单状态和退货政策。订单状态走 Order MCP Server退货政策走 Knowledge MCP Server模型综合两个结果生成回答。这就是从单纯 RAG 升级到 Agent 的路径。四是可观测性。MCP 调用次数、耗时、失败率、调用链路这些在生产环境很重要。可以在 Client 端加拦截器埋点或者用 MCP 协议本身的日志能力。Spring AI 的 MCP Client 支持自定义McpClientCustomizer可以在里面加监控逻辑。如果你打算长期做 Agent 开发Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 按套餐走比按量计费省心尤其是频繁调试工具调用的时候。模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以快速试不同模型的工具调用表现找到最适合你场景的那个。最后说一个实际经验MCP 入门阶段别追求一次配齐所有 Server。先用一个最简单的本地 Stdio Server 跑通闭环确认模型能正确返回 tool_calls、Client 能正确调用、结果能正确回传。这个最小闭环跑通后再加第二个 Server、再换 HTTP 传输、再加认证。每加一个变量就验证一次比一次性配一堆然后对着报错猜要快得多。工具调用的本质是让模型从只会说变成能办事。MCP 把这个能力标准化了Spring AI 把它 Java 化了TaoToken 把模型通道统一了。三者串起来你手上的 Java 项目就有了接入 Agent 生态的基础。