不依赖 SpringAI 和其他重量级框架，采用轻量声明式方式即可启动。
本指南演示如何用 Java 快速构建符合 MCP（Model Context Protocol）的 Server，并通过 HTTP(SSE) 或 Stdio 暴露工具（Tools）与资源（Resources），供 LangChat Pro/Agent 在对话中按需调用。
- 协议兼容：兼容 MCP 标准，支持 Tools/Prompts/Resources 三类能力
- 双传输：一套代码同时支持 HTTP(SSE) 与 Stdio 启动
- 零侵入：通过注解声明能力，隐藏 MCP SDK 细节
- 易集成：与 LangChat Pro MCP 管理无缝对接
执行流程（高层）
在 langchat-mcp-server 模块下找到 mcp-server-filesystem，启动 McpSseServer.java 中的 main 函数：
启动 SSE 服务后，默认端口地址示例：http://localhost:8900/sse
在 LangChat 客户端平台中这样配置：
测试使用
本地启动服务后，示例 Tool 可访问本机指定目录的文件列表：
快速接入（最小代码）
只需在 main 方法中放入如下代码，即可在 Java 中快速启动 MCP Server：
import com.github.codeboyzhou.mcp.declarative.McpServers;
// 你可以使用这个注解来指定扫描MCP资源、提示和工具的基础包
// 这是可选的。如果未指定，它将扫描main方法所在的包
@McpComponentScan(basePackage = "com.github.codeboyzhou.mcp.server.examples")
public class MyMcpServer {
public static void main(String[] args) {
// 启动一个STDIO MCP服务器
McpServers.run(MyMcpServer.class, args).startSyncStdioServer(
McpServerInfo.builder().name("mcp-server").version("1.0.0").build()
);
// 或者启动一个HTTP SSE MCP服务器
McpServers.run(MyMcpServer.class, args).startSyncSseServer(
McpSseServerInfo.builder().name("mcp-server").version("1.0.0").port(8080).build()
);
// 或者使用yaml配置文件启动（兼容Spring AI框架）
McpServers.run(MyMcpServer.class, args).startServer();
// 或者使用特定的配置文件启动（兼容Spring AI框架）
McpServers.run(MyMcpServer.class, args).startServer("my-mcp-server.yml");
}
}
YAML 配置（可选）
当使用 startServer() 时，会读取默认 mcp-server.yml|yaml：
enabled: true
stdio: false
name: mcp-server
version: 1.0.0
instructions: mcp-server
request-timeout: 30000
type: SYNC
resource-change-notification: true
prompt-change-notification: true
tool-change-notification: true
sse-message-endpoint: /mcp/message
sse-endpoint: /sse
base-url: http://localhost:8080
sse-port: 8080
声明式开发（注解）
无需关心原生 MCP Java SDK 的底层细节，直接注解声明即可：
public class MyMcpResources {
// 这个方法定义了一个MCP资源来暴露操作系统环境变量
@McpResource(uri = "env://variables", description = "OS env variables")
public String getSystemEnv() {
// 只需在这里放入你的业务逻辑代码，忘记MCP SDK的细节
return System.getenv().toString();
}
// 在这里添加你的其他MCP资源...
}
public class MyMcpPrompts {
@McpPrompt(description = "A simple prompt to read a file")
public String readFile(
@McpPromptParam(name = "path", description = "filepath", required = true) String path) {
// 只需在这里放入你的业务逻辑代码，忘记MCP SDK的细节
return String.format("What is the complete contents of the file: %s", path);
}
}
public class MyMcpTools {
// 这个方法定义了一个MCP工具来读取文件
@McpTool(description = "Read complete file contents with UTF-8 encoding")
public String readFile(
@McpToolParam(name = "path", description = "filepath", required = true) String path) {
// 只需在这里放入你的业务逻辑代码，忘记MCP SDK的细节
return Files.readString(Path.of(path));
}
// 在这里添加你的其他MCP工具...
}
传输方式对比
| 维度 | HTTP(SSE) | Stdio |
|---|
| 部署形态 | 远程服务/容器/网关治理 | 本地进程/内网可信环境 |
| 网络要求 | 需 HTTP 通路与 SSE 支持 | 无网络要求（进程间） |
| 延迟 | 取决于网络与基础设施 | 延迟低、稳定 |
| 可观测性 | 易于接入网关与日志平台 | 需本地日志与监控接入 |
| 适用场景 | 云端服务、跨网络调用 | 内网私有化、低延迟调用 |
与 LangChat Pro 集成
- 在 LangChat Pro 的 MCP 管理中新增授权，选择 HTTP(SSE) 或 Stdio
- 同步 Tools 列表，校验描述/参数/错误码
- 在 Agent 中启用 MCP 能力，与 Function Call/插件等组合使用
最佳实践
- 安全治理：为 MCP Server 设置鉴权、速率限制；隔离敏感资源
- 错误规范：为 Tools 定义统一错误码/错误消息，便于模型处理
- 幂等设计：避免重复调用造成副作用，必要时引入重试与超时
- 可观测性：输出调用日志（耗时/失败率），便于问题定位与容量规划
- 契约稳定：保持工具命名、参数与返回结构的一致性与可演进性
故障排查（FAQ）
- Tools 列表拉取超时？
- SSE：检查 CORS/网关代理/心跳头；Stdio：检查命令可执行性与环境变量
- 能连通但工具不被调用？
- 检查 Agent 的提示词策略与工具优先级；确认工具输出结构与约定一致
- SSE 日志显示断流？
- 检查代理/负载均衡超时；对长连接开启心跳与重连机制
现在一切就绪，运行你的 MCP 服务器，选择你喜欢的 MCP 客户端，开始你的 MCP 探索之旅。
