1. 两种传输方式Transport传输说明状态Streamable HTTP客户端发 HTTP 请求服务器返回常规响应或按需打开 SSE 流推荐stdio客户端把 MCP 服务器作为本地子进程启动通过标准输入/输出通信推荐HTTP/SSE旧版两个 URL一个启动 SSE 通道一个 POST 提交命令已弃用未来移除1.1 stdioMcpTransporttransportnewStdioMcpTransport.Builder().command(List.of(/usr/bin/npm,exec,modelcontextprotocol/server-everything0.6.2)).logEvents(true)// 是否在日志中打印流量.build();1.2 Streamable HTTPMcpTransporttransportnewStreamableHttpMcpTransport.Builder().url(http://localhost:3001/mcp).logRequests(true)// 打印请求.logResponses(true)// 打印响应.build();注意Streamable HTTP不会创建全局 SSE 流规范如此。依赖「服务器主动发起请求/通知」的功能可能失效若服务器把请求/通知附加在客户端发起操作时的 SSE 流中则仍可正常工作。1.3 旧版 HTTP/SSE弃用McpTransporttransportnewHttpMcpTransport.Builder().sseUrl(http://localhost:3001/sse)// POST 地址由服务器动态提供.logRequests(true).logResponses(true).build();2. MCP 客户端McpClientMcpClientmcpClientnewDefaultMcpClient.Builder().key(MyMCPClient)// 可选多个客户端时用于区分推荐设置.transport(transport).build();3. MCP 工具提供者McpToolProviderMcpToolProvidertoolProviderMcpToolProvider.builder().mcpClients(mcpClient).build();一个工具提供者可同时使用多个客户端。3.1 容错策略.builder().failIfOneServerFails(boolean)默认false某个服务器出错则忽略继续使用其他服务器。true任意服务器出错立即抛异常。3.2 工具过滤避免工具过多导致幻觉按名称过滤白名单McpToolProvidertoolProviderMcpToolProvider.builder().mcpClients(mcpClient).filterToolNames(get_issue,get_issue_comments,list_issues).build();更通用的BiPredicateMcpClient, ToolSpecification示例两个客户端都有echoInteger只保留numeric-mcp的McpToolProvidertoolProviderMcpToolProvider.builder().mcpClients(mcpClient1,mcpClient2).filter((mcpClient,tool)-!tool.name().startsWith(echoInteger)||mcpClient.key().equals(numeric-mcp)).build();同一 builder 上多次调用filter之间是AND关系。运行时可动态添加/移除客户端和过滤器。3.3 绑定到 AI 服务方式一绑定工具提供者BotbotAiServices.builder(Bot.class).chatModel(model).toolProvider(toolProvider).build();方式二直接提供工具映射MapToolSpecification,ToolExecutortoolsmcpClient.listTools().stream().collect(Collectors.toMap(tool-tool,tool-newMcpToolExecutor(mcpClient)));BotbotAiServices.builder(Bot.class).chatModel(model).tools(tools).build();4. 日志MCP 服务器可向客户端发送日志消息默认客户端把它们转成 SLF4J 日志。自定义需实现dev.langchain4j.mcp.client.logging.McpLogMessageHandlerMcpClientmcpClientnewDefaultMcpClient.Builder().transport(transport).logMessageHandler(newMyLogMessageHandler()).build();5. 资源Resources两种用法编程式访问与自动暴露为合成工具。5.1 编程式访问client.listResources();// 列出资源返回 McpResource含 URI 等元数据client.listResourceTemplates();// 列出资源模板返回 McpResourceTemplateclient.readResource(uri);// 读取资源返回 McpReadResourceResultreadResource返回内容列表McpResourceContents每条为McpBlobResourceContents二进制McpTextResourceContents文本5.2 自动暴露为合成工具构建McpToolProvider时设置McpResourcesAsToolsPresenter默认实现DefaultMcpResourcesAsToolsPresenter会自动增加两个工具list_resources列出所有资源get_resource读取指定资源内容需 MCP 服务器名 URI示例输出[{mcpServer:alice,uri:file:///info,uriTemplate:null,name:basicInfo,description:Basic information about Alice,mimeType:text/plain},{mcpServer:bob,uri:file:///info,uriTemplate:null,name:basicInfo,description:Basic information about Bob,mimeType:text/plain}]每个资源由(mcpServer, uri)唯一标识。合成工具描述可用DefaultMcpResourcesAsToolsPresenter.Builder自定义。6. 提示词Promptsclient.listPrompts();// - ListMcpPromptclient.getPrompt(name,arguments);// 渲染提示词内容一个提示词可能包含多条消息McpPromptMessage内容类型支持McpTextContentMcpImageContentMcpEmbeddedResourceMcpPromptMessage.toChatMessage()可转为通用ChatMessage但有两点限制角色为assistant且内容非文本 → 抛异常含二进制内容 → 无法转换7. 实战Docker 运行 GitHub MCP 服务器7.1 打包镜像dockerbuild-tmcp/github-fsrc/github/Dockerfile.dockerimagels# REPOSITORY TAG IMAGE ID SIZE# mcp/github latest b141704170b1 173MB实现来源GitHub MCP server源码在 MCP GitHub 仓库。7.2 通过 stdio 连接并总结最近提交publicstaticvoidmain(String[]args)throwsException{ChatModelmodelOpenAiChatModel.builder().apiKey(System.getenv(OPENAI_API_KEY)).modelName(gpt-4o-mini).logRequests(true).logResponses(true).build();McpTransporttransportnewStdioMcpTransport.Builder().command(List.of(/usr/local/bin/docker,run,-e,GITHUB_PERSONAL_ACCESS_TOKEN,-i,mcp/github)).logEvents(true).build();McpClientmcpClientnewDefaultMcpClient.Builder().transport(transport).build();ToolProvidertoolProviderMcpToolProvider.builder().mcpClients(List.of(mcpClient)).build();BotbotAiServices.builder(Bot.class).chatModel(model).toolProvider(toolProvider).build();try{Stringresponsebot.chat(Summarize the last 3 commits of the LangChain4j GitHub repository);System.out.println(RESPONSE: response);}finally{mcpClient.close();}}注意Token 通过环境变量GITHUB_PERSONAL_ACCESS_TOKEN传入公共仓库的部分操作可不需要。Docker 路径需按操作系统调整示例为/usr/local/bin/docker用 Podman 时替换为对应命令。7.3 运行效果输出示例Here are the summaries of the last three commits in the LangChain4j GitHub repository: 1. Commit 36951f9 (2025-02-05) by Dmytro Liubarskyi - Updated to upload-pages-artifactv3 2. Commit 6fcd19f (2025-02-05) by Dmytro Liubarskyi - Updated to checkoutv4, deploy-pagesv4, upload-pages-artifactv4 3. Commit 2e74049 (2025-02-05) by Dmytro Liubarskyi - Updated to setup-nodev4, configure-pagesv48. 不使用 AI 服务直接调用 MCP底层 API8.1 列出工具并驱动 ChatRequestListToolSpecificationtoolSpecificationsmcpClient.listTools();ChatRequestchatRequestChatRequest.builder().messages(UserMessage.from(What will the weather be like in London tomorrow?)).toolSpecifications(toolSpecifications).build();ChatResponseresponsechatModel.chat(chatRequest);AiMessageaiMessageresponse.aiMessage();if(aiMessage.hasToolExecutionRequests()){for(ToolExecutionRequestreq:aiMessage.toolExecutionRequests()){StringresultStringmcpClient.executeTool(req);ToolExecutionResultMessageresultMessageToolExecutionResultMessage.from(req.id(),req.name(),resultString);}}8.2 直接执行指定工具ToolExecutionRequestrequestToolExecutionRequest.builder().name(tool1).arguments({\a\: \b\}).build();StringtoolResultmcpClient.executeTool(request);9. 工具缓存DefaultMcpClient内部维护工具列表缓存默认首次获取后不再重复请求除非服务器发通知更新。手动清除mcpClient.evictToolListCache();构建时禁用缓存McpClientmcpClientnewDefaultMcpClient.Builder().key(MyMCPClient).transport(transport).cacheToolList(false).build();速查小结三类对象McpTransport通信→McpClient客户端可设 key/日志处理器/缓存→McpToolProvider工具提供者可多客户端 过滤 容错→ 绑定到AiServices。两个维度扩展资源编程式 / 合成工具list_resources、get_resource、提示词listPrompts/getPrompt。调试开关logEvents、logRequests、logResponses。常见坑Streamable HTTP 无全局 SSE工具过多要过滤工具列表有缓存需要时用evictToolListCache()或cacheToolList(false)。