把 Spring AI 的 @Tool 一键暴露成 MCP Server:我用它让 30 个老接口变成 工具

💡 提示

篇5 · 干货教程 · 字数：约 3600 字 | 阅读时长：10–12 分钟

概念本质类比

Function Calling模型的能力一个人"会说中文"

MCP工具与客户端的传输协议"USB-C 接口"标准

关键认知：一个 @Tool 方法 = 两件事

java

@Tool(description="查询订单状态")publicStringqueryOrder(StringorderNo) { ... }

—本地工具：你当前的 Spring 应用内，LLM 可以直接调（Function Calling）

—MCP Server 端点：通过网络暴露出去，Claude Desktop、Cursor 等外部客户端也能调（MCP）

💡 提示

用一句话总结：Function Calling 是"让模型会调工具"，MCP 是"让工具被全世界用到"。 前者是模型能力，后者是生态协议。

传输方式适用场景优点缺点

STDIO本地工具（同机进程）零网络开销、配置简单只能本机、不适合服务化

SSE旧版远程方案兼容早期客户端⚠️ 已被 MCP 规范标记为 deprecated

Streamable HTTP生产环境首选支持无状态、可水平扩展、走标准 HTTP需要 HTTP 基础设施

—本地开发 / 单机工具 → STDIO（比如文件系统、Git 操作）

—生产环境 / 服务化 / 多客户端共享 → Streamable HTTP

—除非有历史包袱，别再选 SSE（新规范里它是过渡方案）

依赖

xml

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

三种注解：Tool / Resource / Prompt

java

@ComponentpublicclassOrderMcpTools {@McpTool(description="根据订单号查询订单状态，返回 待发货/已发货/已签收")publicStringqueryOrderStatus(@McpToolParam(description="订单号，例如 A12345") StringorderNo,@McpToolParam(description="用户ID，用于权限校验") StringuserId) {// 复用已有的 Service，权限校验在里面returnorderService.getStatus(orderNo, userId);    }}

java

@McpResource(uri="order://{orderNo}/detail",name="订单详情",description="读取指定订单的完整信息（JSON）")publicStringgetOrderDetail(StringorderNo) {returnjson(orderService.findDetail(orderNo));}

java

@McpPrompt(name="order-complaint", description="生成订单投诉话术")publicStringcomplaintPrompt(@McpPromptParam(description="订单号") StringorderNo) {return"""        请以客服身份，针对订单 %s 生成一段专业、有同理心的投诉处理话术。        要求：先共情、再说明、最后给方案，不超过 150 字。        """.formatted(orderNo);}

自动生成的 JSON Schema

json

{"name": "queryOrderStatus","description": "根据订单号查询订单状态，返回 待发货/已发货/已签收","inputSchema": {"type": "object","properties": {"orderNo": { "type": "string", "description": "订单号，例如 A12345" },"userId":  { "type": "string", "description": "用户ID，用于权限校验" }    },"required": ["orderNo", "userId"]  }}

💡 提示

这是 MCP 最爽的一点：@McpToolParam 的 description 会自动变成 LLM 判断"要不要调"的依据。写清楚描述 = 工具好用的一半。

启动

yaml

spring:ai:mcp:server:name: order-mcp-serverversion: 1.0.0protocol: STREAMABLE_HTTP   # 生产推荐

java

@SpringBootApplicationpublicclassMcpServerApplication {publicstaticvoidmain(String[]args) {SpringApplication.run(McpServerApplication.class, args);    }}

改造前 vs 改造后

项目改造前改造后

代码量每个接口写一个 Function 包装（~30 行）加 2 个注解（~2 行）

暴露范围只能本应用内 LLM 调用任何 MCP 客户端都能调

维护接口变了要改两处改一处

总工时预计 2 天半小时

改造姿势

java

// 改造前：一个普通的 MVC Controller@GetMapping("/order/{orderNo}")publicOrderVOgetOrder(@PathVariableStringorderNo, @RequestHeaderStringuserId) {returnorderService.getOrder(orderNo, userId);}// 改造后：加注解，变成 MCP Tool（原接口保持不变）@McpTool(description="查询订单详情")publicOrderVOgetOrder(@McpToolParam(description="订单号") @PathVariableStringorderNo,@McpToolParam(description="用户ID") @RequestHeaderStringuserId) {returnorderService.getOrder(orderNo, userId);}

权限、限流、审计怎么保留？

java

@ConfigurationpublicclassMcpSecurityConfig {@BeanpublicMcpServerFeatures.SyncToolSpecificationsecuredTools(OrderMcpToolstools, AuthServiceauth, RateLimiterlimiter, AuditLogaudit) {// 1. 权限：校验 userId 是否有权访问该订单// 2. 限流：每用户每分钟 N 次// 3. 审计：记录谁在什么时候调用了什么工具、参数、结果        ...    }}

💡 提示

反过来说：如果你发现改造时要复制一遍权限逻辑，说明你的分层有问题，趁这个机会修掉。

分布式注册：Nacos MCP Registry

yaml

spring:ai:alibaba:mcp:nacos:server-addr: ${NACOS_ADDR}service-name: order-mcp-server

方式 1：Spring AI MCP Client（自己写 Agent）

xml

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

yaml

spring:ai:mcp:client:streamable-http:connections:order-server:url: http://localhost:8080/mcp

java

Stringanswer=chatClient.prompt()        .user("帮我查一下订单 A12345 的状态")        .call().content();// 模型自动调用 order-mcp-server 的 queryOrderStatus

方式 2：Claude Desktop / Cursor 直连

json

{"mcpServers": {"order-server": {"url": "http://your-host:8080/mcp"    }  }}

#坑后果解法

1还在用 SSE未来不兼容换 Streamable HTTP

2@McpToolParam 描述为空LLM 不会调用描述写清楚用途和格式

3工具方法无权限校验越权风险复用 Service 层校验，参数带 userId

4工具无幂等性重复调用出问题危险操作加二次确认或幂等键

5暴露了删除/转账类工具安全事故只暴露读操作，写操作必须人工确认

6没做限流被刷爆Advisor 链加限流

7无审计日志出事查不到记录工具调用全链路

8工具粒度太细LLM 选择困难按业务动作聚合（一个工具做一件事）

💡 提示

https://github.com/java-ai-in-action/mcp-in-action  含：@McpTool / @McpResource / @McpPrompt 三种注解示例、Streamable HTTP 配置、权限+限流+审计 Advisor、Claude Desktop 接入配置

💡 提示

本文为「Java AI 实战派」系列第 5 篇，共 10 篇，不定时更新。   上一篇：篇4 ·《RAG 准确率从 32% 干到 89%：重写切片、混合检索与 Rerank 的全流程》   下一篇：篇6 ·《我用 Spring AI Alibaba + Nacos 搭了个企业级 Multi-Agent，老板看完沉默了》

💡 提示

版本说明：本文基于 Spring AI 2.0 GA 与 MCP 1.0 规范编写，具体 API 与版本号以官方仓库为准。