MCP Java SDK实战：Client与Server双端集成核心解析

MCPModel Context Protocol这两年火得很快周边生态也已经从早期的“Python 独大”扩展到了 Java、Go、TypeScript 等主流语言。Java 生态里官方 SDK 的定位很明确让 JVM 系的应用能快速当一个 MCP Client去连接外部工具服务也能快速把一个内部能力包成一个 MCP Server供 AI 应用或其他客户端调用。这篇博文我按自己实际跑通的经验来写重点拆 MCP Java SDK 的 Client 和 Server 两端的核心功能它们解决什么问题、初始化流程长什么样、工具和资源是怎么暴露与发现的、双端联动怎么验证以及我踩过的几个比较典型的坑。适合刚接触 MCP、准备在 Java 项目里落地 AI 工具接入的开发者参考。1. MCP 与 Java SDK先搞清楚我们在集成什么1.1 没有 MCP 时AI 应用接入工具为什么这么痛苦在 MCP 出现之前一个 AI 应用想调用外部能力通常是一条“点对点”的集成路线你有一个大模型对话框架想加一个查数据库的能力那就写一段函数把这个函数注册进模型的工具列表再处理模型返回的参数调用请求。这本身不复杂复杂的是工具一多就乱了。比如我们有天气查询、内部订单查询、Git 仓库操作、监控告警查询这四组能力。如果没有统一协议每组能力都要定义一套参数格式、一套鉴权方式、一套调用约定。模型侧则要维护一个“越来越大的工具描述集合”每接一个新系统不仅要改调用代码还要重新设计工具的描述文本让模型能准确理解该调哪个、参数怎么填。MCP 想解决的核心问题是“把 AI 应用和工具之间的连接方式标准化”。它定义了一套 JSON-RPC 风格的消息格式约定 Client 和 Server 之间怎么握手、怎么发现能力、怎么调用工具、怎么传输资源。这样模型应用只需实现一个 MCP Client工具方只需实现一个 MCP Server两边通过协议对话而不是靠一堆散乱的内部 API。1.2 MCP 的 Client/Server 模型和 Java SDK 的定位MCP 的架构是典型的主从模式但这里的“主从”只体现在会话管理上两端在协议层面是平等的协商关系。MCP Server持有实际能力的一方。它能暴露三类东西——工具Tool、资源Resource、提示词模板Prompt。工具是用来被调用执行的资源是用来读取上下文信息的提示词模板是给模型用的语料片段。MCP Client连接 Server 的一方。它负责发起握手、拉取 Server 的能力清单、调用工具、读取资源并把结果交给上层 AI 应用。Java SDK 的价值是把这套协议封装成符合 Java 习惯的 API。你不用手工构造 JSON-RPC 报文、不用自己维护连接状态、也不用自己解析 Server 返回的 Content 块SDK 把这些都做了。而且接口有同步和异步两套风格Spring 环境里也有适配能力这对 Java 开发者的集成成本是个很实际的降低。1.3 SDK 在 JVM 场景下的适用边界使用 Java SDK 的项目大致有三类第一类是已有 AI 编排服务的后端应用。你有一个调度引擎需要让大模型去调用企业内部工具那么你在引擎层内嵌一个 MCP Client连接各个内部的 MCP Server就实现了工具统一接入。第二类是工具提供方。你想把自己维护的一套 API 暴露给模型用与其开发一个“专用模型接口”不如做一层 MCP Server 适配把现有服务包成标准协议谁都能连。第三类是本地开发调试工具。比如希望 CLI 工具能访问 MCP 生态里的服务通过 Java SDK 起一个 Client再配合标准输入输出传输方式就能把本地命令接到远端 Server 上。SDK 的适用范围不是只能做“AI 应用”它本质上是让任意 Java 进程具备 MCP 会话能力。所以如果你有一个中间件想接入 MCP 生态也可以直接用这套 SDK 完成协议层工作。2. 先啃 Client 端连接、发现、调用这条主线2.1 初始化与连接生命周期Client 端使用 SDK 时的第一件事是创建一个客户端实例。SDK 提供了同步 ClientSync和异步 ClientAsync两类核心入口。平时开发我建议先从同步接口入手因为它符合 Java 开发者对“方法调用返回结果”的直觉排查问题也简单。业务真正跑起来再评估是否需要异步换取更好的吞吐。创建同步 Client 的典型流程分为三步构造传输层配置指定 Server 的地址和通信方式构造 Client 配置设置协议版本、客户端标识、能力声明调用初始化连接完成握手。代码示意以实际引入版本的 API 为准McpClientConfig config McpClientConfig.builder() .clientInfo(new Implementation(demo-client, 1.0.0)) .transport(new HttpClientTransport(http://localhost:8080/mcp)) .build(); McpSyncClient client McpSyncClient.builder() .clientConfig(config) .build(); // 连接并完成协议握手 client.connect();这个connect()不是简单的 TCP 建连。对应 MCP 协议里的 initialize 请求Client 会告诉 Server“我是谁、我支持哪些能力”Server 会返回它的协议版本、Server 信息、以及它支持哪些能力。双方完成能力协商后连接才真正处于可用状态。断开连接时调用close()或closeGracefully()。前者立即关闭底层传输后者会先尝试把已发出的请求处理完适合优雅停机。这部分连接生命周期控制在误用线程池之后特别重要后面踩坑一节会详细说。2.2 能力协商与动态工具发现MCP 协议里有个很关键的机制是能力协商。初始化阶段Client 声明roots、sampling等能力Server 声明resources、tools、prompts等能力。协商完成之后双方才确认“这段会话里哪些功能是可用的”。客户端拿到 Server 能力之后需要主动拉取工具列表。这个动作对应 MCP 的tools/list请求SDK 里通常封装成类似listTools()的方法ListToolsResult tools client.listTools(); for (Tool tool : tools.tools()) { System.out.println(tool.name()); System.out.println(tool.description()); System.out.println(tool.inputSchema()); // JSON Schema告诉模型参数怎么填 }这一步要理解它的本质工具不是写死在代码里的而是运行时动态发现的。这意味着服务端可以随时加新工具客户端不用改代码重启后拉一次列表就能感知。这也是 MCP 相对“硬编码工具注册”的核心优势。调用工具走的是tools/call请求SDK 里用callTool(name, arguments)CallToolResult result client.callTool( getUser, Map.of(userId, u_12345) ); result.content().forEach(content - { // 拿到工具返回的文本、图片、资源链接 });这里有个容易忽略的细节arguments是一个MapString, Object它的结构必须和 Server 暴露的inputSchema吻合。如果参数类型对不上Server 端 JSON Schema 校验会直接报错。实际项目里我建议在调用前先拉一次工具列表把 Schema 传给模型做参考而不是写死参数结构——不然服务端稍微改个参数名客户端就直接断掉。2.3 同步、异步、阻塞式 API 的选择Java SDK 的 Client 除了McpSyncClient还有McpAsyncClient。两者的定位区别是同步接口内部会用阻塞方式等待响应适合请求量可控、链路要求直观的场景异步接口则基于CompletableFuture适合高并发、或者调用发起处不希望阻塞线程的场景。McpAsyncClient asyncClient McpAsyncClient.builder() .clientConfig(config) .build(); asyncClient.connect() .thenCompose(v - asyncClient.listTools()) .thenAccept(tools - System.out.println(tools.tools().size()));实际使用中我倾向于在异步接口外层保留一个同步门面而不是层层嵌套thenCompose。原因很简单MCP 调用链里除了协议请求外还有业务逻辑、鉴权、日志埋点等全链路异步会让出错的排查路径变得很隐晦。大多数 Java 后端项目的请求入口本身就是多线程模型同步阻塞一个业务线程换取的是清晰的调用链这在工具调用这种低频率、高单次代价的场景下是划算的。如果你的应用是用 Spring WebFlux 这类全响应式框架那就直接拥抱异步接口把CompletableFuture转换到响应式流里。2.4 Client 端的安全边界与鉴权开销MCP 协议本身没规定鉴权方式Java SDK 也不会替你拦截“谁在调用工具”。这意味着你在 Client 侧必须自己把控好安全边界。我遇到过的实际场景是内部一个数据查询服务接入 MCP 后所有能访问 Client 端接口的人理论上都能通过 Client 去调用 Server 端暴露的工具。如果 Server 端工具背后直接是数据库敏感表那这就变成了一个绕过业务权限体系的“后门”。务实做法分三层传输层安全远端传输必须走 HTTPS本地调试用 HTTP 也要限定监听地址接入层鉴权Client 与 Server 之间增加 Token 或 mTLS。Java SDK 的传输层一般支持自定义 Headers可以在启动时注入认证凭证工具级授权Server 端不要无脑暴露所有工具。至少做一个白名单机制根据调用方身份过滤可 List 的工具。// 传输层注入 token 的示意 HttpClientTransport transport HttpClientTransport.builder() .baseUrl(https://mcp.example.com/mcp) .headers(Map.of(Authorization, Bearer token)) .build();鉴权不是 MCP 特有的负担但协议标准化之后安全问题更容易被忽略。很多人以为“走协议就安全了”这是一个必须尽早打破的错觉。3. Server 端要做的事注册、暴露、回连3.1 工具注册从方法注解到协议消息Server 端最核心的工作是把 Java 方法暴露成 MCP 工具。SDK 里最直观的方式是用Tool注解。Tool(description 根据 userId 查询用户基础信息) public UserInfo getUser(ToolParam(description 用户ID) String userId) { // 业务实现 return userRepository.findById(userId); }这个注解的作用不只是标记方法。SDK 在启动时会对带Tool注解的方法做扫描通过反射提取方法名、描述、参数列表再结合参数上的ToolParam注解自动生成符合 JSON Schema 的工具定义。也就是说你写一个普通 Java 方法SDK 帮你把它变成了模型可感知、可调用的协议工具。这里有几个设计原则值得注意方法名就是工具名。模型调用时依赖这个名字做语义匹配所以名字要直观、且符合团队内部统一规范description不能写得太短。模型的工具选择很大程度依赖描述文本写“查询用户”就远不如写“根据内部统一用户ID查询用户基础信息常用于订单、权限模块的用户维度查询”效果好参数对象如果比较复杂可以定义一个 POJO 作为入参SDK 会按 POJO 的字段结构生成嵌套 JSON Schema比散列一堆 String 参数可读性好很多。工具注册后Server 启动时会自动完成协议侧的tools/list响应和tools/call分发。3.2 资源与提示词模板的暴露工具之外Server 还能暴露资源Resource和提示词模板Prompt。资源本质上是可读取的数据源比如文件内容、数据库查询结果、项目文档片段。它们不触发执行逻辑而是把“上下文”提供给客户端供模型理解某个主题。SDK 里资源一般通过注解或注册器暴露。McpResource(name current-user, description 当前登录用户信息, uri user://current) public String getUserResource() { return userSessionService.currentUserSummary(); }资源的 URI 是协议层定位资源的标识客户端通过resources/read请求读取。实际项目中可以把监控大盘的数据、灰度开关状态、配置中心内容这类“低变更、常需要”的信息作为资源暴露而不是做成工具。因为资源读取的语义是“给我看”而工具的语义是“帮我做”两者在模型侧的使用方式完全不同。提示词模板则是预定义的对话片段。它适合做分层 Prompt 管理比如把“代码评审规则”“SQL 生成规范”这类不常变化的指令文本放到 Server 端。客户端发起 prompts/get 请求拿到模板后填充变量再注入对话上下文。工具、资源、提示词模板是 Server 能力的三根支柱但大多数项目真正高频使用的还是工具。资源和提示词模板更适合作为进阶能力逐步引入不用一开始就全部铺开。3.3 Server 的日志、遥测与采样回连Server 端的运行观测是个容易被忽略的点。由于 MCP 协议链路是“模型应用 → Client → Server”一旦工具调用失败用户感知到的是模型回答“出错了”但问题可能出在 Server 端的方法异常、参数校验、依赖服务超时等环节。没有日志链路排查会非常痛苦。我的做法是在 Server 端每个Tool方法内至少记录三件事入参摘要、执行耗时、出参摘要。不需要额外的链路追踪组件先确保“哪个工具、什么参数、耗了多久”一目了然。Java SDK 在协议层面也支持日志/遥测透传。你可以在 Client 端上报请求耗时、错误码、重试次数等指标与 Server 端的执行日志在时间维度对齐就能大致还原一次调用在链路里的分布情况。3.4 采样回连机制Server 反向请求模型MCP 协议有个看起来很不起眼、但非常重要的能力叫Sampling采样它允许 Server 请求 Client 发起一次 LLM 补全。这就是“Server 反向调用模型”的机制。什么场景需要它典型的是一个专业领域的工具 Server 在处理请求时发现需要找模型做一次中间判断比如“这段用户输入属于哪个业务意图”。此时 Server 可以通过sampling/create请求把上下文和提示词发给 Client由 Client 调用它所连接的模型拿到补全结果后返回给 Server。在 Java SDK 里启用采样Client 初始化时要声明sampling能力并实现一个回调处理器。Server 端在部署服务时把采样回调传给某些工具方法业务代码里就能发起一次模型请求。// 示意Client 侧处理 Server 的采样请求 McpClientConfig config McpClientConfig.builder() .capabilities(new ClientCapabilities( null, null, new SamplingCapability())) .build(); // Server 侧工具内发起采样请求 CreateMessageRequest request new CreateMessageRequest( List.of(contentBlock, systemPrompt), new ModelPreferences(...)); CreateMessageResult result samplingClient.createMessage(request);Sampling 机制让 Server 不再只是一个“被动执行者”它可以借助模型能力完成轻量级决策。这个设计非常巧妙它避免了很多场景下“所有逻辑都要在模型侧做意图识别”的笨重做法。但代价是链路变长、延迟变高。我建议只在确实需要模型判断时使用而且要给采样调用设置超时和兜底策略不能因为模型没响应就把整个工具调用阻塞住。4. 双端联动典型集成落地与验证4.1 从零搭一个本地 MCP 服务讲了这么多原理我们实操一把。假设现在要做一个“内部用户查询”的 MCP Server暴露两个工具根据 userId 查用户、根据部门查用户列表。第一步引入 SDK 依赖搭建一个最小的 MCP Serverpublic class UserMcpServer { public static void main(String[] args) throws IOException { var registry new McpToolRegistry(); var server new UserTools(); // 包含 Tool 方法的实例 registry.register(server); McpServerConfig config McpServerConfig.builder() .serverInfo(new Implementation(user-server, 1.0.0)) .toolRegistry(registry) .build(); var transport new StdioServerTransport(); McpSyncServer mcpServer McpSyncServer.builder() .serverConfig(config) .transport(transport) .build(); mcpServer.start(); } }本地开发阶段用标准输入输出stdio作为传输是最省事的。模型应用通过子进程方式启动这个 Server双方在管道里交换 JSON-RPC 消息不需要处理端口、防火墙。如果要给远程调用则换成 HTTP 流式传输指定监听端口即可。4.2 用 Client 连接并调用服务的三种方式Server 跑起来之后我们用 Client 去连接。方式一同进程内连接。这是集成测试时最方便的方式Client 和 Server 都在一个 JVM 里不经过网络直接通过传输层对接。方式二stdio 方式连接。Client 以本地子进程方式启动 Server适合命令行工具或本地开发。方式三HTTP 方式连接。Server 部署在远端或者本地监听端口Client 通过 HTTP 连接。我用得最多的是第三种因为它在环境隔离和排障上最清晰——Server 独立部署Client 连接地址可配置出问题可以分别看两边日志。HttpClientTransport transport HttpClientTransport.builder() .baseUrl(http://127.0.0.1:8080/mcp) .build(); McpSyncClient client McpSyncClient.builder() .clientConfig(McpClientConfig.builder() .transport(transport) .build()) .build(); client.connect(); System.out.println(client.listTools().tools().size());有一个隐性要点连接成功后要先listTools()拿到工具定义再调用工具。很多初次接触的人会省略第一步直接callTool虽然也能调用但你没有拿到 Server 最新的 Schema遇到参数变更就直接懵了。规范的调用链一定是“连接 → 拉能力清单 → 按 Schema 构造参数 → 调用”。4.3 验证与监控如何判断调用走了协议层一个失败的工具调用可能断在四个环节Client 发起前、协议传输中、Server 执行中、结果回传中。所以验证要做分环节断言。冒烟测试阶段我习惯用一个最小验证脚本连接、拉工具列表、调用一个无副作用的工具比如echo或getCurrentTime确认全链路通了。再测试一个真正有业务逻辑的工具。监控方面有两个实用点协议报文抓包本地 HTTP 传输模式下可以用抓包工具看请求体里的 JSON-RPC 结构确认tools/call的 params 是否按预期组织Server 端日志埋点每个工具方法入参和耗时打点配合 Client 端调用耗时可以快速定位耗时在传输层还是在业务层。只要这两个观测点做好MCP 链路对普通开发来说就不再是黑盒。4.4 配置管理多环境连接信息怎么拆工具链一旦涉及多个环境开发、测试、生产连接管理就会成为实际痛点。我的建议是将 MCP Client 的连接信息当作普通的外部依赖配置来管理不要硬编码。用配置中心或环境变量维护以下内容Server 的 baseUrl传输类型stdio 还是 HTTP鉴权凭证连接超时、调用超时启动时是否自动连接。举例mcp: servers: user-server: base-url: ${MCP_USER_SERVER_URL} transport: http auth-token: ${MCP_USER_SERVER_TOKEN} connect-timeout: 5s call-timeout: 10s不同环境用不同的配置项注入既不会把测试环境的地址带到生产也能在同一条代码里适配多种连接拓扑。集成测试时用本地 Server 地址生产切到正式集群地址代码层面完全不用改。5. 我会踩的坑真实问题与排查思路5.1 协议版本与 SDK 版本强绑定MCP 协议还在快速演进中Java SDK 的版本与协议版本是强绑定的。不同版本的 SDK 初始化的默认协议版本可能不同如果 Client 和 Server 用的 SDK 版本差距过大可能出现握手失败或能力协商异常。现象一般表现为连接时报Unsupported protocol version或者连接成功了但listTools()返回空集合。排查链路抓初始化握手报文看 Client 发出去的protocolVersion和 Server 回应的版本检查两端 SDK 对应的协议版本范围确认是否有交集优先把两端 SDK 升级到一致版本。这个问题治本的办法是统一版本管理。MCP SDK 版本号应该在项目依赖锁文件里固定双端共用同一套 BOM 或版本目录不要各自引入不同小版本。5.2 线程模型与连接泄漏一个我实际遇到过的线上问题我在一个内部项目里把 MCP Server 集成到一个已有的 Spring Boot 应用中。服务刚上线时一切正常一周后开始出现连接超时、响应变慢。排查后发现是线程池被打满。原因不复杂SDK 的同步接口在等待协议响应时会占用调用线程而我的业务代码把多次工具调用放在了同一个同步块里且没有设置调用超时。当某个工具调用的底层接口响应变慢时一个慢调用就卡住了一个线程随着流量积压线程池被慢调用占满健康请求反而被饿死。处理方案有三个层面所有工具调用必须有明确超时不能依赖默认值或无限等待慢工具要隔离不要和快工具共用同一个线程池或调用通道连接数要与业务并发模型匹配。从我个人的经验看任何“连接不上”或“卡住没反应”的问题先检查三件事线程有没有泄漏、连接有没有超时、底层有没有慢调用。这三件事查完大部分问题都能定位。5.3 超时与重试默认策略不一定适合你Java SDK 的默认超时和重试策略通常是为通用场景设计的不一定适合你的业务。比如一个工具调用正常耗时只要 200ms但偶尔因为依赖抖动会到 3 秒。如果你不设置超时一个抖动就可能让调用线程挂住很久。反之如果一个工具本身平均耗时就需要 8 秒你把超时设成 1 秒那这个工具永远不会成功。这表明超时设置必须“一工具一策”。每个callTool调用最好针对该方法设定独立的超时时间而不是全局一套。重试也类似。协议层重试和业务层重试要区分开协议层重试连接失败、握手失败这类通道问题适合有限重试业务层重试工具方法内部因为依赖抖动失败而抛异常这个不该由 MCP 协议层重试而应该在业务层按幂等规则处理。我见到的一个典型反例有人在 Client 侧把callTool包了一个全局重试遇到超时就重试两遍。结果 Server 端的工具是“创建订单”这种非幂等操作一个慢响应被判定超时但 Server 侧实际创建成功了Client 侧又发起重试产生了一笔重复订单。在工具调用链路上默认不要乱加重试尤其不要在高风险操作上加。5.4 日志与调试技巧看到协议层实际交换MCP 调试的难点在于“两端都正常但合在一起就不对”。这时候最有效的手段是把协议层的实际消息打出来。我调试 MCP Java SDK 问题时通常会做两件事第一开启 SDK 的日志级别到DEBUG观察初始化请求的参数结构、工具定义的实际 JSON Schema 长什么样。这能快速发现序列化问题比如某个参数类型被序列化成了期望之外的结构。第二在 HTTP 模式下用工具抓包直接看 HTTP 请求体和响应体。如果请求能正常到达 Server 但返回异常问题大概率在 Server 工具方法的参数绑定或异常处理上。有一个高频问题值得单独说工具方法的返回值序列化失败。比如返回对象里有循环引用、有无法序列化的InputStream、或者有个LocalDateTime字段但序列化配置没适配。SDK 在把返回值转成协议 Content 块时如果遇到无法序列化的对象通常会抛异常或返回空内容。开发时一定要用真实对象做一次端到端测试不要只测简单字符串返回。6. 扩展玩法与边界6.1 从“单工具”到“工具网关”鉴权与多租户改造MCP Server 一旦多了就会自然想做一个统一网关对外是一个 MCP Server对内路由到多个业务服务。Java SDK 完全支持这种改造。核心思路是做一层工具转发器Server 扫描时注册的都是“代理工具”真正调用时根据参数里的路由字段从工具注册表中找到实际执行类并调用。多租户场景下每个租户的工具可见性可能不同。这时不要把工具清单写死而应当根据调用方身份动态生成工具列表。MCP 单次会话里Client 和 Server 是一对一的所以“租户身份”通常在连接初始化或请求 Header 里注入。Server 侧可以基于身份信息过滤工具注册表实现了“不同租户看到不同工具集合”的效果。6.2 拦截器与请求上下文的扩展Java SDK 一般会提供在请求链路上插入自定义逻辑的扩展点如拦截器、过滤器我强烈建议不要错过这个能力。拦截器适合做几类横向逻辑调用耗时统计和审计日志参数脱敏比如把请求里的密码字段提前打码权限二次校验灰度放量。这类逻辑如果写进每个Tool方法里代码会非常脏。放进拦截器后工具方法只关心业务实现横切逻辑统一处理整体可维护性提升非常明显。6.3 不只是 AI 应用MCP 的跨界用法回到标题的关键词“Client 和 Server 功能”其实这两端组合起来的能力边界远不止给大模型当工具这么窄。我见过一个有意思的用法把一个“配置查询服务”做成 MCP Server然后一个运维脚本通过 MCP Client 去读取配置。这样做的价值在于所有配置读取都走同一条协议链路统一了鉴权、审计、限流。配置系统本身并不知道自己在一个 MCP 生态里它只是暴露了资源。还有一个用法是把测试数据工厂包成 MCP Server测试框架通过 Client 在集成测试里动态造数。工具就是“创建用户”“创建订单”这些方法测试代码不用再写一坨工具类而是通过标准协议去调用测试数据和业务逻辑的耦合也被切断了。这些案例的共同点是当一套能力被标准化为可发现、可调用、可组合的协议接口之后消费方不一定是模型也可以是脚本、测试框架、运维工具。Java SDK 在这条路上最重要的价值就是让 JVM 生态的开发者能以最低的改造成本把自己的服务升级为可组合的协议节点。我自己的经验是第一次跑通 MCP 双端链路时最大的收获不是“AI 能调用工具了”而是理解了“标准化连接”这件事本身的价值。工具注册、资源暴露、采样回连这些设计每一条都是冲着“让系统之间以统一语言协作”去的。如果你正在做一个有多种消费者、需要动态扩展能力的服务MCP Java SDK 值得认真评估。