Spring AI MCP 核心注解详解：@McpTool、@McpResource、@McpPrompt 的区别与应用（TaoToken 统一 Key 接入版）

1. 为什么 Java 开发者需要搞懂这三个注解如果你正在用 Spring AI 搭一个能被 AI 工具调用的服务端大概率会遇到一个绕不开的问题MCP 协议里 Tool、Resource、Prompt 到底该怎么分工我见过不少项目把三者混着用结果 AI 客户端要么调不到工具要么读资源时返回一堆无用上下文排查起来非常痛苦。MCPModel Context Protocol本质上是给大模型和外部系统之间定的一套“对话规则”。Spring AI 把这套规则封装成了三个注解McpTool负责“做事”McpResource负责“给数据”McpPrompt负责“定格式”。你可以把它们理解成一个餐厅Tool 是厨师执行动作Resource 是冰箱提供原料Prompt 是菜谱模板规定怎么做。三者配合AI 才能稳定地完成复杂任务。这篇内容面向已经会用 Spring Boot、但还没把 MCP 注解跑通的 Java 开发者。我会先讲清楚三个注解的语义边界再给出一份可以直接复制的application.yml和 TaoToken 统一 Key 配置骨架最后用 Cline 或 CC Switch 连接后逐步验证McpTool触发、McpResource读取、McpPrompt渲染的完整链路。整个过程不需要你额外折腾网络环境只要本地能跑 Spring Boot 就行。2. TaoToken 前置统一 Key 与 MCP 服务端的关系在动手写注解之前先把 Key 的事情理清楚。MCP 服务端本身不直接调用大模型它只是把能力暴露给 AI 客户端比如 Cline、CC Switch。真正需要 Key 的地方是客户端侧——客户端拿着 Key 去请求模型模型决定要不要调用你暴露的 Tool、读取你注册的 Resource。TaoToken 在这里的角色是提供一个统一的 API 入口让你在客户端配置一次 Key就能访问多个模型。对于 MCP 调试来说这意味着你不需要为每个模型单独换 Key切换模型时只改模型名就行。你需要提前准备两样东西第一一个可用的 API Key。到 TaoToken 控制台创建即可地址是https://taotoken.net/console创建完记得复制保存页面刷新后不会再显示完整 Key。第二确认你的 Spring Boot 项目已经引入 Spring AI MCP 相关依赖。下面是一个最小化的pom.xml片段Spring Boot 3.2 和 Spring AI 1.0.0-M6 以上版本都适用dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-server-spring-boot-starter/artifactId version1.0.0-M6/version /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server-webmvc/artifactId version1.0.0-M6/version /dependency如果你用的是 Gradle对应换成implementation即可。依赖拉不下来时先检查仓库里有没有配 Spring MilestoneM6 版本还在里程碑仓库里。注意TaoToken 的 API 地址是https://taotoken.net/api这个地址是给客户端调模型用的不是给你的 MCP 服务端用的。服务端只负责暴露能力不负责转发模型请求。3. 可复制配置application.yml 与三个注解的完整骨架3.1 application.yml 骨架先给一份可以直接粘贴的配置。关键点是spring.ai.mcp.server这一段它决定了你的服务端以什么方式暴露给客户端。这里用 WebMVC 的 SSE 模式适合本地调试server: port: 8080 spring: application: name: spring-ai-mcp-demo ai: mcp: server: name: demo-mcp-server version: 1.0.0 protocol: SSE sse-endpoint: /sse sse-message-endpoint: /mcp/message capabilities: tool: true resource: true prompt: truecapabilities三个开关建议全开否则客户端可能看不到对应类型的能力。sse-endpoint是客户端连接地址后面 Cline 里填的就是http://localhost:8080/sse。3.2 McpTool让 AI 执行动作Tool 的语义是“执行一个动作并返回结果”。它适合做计算、调外部 API、写文件、查数据库这类有副作用的操作。Spring AI 里注册 Tool 有两种方式推荐用ToolCallbackProvider显式注册避免扫描不到。package com.example.mcp.tool; import org.springframework.ai.tool.annotation.Tool; import org.springframework.stereotype.Component; Component public class OrderTool { Tool(description 根据订单号查询订单状态返回状态码和描述) public String queryOrderStatus(String orderId) { if (orderId null || orderId.isBlank()) { return 订单号不能为空; } // 模拟查询 return 订单 orderId 状态已发货预计明天送达; } }注册到容器package com.example.mcp.config; import com.example.mcp.tool.OrderTool; import org.springframework.ai.tool.ToolCallbackProvider; import org.springframework.ai.tool.method.MethodToolCallbackProvider; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class McpToolConfig { Bean public ToolCallbackProvider orderToolProvider(OrderTool orderTool) { return MethodToolCallbackProvider.builder() .toolObjects(orderTool) .build(); } }description一定要写清楚模型是根据这段描述决定要不要调用的。我试过把描述写成“查询订单”结果模型经常不触发改成“根据订单号查询订单状态返回状态码和描述”之后触发率明显提升。3.3 McpResource让 AI 读取数据Resource 的语义是“读取一份数据”它不应该有副作用。适合暴露配置文件、知识库文档、只读的数据库视图。URI 是资源的唯一标识客户端通过 URI 来读取。package com.example.mcp.resource; import org.springframework.ai.mcp.annotation.McpResource; import org.springframework.stereotype.Component; Component public class ConfigResource { McpResource( uri config://app/features, name 应用功能开关, description 返回当前应用的功能开关配置JSON 格式 ) public String getFeatureFlags() { return { newCheckout: true, betaSearch: false, maxRetry: 3 } ; } }注意 URI 的 scheme 可以自定义config://、file://、db://都行只要客户端能识别。Resource 返回的内容会直接进入模型上下文所以不要返回超大文本否则会挤占 token。3.4 McpPrompt让 AI 按模板渲染Prompt 的语义是“生成一段标准化的提示词”。它不执行动作也不读数据而是把参数填充进模板返回给客户端。适合统一 AI 的回复格式比如总结、翻译、代码审查。package com.example.mcp.prompt; import org.springframework.ai.mcp.annotation.McpPrompt; import org.springframework.ai.mcp.annotation.McpPromptArg; import org.springframework.stereotype.Component; import java.util.Map; Component public class SummaryPrompt { McpPrompt( name summarize, description 总结一段文本输出不超过100字 ) public String summarize( McpPromptArg(name content, description 待总结的文本) String content) { return 请用不超过100字总结以下内容保留关键数字和结论\n content; } }Prompt 的返回值就是最终提示词客户端拿到后会直接发给模型。参数用McpPromptArg标注客户端会提示用户填写。4. 验证请求用 Cline 或 CC Switch 跑通完整链路4.1 启动服务端先确认端口没被占用然后启动 Spring Bootmvn spring-boot:run看到日志里出现Registered tool: queryOrderStatus、Registered resource: config://app/features、Registered prompt: summarize就说明三个注解都生效了。如果只看到部分检查对应的Component有没有被扫描到。4.2 在 Cline 里配置 MCP 服务端打开 Cline 的 MCP 配置添加一个 SSE 类型的服务端{ mcpServers: { spring-ai-demo: { url: http://localhost:8080/sse, disabled: false } } }保存后 Cline 会自动连接连接成功会在工具列表里看到queryOrderStatus、config://app/features、summarize三项。4.3 验证 McpTool 触发在 Cline 对话框里输入“帮我查一下订单 A12345 的状态”。模型应该会调用queryOrderStatus返回“订单 A12345 状态已发货预计明天送达”。如果没触发把description再写具体一点或者在对话里明确说“使用 queryOrderStatus 工具”。4.4 验证 McpResource 读取输入“读取 config://app/features 的内容”。客户端会发起资源读取请求返回那段 JSON。如果客户端不支持直接读 URI可以换成“当前应用有哪些功能开关”模型会自己决定去读资源。4.5 验证 McpPrompt 渲染输入“用 summarize 模板总结这段话Spring AI 的 MCP 支持三种注解……”。客户端会弹出参数填写框填入 content 后模型收到的是渲染后的提示词输出一段不超过100字的总结。4.6 客户端侧 Key 配置如果你在 Cline 里同时配置了模型Key 填 TaoToken 控制台创建的那个API 地址填https://taotoken.net/api。这样模型请求走 TaoTokenMCP 能力走本地服务端两边互不干扰。想换模型时只改模型名Key 不用动。5. 本篇常见错排查问题一客户端连不上 SSE报 404。检查sse-endpoint配置是不是/sse以及 Spring Boot 有没有正常启动。如果用了 Spring Security需要放行/sse和/mcp/message。问题二Tool 注册了但模型不调用。九成是description太模糊。把动作、输入、输出都写进去比如“根据订单号查询订单状态输入为字符串订单号返回状态码和描述”。另外确认ToolCallbackProvider的 Bean 被 Spring 管理了。问题三Resource 返回内容乱码。检查返回的字符串编码Spring 默认 UTF-8但如果你的文件读取用了其他编码需要显式指定。Resource 的 URI 不要带空格和中文。问题四Prompt 参数填了但没渲染。McpPromptArg的name要和模板里的占位符对应。如果你用的是字符串拼接而不是模板引擎确认拼接逻辑没有把参数丢掉。问题五三个能力只显示一个。检查application.yml里的capabilities是不是全开了。有些客户端只显示 Tool不显示 Resource 和 Prompt换 CC Switch 试试它对三类能力的展示更完整。问题六TaoToken Key 在客户端报 401。确认 Key 没有多余空格API 地址是https://taotoken.net/api而不是带 UTM 的官网地址。如果刚创建 Key等几秒再试控制台有缓存。6. 把注解用对比堆功能更重要跑通这三个注解之后你会发现 MCP 服务端的设计其实很克制Tool 只做动作Resource 只读数据Prompt 只出模板。很多项目出问题不是因为功能不够而是因为把三者混在一起——比如在 Tool 里返回一大段配置或者在 Resource 里做写操作。边界清晰了模型调用才稳定。如果你准备长期用这套东西做编码助手或 Agent建议把 Key 统一放在 TaoToken 的 Coding Plan 里管理地址是https://taotoken.net/coding-plan这样多个客户端共用一个 Key切换模型时不用到处改配置。接入文档在https://taotoken.net/doc里面有各客户端的详细配置示例。想先验证模型对话效果可以直接用https://taotoken.net/models里的对话入口试几句确认 Key 没问题再往客户端里填。最后留一个我踩过的坑Resource 的 URI 不要用file://去读项目外的绝对路径客户端可能会因为权限问题读不到换成自定义 scheme 加内存数据更稳。