Java MCP 实战：构建跨进程与远程的工具服务
一、MCP 协议简介
MCP（Model Context Protocol，模型上下文协议）是由Anthropic推出的一种开放标准协议，旨在为大语言模型（LLM）与外部数据源、工具和服务提供标准化、安全的集成方式。支持进程间（通过 stdio）和远程（通过 HTTP SSE/Streaming）通讯。它专为 AI 开发设计，可以方便地提供 Tool（工具服务）、Prompt（提示语服务）和 Resource（资源服务）三种原语内容。
MCP 的核心优势在于：
- 支持多种通讯方式（stdio/SSE/Streaming）
- 支持服务发现（客户端可查询服务端点提供的接口）
- 与 AI 生态无缝集成（可直接作为大模型的工具使用）
MCP 架构示意图：
二、环境准备
首先在项目中添加 Java MCP 关键依赖：
<dependency>
<groupId>org.noear</groupId>
<artifactId>solon-ai-mcp</artifactId>
<version>最新版本</version>
</dependency>
支持 java8, java11, java17, java21, java24 。支持 solon，springboot，vert.x，jFinal 等框架集成。完整的示例参考：
- https://gitee.com/solonlab/solon-ai-mcp-embedded-examples
- https://gitcode.com/solonlab/solon-ai-mcp-embedded-examples
- https://github.com/solonlab/solon-ai-mcp-embedded-examples
三、构建 MCP 服务端
1、最简单的 SSE 服务
@McpServerEndpoint(sseEndpoint = "/mcp/sse")
public class SimpleMcpServer {
@ToolMapping(description = "问候服务")
public String hello(@Param(name="name", description = "用户名") String name) {
return "你好, " + name;
}
}
public class App {
public static void main(String[] args) {
Solon.start(App.class, args);
}
}
2、多端点服务
// 金融工具服务
@McpServerEndpoint(name="finance-tools", sseEndpoint = "/finance/sse")
public class FinanceTools {
@ToolMapping(description = "计算复利")
public double compoundInterest(
@Param(description = "本金") double principal,
@Param(description = "年利率") double rate,
@Param(description = "年数") int years) {
return principal * Math.pow(1 + rate, years);
}
}
// 教育工具服务
@McpServerEndpoint(name="edu-tools", sseEndpoint = "/edu/sse")
public class EducationTools {
@ToolMapping(description = "生成数学题")
public String generateMathProblem(
@Param(description = "难度级别") String level) {
if("easy".equals(level)) {
return "3 + 5 = ?";
} else {
return "∫(x^2)dx from 0 to 1 = ?";
}
}
}
3、动态管理工具
@Controller
public class ToolManager {
@Inject("finance-tools")
McpServerEndpointProvider financeEndpoint;
@Mapping("/tool/add")
public void addTool() {
financeEndpoint.addTool(new FunctionToolDesc("calculateTax")
.doHandle(params -> {
double income = (double)params.get("income");
return income * 0.2; // 简单计算20%税
}));
financeEndpoint.notifyToolsListChanged();
}
@Mapping("/tool/remove")
public void removeTool() {
financeEndpoint.removeTool("calculateTax");
financeEndpoint.notifyToolsListChanged();
}
}
4、STDIO 服务
@McpServerEndpoint(channel = McpChannel.STDIO)
public class StdioCalculator {
@ToolMapping(description = "加法计算")
public int add(@Param int a, @Param int b) {
return a + b;
}
@ToolMapping(description = "减法计算")
public int subtract(@Param int a, @Param int b) {
return a - b;
}
}
注意：STDIO 服务不能开启控制台日志，否则会污染协议流。
四、构建 MCP 客户端
1、基本客户端调用
public class McpClientDemo {
public static void main(String[] args) {
// 连接SSE服务
McpClientToolProvider sseClient = McpClientToolProvider.builder()
.apiUrl("http://localhost:8080/mcp/sse")
.build();
String greeting = sseClient.callToolAsText("hello", Map.of("name", "张三"));
System.out.println(greeting);
// 连接STDIO服务
McpClientToolProvider stdioClient = McpClientToolProvider.builder()
.channel(McpChannel.STDIO)
.serverParameters(McpServerParameters.builder("java")
.args("-jar", "path/to/stdio-service.jar")
.build())
.build();
int sum = stdioClient.callToolAsText("add", Map.of("a", 5, "b", 3));
System.out.println("5 + 3 = " + sum);
}
}
2、集成到AI模型
@Configuration
public class AiConfig {
@Bean
public ChatModel chatModel(
@Inject("${solon.ai.chat.config}") ChatConfig chatConfig,
@Inject("mcp-weather") McpClientToolProvider toolProvider) {
return ChatModel.of(chatConfig)
.defaultToolsAdd(toolProvider.getTools())
.build();
}
@Bean("mcp-weather")
public McpClientToolProvider weatherToolProvider() {
return McpClientToolProvider.builder()
.apiUrl("http://weather-service/mcp/sse")
.build();
}
}
@Service
public class WeatherService {
@Inject
ChatModel chatModel;
public String askWeather(String question) {
ChatResponse response = chatModel.prompt(question).call();
return response.getContent();
}
}
五、高级特性
1、三种原语内容
@McpServerEndpoint(sseEndpoint = "/mcp/sse")
public class FullFeatureServer {
// 工具服务
@ToolMapping(description = "汇率转换")
public double exchangeRate(
@Param(description = "源货币") String from,
@Param(description = "目标货币") String to) {
// 实现汇率转换逻辑
return 6.5;
}
// 资源服务
@ResourceMapping(uri = "config://app-info",
description = "获取应用信息")
public String getAppInfo() {
return "AppName: WeatherService, Version: 1.0.0";
}
// 提示语服务
@PromptMapping(description = "生成天气报告提示")
public Collection<ChatMessage> weatherReportPrompt(
@Param(description = "城市名称") String city) {
return Arrays.asList(
ChatMessage.ofSystem("你是一个天气报告助手"),
ChatMessage.ofUser("请生成" + city + "的天气报告")
);
}
}
2、代理模式
// 将STDIO服务代理为SSE服务
@McpServerEndpoint(sseEndpoint = "/proxy/sse")
public class StdioToSseProxy implements ToolProvider {
private McpClientProvider stdioClient = McpClientProvider.builder()
.channel(McpChannel.STDIO)
.serverParameters(ServerParameters.builder("java")
.args("-jar", "path/to/stdio-service.jar")
.build())
.build();
@Override
public Collection<FunctionTool> getTools() {
return stdioClient.getTools();
}
}
// 将SSE服务代理为STDIO服务
@McpServerEndpoint(channel = McpChannel.STDIO)
public class SseToStdioProxy implements ToolProvider {
private McpClientProvider sseClient = McpClientProvider.builder()
.apiUrl("http://remote-service/mcp/sse")
.build();
@Override
public Collection<FunctionTool> getTools() {
return sseClient.getTools();
}
}
3、与Web API互通
@Controller
@McpServerEndpoint(sseEndpoint = "/mcp/sse")
public class HybridService {
// 同时作为Web API和MCP工具
@ToolMapping(description = "查询库存")
@Mapping("/api/inventory")
public int getInventory(
@Param(description = "产品ID") String productId,
@Header("Authorization") String auth) {
// 验证逻辑...
return 100; // 示例库存
}
// 纯Web API
@Mapping("/api/info")
public String getInfo() {
return "Service Info";
}
// 纯MCP工具
@ToolMapping(description = "计算折扣")
public double calculateDiscount(
@Param(description = "原价") double price,
@Param(description = "会员等级") String level) {
if("VIP".equals(level)) {
return price * 0.8;
}
return price;
}
}
六、生产环境注意事项
1、鉴权设计：使用过滤器保护MCP端点
@Component
public class McpAuthFilter implements Filter {
@Override
public void doFilter(Context ctx, FilterChain chain) throws Throwable {
if (ctx.pathNew().startsWith("/mcp/")) {
String apiKey = ctx.header("X-API-KEY");
if(!validateApiKey(apiKey)) {
ctx.status(401);
return;
}
}
chain.doFilter(ctx);
}
}
2、客户端配置
McpClientToolProvider.builder()
.apiUrl("http://service/mcp/sse")
.apiKey("your-api-key")
.httpTimeout(HttpTimeout.builder()
.connectTimeout(Duration.ofSeconds(5))
.readTimeout(Duration.ofSeconds(30))
.build())
.requestTimeout(Duration.ofSeconds(20))
.build();
3、断线重连：客户端默认支持断线重连，可通过心跳机制保持连接
@McpServerEndpoint(sseEndpoint = "/mcp/sse", heartbeatInterval = "60s")
public class HeartbeatService {
// ...
}
七、总结
通过本文，我们学习了如何使用 Java 和 Solon MCP 构建强大的工具服务：
- 可以创建多种类型的服务端点（SSE/STDIO）
- 支持动态添加和移除工具
- 可与 Web API 无缝集成
- 支持代理模式实现协议转换
- 提供完整的鉴权和配置方案
MCP 协议特别适合需要与 AI 系统集成的场景，能够将现有服务快速暴露给大模型使用，同时也支持传统的程序间调用。其灵活的通讯方式（进程内/远程）和原语支持（工具/提示/资源）使其成为构建现代分布式系统的有力工具。
在实际项目中，可以根据需求选择 SSE 或 STDIO 通讯方式，或者结合两者使用代理模式。对于需要与 AI 集成的场景，MCP 提供的工具服务描述机制能够大大简化集成工作。
