MCP Server 用 Java 写:让 AI 直接调你的接口
你花两个月做的订单系统,接口文档写了四十页。同事想让 Claude 帮忙查一个订单,还是得先打开 Postman,复制订单号,粘进聊天框,再把返回的 JSON 贴回去让模型解释。模型很聪明,问题是它看不见你的系统。
MCP 就是补这块的:把你已有的 Java 方法包装成 AI 客户端能自动发现、自动调用的工具。写一次,Claude Desktop、Cursor、自己写的 Agent 都能直接用。下面从协议原理讲到能跑的代码,最后说几个上了线才会暴露的坑。
一、MCP 到底解决什么问题:AI 看不见你的 Java 接口
MCP 解决的是「工具供给」问题,不是「模型能力」问题。模型会不会调工具早就不是瓶颈了,瓶颈是:它凭什么知道你有哪些工具。
先看没有 MCP 的世界。Function Calling 的函数声明是写在应用里的,声明和调用方绑死。你给客服机器人写了 queryOrderStatus 的函数声明,这份声明只活在那个机器人里。换成 Cursor 想查同一张订单表,得再写一遍;换成团队另一个 Go 项目里的 Agent,还得再写一遍,换个 JSON 结构。五个入口,五份重复声明,五个地方各自维护参数格式。
更烦的是格式不统一。每家大模型的 function 声明长得都差不多但又都不一样,字段名、必填语义、参数描述的位置都有细微差别。你的业务逻辑明明只有一份,适配层却要写 N 份。
MCP 把这一层单独抽了出来。它是一份协议,规定了「工具怎么描述」「工具怎么被调用」「结果怎么返回」。你的 Java 服务实现一次协议,任何支持 MCP 的客户端都能连上来。客户端去问服务端「你有哪些工具」,服务端回一份带 JSON Schema 的清单,客户端把这份清单翻译成自己家模型能懂的格式。声明只写一次,适配由客户端负责。
打个比方。Function Calling 像你给每家打印机厂商单独写一份驱动;MCP 像 USB 标准,打印机按 USB 做,电脑按 USB 做,中间不用互相认识。你在 Java 里实现的是「打印机」那一侧。
需要说清的一点:MCP 不替代 Function Calling。模型这一层调用的仍然是 tool call,MCP 只是让工具清单和调用入口从应用内部挪到了独立进程。你写 MCP Server 的时候,业务代码不用改一行 model 相关的逻辑。
MCP 定义了三种原语:
- tools(工具):能执行动作、改变状态的,比如「下单」「退款」「查库存」。Java 后端用得最多的就是它。
- resources(资源):只读数据,按 URI 取,比如
order://202611170000123456。适合给模型当上下文,不适合触发业务动作。 - prompts(提示模板):服务端预置的提示词模板,客户端可以带参数取。
大部分场景只需要 tools。这篇文章的代码也只做 tools,resources 和 prompts 是同一个注解体系下的兄弟,用法一致。
谁在用 MCP:Claude Desktop、Cursor、VS Code、JetBrains 系 IDE,还有一堆自研 Agent 框架。这就是它的价值——你不是为某一个产品接一次,是为所有支持这个协议的东西接一次。
二、底层原理:MCP Server 是怎么被 AI 调起来的
MCP 的通信格式是 JSON-RPC 2.0,一次工具调用就是两条 JSON 消息的往返。理解这一点,后面所有配置项都不再是玄学。
2.1 两种传输方式,选错会很痛
stdio:客户端把你的服务当成子进程拉起来,通过标准输入输出收发 JSON-RPC 帧。本地 IDE、桌面客户端用这个。特点是零网络配置、天然隔离,缺点是只能本机用,而且你的程序绝对不能往 stdout 打日志——日志会和协议帧混在一起,客户端直接解析失败。
Streamable HTTP:服务端是个正常的 HTTP 服务,客户端 POST 到 /mcp,服务端可以用普通 JSON 回,也可以升级成 SSE 流式回。团队共享、多用户接入、放到内网给一堆 Agent 用,都是这个。旧版本有过「SSE + 独立 message 端点」的双端点方案,现在基本退场了。
Spring AI 的服务端配置里 protocol 有两个值:STREAMABLE 和 STATELESS,默认 STREAMABLE。区别在于要不要维持会话状态——STREAMABLE 会发 mcp-session-id 头,服务端记住这个会话;STATELESS 每条请求自带全部上下文,不记会话。单机随便选,多副本部署必须 STATELESS,不然请求被负载均衡打到另一台机器,会话就找不到了。
2.2 一次调用的完整链路
客户端连上来,按顺序干这几件事:
initialize:握手。客户端报协议版本和自己支持的能力,服务端回自己的名字、版本、能力清单。notifications/initialized:客户端确认,握手结束。tools/list:客户端问「你有哪些工具」。服务端返回工具名、描述、参数的 JSON Schema。tools/call:模型决定用某个工具后,客户端带着参数发过来,服务端执行,返回结果内容。
关键点在第四步:模型不直连你的服务器。链路是 模型 → 客户端程序 → 你的 MCP Server。客户端程序负责把工具清单塞进模型的上下文、解析模型吐出来的 tool call、转成 tools/call 发给你、再把结果回灌给模型。所以鉴权、限流、审计这些该做的事,一件都少不了。
2.3 Spring AI 帮你翻译了什么
手写 MCP Server 意味着自己拼 JSON Schema、自己分发方法名、自己序列化返回值。Spring AI 的做法是注解 + 自动配置,把这三件事包了:
| 你写的 Java | MCP 协议里的东西 |
|---|---|
@McpTool(name = "query_order_status") |
工具名 query_order_status |
@McpTool(description = "...") |
工具的 description,模型靠它判断该不该用 |
方法参数类型 + @McpToolParam |
inputSchema 的 JSON Schema |
| 方法返回值 | content 数组里的文本/结构化内容 |
| 方法抛异常 | isError: true + 错误文本 |
注解扫描器在 Bean 初始化阶段扫一遍容器里所有 Bean 的方法,凡是带 @McpTool 的都注册成工具。也就是说,你的工具类就是个普通的 @Component,能注入 Repository、能加 @Transactional、能读配置,跟你写 Service 没区别。
客户端那一侧反过来:spring-ai-starter-mcp-client 连上服务端,拉 tools/list,把每个工具包装成 Spring AI 的 ToolCallback,再通过 ToolCallbackProvider 交给 ChatClient。模型看到的还是普通的函数声明,它根本不知道背后是个 HTTP 服务。
三、实战:两个工程,一个提供工具一个用工具
服务端负责把订单查询暴露成 MCP 工具,客户端负责让模型调用它。分开写是因为真实项目里这两件事通常不在一个进程。
3.1 服务端依赖
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.1.2</version>
<relativePath/>
</parent>
<groupId>com.example</groupId>
<artifactId>order-mcp-server</artifactId>
<version>1.0.0</version>
<properties>
<java.version>21</java.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>2.0.2</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>4.1.2</version>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
<version>2.0.2</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>4.1.2</version>
</plugin>
</plugins>
</build>
</project>
spring-ai-starter-mcp-server-webmvc 是跑在 Spring MVC 上的 MCP 服务端。项目用 WebFlux 就换成 spring-ai-starter-mcp-server-webflux,代码不用动。
3.2 服务端配置
server:
port: 8080
spring:
ai:
mcp:
server:
name: order-mcp-server
version: 1.0.0
instructions: >-
内部订单查询工具。查单个订单用 query_order_status,
查某个用户最近的订单用 list_recent_orders。
所有时间返回 ISO-8601 格式字符串。
capabilities:
tool: true
streamable-http:
mcp-endpoint: /mcp
instructions 会随 initialize 一起下发给客户端,客户端通常会把它拼进系统提示词。这里写清楚「什么场景用哪个工具」,比在代码注释里写十行都有用。
3.3 工具类
package com.example.orders.mcp;
import org.springframework.ai.mcp.annotation.McpTool;
import org.springframework.ai.mcp.annotation.McpToolParam;
import org.springframework.stereotype.Component;
import java.util.List;
@Component
public class OrderTools {
private final OrderRepository repository;
public OrderTools(OrderRepository repository) {
this.repository = repository;
}
@McpTool(
name = "query_order_status",
description = """
按订单号查询订单当前状态、承运商和运单号。
用户问"我的订单到哪了""发货了吗""快递单号是多少"时调用。
订单号必须是 18 位纯数字,如果用户给的不够 18 位,先反问补全再调用。"""
)
public OrderStatus queryOrderStatus(
@McpToolParam(description = "18 位订单号,例如 202611170000123456", required = true)
String orderNo) {
return repository.findByOrderNo(orderNo)
.orElseThrow(() -> new IllegalArgumentException("订单不存在:" + orderNo));
}
@McpTool(
name = "list_recent_orders",
description = """
按用户手机号后四位查询该用户最近的订单列表,按下单时间倒序。
用户说"我最近买了什么""帮我看看这个月的单子"时调用。
结果最多 10 条,只要摘要字段,不含商品明细。"""
)
public List<OrderBrief> listRecentOrders(
@McpToolParam(description = "用户手机号的后四位数字", required = true)
String phoneSuffix,
@McpToolParam(description = "返回条数,1 到 10,默认 5", required = false)
Integer limit) {
int size = (limit == null) ? 5 : Math.max(1, Math.min(limit, 10));
return repository.findByPhoneSuffix(phoneSuffix, size);
}
}
三个细节值得说。
description 写的是什么时候用,不是「这个工具能干什么」。模型选工具靠的就是这段文本,写成「查询订单状态」这种功能描述,它不知道该在用户问「快递到哪了」时调用。把用户的原话写进去,命中率高得多。
参数描述里带格式约束。「18 位纯数字」这种话写在 description 里,模型会自己先校验再调用,少一次失败的往返。
返回值用 record。服务端会把 record 序列化成 JSON 塞进 content,同时生成 outputSchema,客户端能拿到结构化的结果,不用再解析文本。
配套的数据层,为了代码能直接跑,用内存实现:
package com.example.orders.mcp;
import org.springframework.stereotype.Repository;
import java.util.Comparator;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.ConcurrentHashMap;
@Repository
public class OrderRepository {
private final Map<String, OrderStatus> orders = new ConcurrentHashMap<>();
public OrderRepository() {
orders.put("202611170000123456", new OrderStatus(
"202611170000123456", "SHIPPED", "SF", "SF1234567890123",
"2026-11-15T09:20:00Z", "13800001234"));
orders.put("202611160000654321", new OrderStatus(
"202611160000654321", "DELIVERED", "JD", "JD9876543210987",
"2026-11-14T18:05:00Z", "13800001234"));
orders.put("202611120000777888", new OrderStatus(
"202611120000777888", "PAID", null, null,
"2026-11-12T11:42:00Z", "13800001234"));
}
public Optional<OrderStatus> findByOrderNo(String orderNo) {
return Optional.ofNullable(orders.get(orderNo));
}
public List<OrderBrief> findByPhoneSuffix(String phoneSuffix, int limit) {
return orders.values().stream()
.filter(o -> o.buyerPhone().endsWith(phoneSuffix))
.sorted(Comparator.comparing(OrderStatus::createdAt).reversed())
.limit(limit)
.map(o -> new OrderBrief(o.orderNo(), o.status(), o.carrier(), o.createdAt()))
.toList();
}
}
package com.example.orders.mcp;
public record OrderStatus(
String orderNo,
String status,
String carrier,
String trackingNo,
String createdAt,
String buyerPhone) {
}
package com.example.orders.mcp;
public record OrderBrief(
String orderNo,
String status,
String carrier,
String createdAt) {
}
注意两个 record 的分工:OrderStatus 带手机号,OrderBrief 不带。工具返回值是要进模型上下文的,能少给一个字段就少给一个。
3.4 启动类
package com.example.orders;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class OrderMcpServerApplication {
public static void main(String[] args) {
SpringApplication.run(OrderMcpServerApplication.class, args);
}
}
启动之后,POST http://localhost:8080/mcp 就是 MCP 端点。用官方 Inspector 最省事:
npx @modelcontextprotocol/inspector
在界面里选 Streamable HTTP,地址填 http://localhost:8080/mcp,点 Connect 就能看到 tools/list 返回的两个工具,也能直接填参数调一次。这一步跑通,说明服务端没问题,剩下的都是客户端的事。
3.5 客户端:让模型用上这些工具
客户端工程的依赖:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>2.0.2</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-client</artifactId>
<version>2.0.2</version>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
<version>2.0.2</version>
</dependency>
</dependencies>
父 POM 同样是 spring-boot-starter-parent 4.1.2,java.version 21。
配置:
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}
chat:
options:
model: gpt-4.1-mini
mcp:
client:
name: order-agent
version: 1.0.0
streamable-http:
connections:
order-server:
endpoint: http://localhost:8080/mcp
连接参数叫 endpoint,不叫 url。写错了不会报错,只会静默连不上,然后模型告诉你「我没有查询订单的工具」——排查半天。
配置就位后,MCP 客户端会把远端工具包装成 ToolCallbackProvider,把它塞给 ChatClient 即可:
package com.example.agent;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class AgentConfig {
@Bean
ChatClient chatClient(ChatClient.Builder builder, ToolCallbackProvider mcpTools) {
return builder
.defaultSystem("你是电商客服助手,查订单必须调用工具,不要凭空猜。")
.defaultToolCallbacks(mcpTools)
.build();
}
@Bean
CommandLineRunner demo(ChatClient chatClient) {
return args -> {
String answer = chatClient.prompt()
.user("我手机尾号 1234,最近买了什么东西?帮我看看发货了没")
.call()
.content();
System.out.println(answer);
};
}
}
启动客户端,模型会先调 list_recent_orders,拿到三条订单,其中一条状态是 SHIPPED,然后组织成一段人话回给你。整个过程中,客户端程序做的是转发,业务逻辑一行都没重写。
四、踩坑经验:上线后才暴露的六个问题
工具描述写得好不好,直接决定模型会不会用;剩下的坑基本都在「边界」上。
坑一:description 写成功能说明书。 「查询订单」这种写法模型不会主动选。要写触发场景,把用户可能说的话覆盖进去。我一般按「做什么 + 用户会怎么问 + 参数约束」三段写,参考上面 query_order_status 的写法。
坑二:返回值不设上限。 见过有人把「查询商品列表」直接返回 200 条记录的完整 JSON,一次工具调用吃掉一万多 token,模型后面的推理直接崩。工具返回是进上下文的,不是进数据库的。规则很简单:默认返回摘要字段,条数封顶 10 条,要明细就再开一个按 ID 查的工具。
坑三:默认超时 20 秒,长任务必挂。 服务端 spring.ai.mcp.server.request-timeout 默认 20 秒。导出报表、批量对账这种工具,20 秒根本不够,客户端拿到超时后模型会重试,重试再超时,最后给你一句「系统繁忙」。正确做法是拆成两段:一个工具提交任务返回 jobId,另一个工具按 jobId 查进度。模型自己有耐心轮询。
坑四:把 /mcp 当内网接口挂到公网。 MCP 端点本质是个「什么都能调的入口」。你的 refund_order、update_address 一旦包装成工具,任何拿到这个 URL 的客户端都能调。至少加一层 API Key 校验(Spring Security 的过滤器就行),管理类接口干脆别包装成工具。工具的权限边界要按「最坏情况」设计:这个工具被滥用一次,损失多大。
坑五:stdio 模式下往 stdout 打日志。 用 stdio 传输时,stdout 是协议通道。System.out.println 打个调试信息,客户端立刻解析失败,报错还告诉你「invalid JSON」。日志一律走 stderr,或者干脆用文件 appender。
坑六:多副本部署用了会话态。 默认 STREAMABLE 会维持会话,initialize 落在 A 机器,tools/call 被路由到 B 机器,B 不认识这个 session,直接 400。要么做会话粘滞,要么把 spring.ai.mcp.server.protocol 设成 stateless。后者更省心,代价是每条请求都要重新带能力协商信息,流量略大。
还有两类不值得单独开一节的:工具数量控制在 20 个以内(超过之后模型选错的概率明显上升,跟之前聊过的工具检索是同一个问题);工具名用下划线小写,别用驼峰,某些客户端会把名字当 URI 片段处理。
五、性能对比和技术选型
MCP 的固定开销很小,成本大头在你的业务接口本身。
| 方案 | 复用范围 | 接入成本 | 适合场景 |
|---|---|---|---|
| 各应用各写 Function Calling | 单应用 | 每接一个客户端写一遍 | 只有一个入口的临时脚本 |
| OpenAPI 文档转 MCP | 所有 MCP 客户端 | 需要转换工具 + 手调 schema | 已有完整 OpenAPI、接口稳定 |
| Spring AI 注解式 MCP Server | 所有 MCP 客户端 | 加注解即可,业务代码不动 | Java 后端,长期维护 |
工具描述的体积是要算进每次对话的,这笔开销固定发生。12 个工具、每个描述 100 字出头,tools/list 的响应体大概 4KB,换算成 token 一千上下,比一次 RAG 检索塞进去的内容还少——具体数字在 Inspector 里点开 tools/list 就能看到。所以工具不是越少越好,但每加一个都要问一句「模型真的会用到吗」。
选型上我的建议很直接:Java 后端已经有 Service 层,就用 Spring AI 的注解式方案,别去手写 JSON-RPC 分发。接口只有 OpenAPI 没有 Java 代码(比如老系统),用 OpenAPI 转 MCP 的工具生成一层壳。只有一个应用、只服务一个模型、短期不打算复用,那就老老实实写 Function Calling,别为了架构好看多搭一个进程。
真正需要提前想清楚的是权限和审计,不是协议选型。MCP 让「调用」变便宜了,也就让「误调用」变便宜了。
六、总结
MCP 的本质是把工具声明从应用里抽出来,变成一份所有 AI 客户端都能读的协议。它不改变模型怎么调工具,只改变工具清单从哪来。
落到 Java 上,你要做的只有三件事:写一个普通 @Component,方法上加 @McpTool 和写清楚触发场景的描述,配好 spring-ai-starter-mcp-server-webmvc 和端点。剩下的 JSON-RPC、schema 生成、会话管理,Spring AI 都替你做了。
几个判断可以直接拿走:
- 团队内部多个 AI 入口要查同一批数据 → 上 MCP,收益立刻体现。
- 只有一个机器人、只接一家模型 → 先别上,Function Calling 够了。
- 工具会改数据(退款、改地址、发消息)→ 先设计权限,再写工具。
- 多副本部署 →
stateless,别犹豫。
工具描述是这个技术栈里最容易被低估的部分。代码写对只完成了一半,模型选不选你的工具,全看那几十个字。
文 / 会编程的吕洞宾