：Client與Server雙端集成核心解析)
MCPModel Context Protocol這兩年火得很快周邊生態(tài)也已經(jīng)從早期的“Python 獨(dú)大”擴(kuò)展到了 Java、Go、TypeScript 等主流語言。Java 生態(tài)里官方 SDK 的定位很明確讓 JVM 系的應(yīng)用能快速當(dāng)一個 MCP Client去連接外部工具服務(wù)也能快速把一個內(nèi)部能力包成一個 MCP Server供 AI 應(yīng)用或其他客戶端調(diào)用。這篇博文我按自己實際跑通的經(jīng)驗來寫重點(diǎn)拆 MCP Java SDK 的 Client 和 Server 兩端的核心功能它們解決什么問題、初始化流程長什么樣、工具和資源是怎么暴露與發(fā)現(xiàn)的、雙端聯(lián)動怎么驗證以及我踩過的幾個比較典型的坑。適合剛接觸 MCP、準(zhǔn)備在 Java 項目里落地 AI 工具接入的開發(fā)者參考。1. MCP 與 Java SDK先搞清楚我們在集成什么1.1 沒有 MCP 時AI 應(yīng)用接入工具為什么這么痛苦在 MCP 出現(xiàn)之前一個 AI 應(yīng)用想調(diào)用外部能力通常是一條“點(diǎn)對點(diǎn)”的集成路線你有一個大模型對話框架想加一個查數(shù)據(jù)庫的能力那就寫一段函數(shù)把這個函數(shù)注冊進(jìn)模型的工具列表再處理模型返回的參數(shù)調(diào)用請求。這本身不復(fù)雜復(fù)雜的是工具一多就亂了。比如我們有天氣查詢、內(nèi)部訂單查詢、Git 倉庫操作、監(jiān)控告警查詢這四組能力。如果沒有統(tǒng)一協(xié)議每組能力都要定義一套參數(shù)格式、一套鑒權(quán)方式、一套調(diào)用約定。模型側(cè)則要維護(hù)一個“越來越大的工具描述集合”每接一個新系統(tǒng)不僅要改調(diào)用代碼還要重新設(shè)計工具的描述文本讓模型能準(zhǔn)確理解該調(diào)哪個、參數(shù)怎么填。MCP 想解決的核心問題是“把 AI 應(yīng)用和工具之間的連接方式標(biāo)準(zhǔn)化”。它定義了一套 JSON-RPC 風(fēng)格的消息格式約定 Client 和 Server 之間怎么握手、怎么發(fā)現(xiàn)能力、怎么調(diào)用工具、怎么傳輸資源。這樣模型應(yīng)用只需實現(xiàn)一個 MCP Client工具方只需實現(xiàn)一個 MCP Server兩邊通過協(xié)議對話而不是靠一堆散亂的內(nèi)部 API。1.2 MCP 的 Client/Server 模型和 Java SDK 的定位MCP 的架構(gòu)是典型的主從模式但這里的“主從”只體現(xiàn)在會話管理上兩端在協(xié)議層面是平等的協(xié)商關(guān)系。MCP Server持有實際能力的一方。它能暴露三類東西——工具Tool、資源Resource、提示詞模板Prompt。工具是用來被調(diào)用執(zhí)行的資源是用來讀取上下文信息的提示詞模板是給模型用的語料片段。MCP Client連接 Server 的一方。它負(fù)責(zé)發(fā)起握手、拉取 Server 的能力清單、調(diào)用工具、讀取資源并把結(jié)果交給上層 AI 應(yīng)用。Java SDK 的價值是把這套協(xié)議封裝成符合 Java 習(xí)慣的 API。你不用手工構(gòu)造 JSON-RPC 報文、不用自己維護(hù)連接狀態(tài)、也不用自己解析 Server 返回的 Content 塊SDK 把這些都做了。而且接口有同步和異步兩套風(fēng)格Spring 環(huán)境里也有適配能力這對 Java 開發(fā)者的集成成本是個很實際的降低。1.3 SDK 在 JVM 場景下的適用邊界使用 Java SDK 的項目大致有三類第一類是已有 AI 編排服務(wù)的后端應(yīng)用。你有一個調(diào)度引擎需要讓大模型去調(diào)用企業(yè)內(nèi)部工具那么你在引擎層內(nèi)嵌一個 MCP Client連接各個內(nèi)部的 MCP Server就實現(xiàn)了工具統(tǒng)一接入。第二類是工具提供方。你想把自己維護(hù)的一套 API 暴露給模型用與其開發(fā)一個“專用模型接口”不如做一層 MCP Server 適配把現(xiàn)有服務(wù)包成標(biāo)準(zhǔn)協(xié)議誰都能連。第三類是本地開發(fā)調(diào)試工具。比如希望 CLI 工具能訪問 MCP 生態(tài)里的服務(wù)通過 Java SDK 起一個 Client再配合標(biāo)準(zhǔn)輸入輸出傳輸方式就能把本地命令接到遠(yuǎn)端 Server 上。SDK 的適用范圍不是只能做“AI 應(yīng)用”它本質(zhì)上是讓任意 Java 進(jìn)程具備 MCP 會話能力。所以如果你有一個中間件想接入 MCP 生態(tài)也可以直接用這套 SDK 完成協(xié)議層工作。2. 先啃 Client 端連接、發(fā)現(xiàn)、調(diào)用這條主線2.1 初始化與連接生命周期Client 端使用 SDK 時的第一件事是創(chuàng)建一個客戶端實例。SDK 提供了同步 ClientSync和異步 ClientAsync兩類核心入口。平時開發(fā)我建議先從同步接口入手因為它符合 Java 開發(fā)者對“方法調(diào)用返回結(jié)果”的直覺排查問題也簡單。業(yè)務(wù)真正跑起來再評估是否需要異步換取更好的吞吐。創(chuàng)建同步 Client 的典型流程分為三步構(gòu)造傳輸層配置指定 Server 的地址和通信方式構(gòu)造 Client 配置設(shè)置協(xié)議版本、客戶端標(biāo)識、能力聲明調(diào)用初始化連接完成握手。代碼示意以實際引入版本的 API 為準(zhǔn)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(); // 連接并完成協(xié)議握手 client.connect();這個connect()不是簡單的 TCP 建連。對應(yīng) MCP 協(xié)議里的 initialize 請求Client 會告訴 Server“我是誰、我支持哪些能力”Server 會返回它的協(xié)議版本、Server 信息、以及它支持哪些能力。雙方完成能力協(xié)商后連接才真正處于可用狀態(tài)。斷開連接時調(diào)用close()或closeGracefully()。前者立即關(guān)閉底層傳輸后者會先嘗試把已發(fā)出的請求處理完適合優(yōu)雅停機(jī)。這部分連接生命周期控制在誤用線程池之后特別重要后面踩坑一節(jié)會詳細(xì)說。2.2 能力協(xié)商與動態(tài)工具發(fā)現(xiàn)MCP 協(xié)議里有個很關(guān)鍵的機(jī)制是能力協(xié)商。初始化階段Client 聲明roots、sampling等能力Server 聲明resources、tools、prompts等能力。協(xié)商完成之后雙方才確認(rèn)“這段會話里哪些功能是可用的”?？蛻舳四玫?Server 能力之后需要主動拉取工具列表。這個動作對應(yīng) 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告訴模型參數(shù)怎么填 }這一步要理解它的本質(zhì)工具不是寫死在代碼里的而是運(yùn)行時動態(tài)發(fā)現(xiàn)的。這意味著服務(wù)端可以隨時加新工具客戶端不用改代碼重啟后拉一次列表就能感知。這也是 MCP 相對“硬編碼工具注冊”的核心優(yōu)勢。調(diào)用工具走的是tools/call請求SDK 里用callTool(name, arguments)CallToolResult result client.callTool( getUser, Map.of(userId, u_12345) ); result.content().forEach(content - { // 拿到工具返回的文本、圖片、資源鏈接 });這里有個容易忽略的細(xì)節(jié)arguments是一個MapString, Object它的結(jié)構(gòu)必須和 Server 暴露的inputSchema吻合。如果參數(shù)類型對不上Server 端 JSON Schema 校驗會直接報錯。實際項目里我建議在調(diào)用前先拉一次工具列表把 Schema 傳給模型做參考而不是寫死參數(shù)結(jié)構(gòu)——不然服務(wù)端稍微改個參數(shù)名客戶端就直接斷掉。2.3 同步、異步、阻塞式 API 的選擇Java SDK 的 Client 除了McpSyncClient還有McpAsyncClient。兩者的定位區(qū)別是同步接口內(nèi)部會用阻塞方式等待響應(yīng)適合請求量可控、鏈路要求直觀的場景異步接口則基于CompletableFuture適合高并發(fā)、或者調(diào)用發(fā)起處不希望阻塞線程的場景。McpAsyncClient asyncClient McpAsyncClient.builder() .clientConfig(config) .build(); asyncClient.connect() .thenCompose(v - asyncClient.listTools()) .thenAccept(tools - System.out.println(tools.tools().size()));實際使用中我傾向于在異步接口外層保留一個同步門面而不是層層嵌套thenCompose。原因很簡單MCP 調(diào)用鏈里除了協(xié)議請求外還有業(yè)務(wù)邏輯、鑒權(quán)、日志埋點(diǎn)等全鏈路異步會讓出錯的排查路徑變得很隱晦。大多數(shù) Java 后端項目的請求入口本身就是多線程模型同步阻塞一個業(yè)務(wù)線程換取的是清晰的調(diào)用鏈這在工具調(diào)用這種低頻率、高單次代價的場景下是劃算的。如果你的應(yīng)用是用 Spring WebFlux 這類全響應(yīng)式框架那就直接擁抱異步接口把CompletableFuture轉(zhuǎn)換到響應(yīng)式流里。2.4 Client 端的安全邊界與鑒權(quán)開銷MCP 協(xié)議本身沒規(guī)定鑒權(quán)方式Java SDK 也不會替你攔截“誰在調(diào)用工具”。這意味著你在 Client 側(cè)必須自己把控好安全邊界。我遇到過的實際場景是內(nèi)部一個數(shù)據(jù)查詢服務(wù)接入 MCP 后所有能訪問 Client 端接口的人理論上都能通過 Client 去調(diào)用 Server 端暴露的工具。如果 Server 端工具背后直接是數(shù)據(jù)庫敏感表那這就變成了一個繞過業(yè)務(wù)權(quán)限體系的“后門”。務(wù)實做法分三層傳輸層安全遠(yuǎn)端傳輸必須走 HTTPS本地調(diào)試用 HTTP 也要限定監(jiān)聽地址接入層鑒權(quán)Client 與 Server 之間增加 Token 或 mTLS。Java SDK 的傳輸層一般支持自定義 Headers可以在啟動時注入認(rèn)證憑證工具級授權(quán)Server 端不要無腦暴露所有工具。至少做一個白名單機(jī)制根據(jù)調(diào)用方身份過濾可 List 的工具。// 傳輸層注入 token 的示意 HttpClientTransport transport HttpClientTransport.builder() .baseUrl(https://mcp.example.com/mcp) .headers(Map.of(Authorization, Bearer token)) .build();鑒權(quán)不是 MCP 特有的負(fù)擔(dān)但協(xié)議標(biāo)準(zhǔn)化之后安全問題更容易被忽略。很多人以為“走協(xié)議就安全了”這是一個必須盡早打破的錯覺。3. Server 端要做的事注冊、暴露、回連3.1 工具注冊從方法注解到協(xié)議消息Server 端最核心的工作是把 Java 方法暴露成 MCP 工具。SDK 里最直觀的方式是用Tool注解。Tool(description 根據(jù) userId 查詢用戶基礎(chǔ)信息) public UserInfo getUser(ToolParam(description 用戶ID) String userId) { // 業(yè)務(wù)實現(xiàn) return userRepository.findById(userId); }這個注解的作用不只是標(biāo)記方法。SDK 在啟動時會對帶Tool注解的方法做掃描通過反射提取方法名、描述、參數(shù)列表再結(jié)合參數(shù)上的ToolParam注解自動生成符合 JSON Schema 的工具定義。也就是說你寫一個普通 Java 方法SDK 幫你把它變成了模型可感知、可調(diào)用的協(xié)議工具。這里有幾個設(shè)計原則值得注意方法名就是工具名。模型調(diào)用時依賴這個名字做語義匹配所以名字要直觀、且符合團(tuán)隊內(nèi)部統(tǒng)一規(guī)范description不能寫得太短。模型的工具選擇很大程度依賴描述文本寫“查詢用戶”就遠(yuǎn)不如寫“根據(jù)內(nèi)部統(tǒng)一用戶ID查詢用戶基礎(chǔ)信息常用于訂單、權(quán)限模塊的用戶維度查詢”效果好參數(shù)對象如果比較復(fù)雜可以定義一個 POJO 作為入?yún)DK 會按 POJO 的字段結(jié)構(gòu)生成嵌套 JSON Schema比散列一堆 String 參數(shù)可讀性好很多。工具注冊后Server 啟動時會自動完成協(xié)議側(cè)的tools/list響應(yīng)和tools/call分發(fā)。3.2 資源與提示詞模板的暴露工具之外Server 還能暴露資源Resource和提示詞模板Prompt。資源本質(zhì)上是可讀取的數(shù)據(jù)源比如文件內(nèi)容、數(shù)據(jù)庫查詢結(jié)果、項目文檔片段。它們不觸發(fā)執(zhí)行邏輯而是把“上下文”提供給客戶端供模型理解某個主題。SDK 里資源一般通過注解或注冊器暴露。McpResource(name current-user, description 當(dāng)前登錄用戶信息, uri user://current) public String getUserResource() { return userSessionService.currentUserSummary(); }資源的 URI 是協(xié)議層定位資源的標(biāo)識客戶端通過resources/read請求讀取。實際項目中可以把監(jiān)控大盤的數(shù)據(jù)、灰度開關(guān)狀態(tài)、配置中心內(nèi)容這類“低變更、常需要”的信息作為資源暴露而不是做成工具。因為資源讀取的語義是“給我看”而工具的語義是“幫我做”兩者在模型側(cè)的使用方式完全不同。提示詞模板則是預(yù)定義的對話片段。它適合做分層 Prompt 管理比如把“代碼評審規(guī)則”“SQL 生成規(guī)范”這類不常變化的指令文本放到 Server 端。客戶端發(fā)起 prompts/get 請求拿到模板后填充變量再注入對話上下文。工具、資源、提示詞模板是 Server 能力的三根支柱但大多數(shù)項目真正高頻使用的還是工具。資源和提示詞模板更適合作為進(jìn)階能力逐步引入不用一開始就全部鋪開。3.3 Server 的日志、遙測與采樣回連Server 端的運(yùn)行觀測是個容易被忽略的點(diǎn)。由于 MCP 協(xié)議鏈路是“模型應(yīng)用 → Client → Server”一旦工具調(diào)用失敗用戶感知到的是模型回答“出錯了”但問題可能出在 Server 端的方法異常、參數(shù)校驗、依賴服務(wù)超時等環(huán)節(jié)。沒有日志鏈路排查會非常痛苦。我的做法是在 Server 端每個Tool方法內(nèi)至少記錄三件事入?yún)⒄?、?zhí)行耗時、出參摘要。不需要額外的鏈路追蹤組件先確?！澳膫€工具、什么參數(shù)、耗了多久”一目了然。Java SDK 在協(xié)議層面也支持日志/遙測透傳。你可以在 Client 端上報請求耗時、錯誤碼、重試次數(shù)等指標(biāo)與 Server 端的執(zhí)行日志在時間維度對齊就能大致還原一次調(diào)用在鏈路里的分布情況。3.4 采樣回連機(jī)制Server 反向請求模型MCP 協(xié)議有個看起來很不起眼、但非常重要的能力叫Sampling采樣它允許 Server 請求 Client 發(fā)起一次 LLM 補(bǔ)全。這就是“Server 反向調(diào)用模型”的機(jī)制。什么場景需要它典型的是一個專業(yè)領(lǐng)域的工具 Server 在處理請求時發(fā)現(xiàn)需要找模型做一次中間判斷比如“這段用戶輸入屬于哪個業(yè)務(wù)意圖”。此時 Server 可以通過sampling/create請求把上下文和提示詞發(fā)給 Client由 Client 調(diào)用它所連接的模型拿到補(bǔ)全結(jié)果后返回給 Server。在 Java SDK 里啟用采樣Client 初始化時要聲明sampling能力并實現(xiàn)一個回調(diào)處理器。Server 端在部署服務(wù)時把采樣回調(diào)傳給某些工具方法業(yè)務(wù)代碼里就能發(fā)起一次模型請求。// 示意Client 側(cè)處理 Server 的采樣請求 McpClientConfig config McpClientConfig.builder() .capabilities(new ClientCapabilities( null, null, new SamplingCapability())) .build(); // Server 側(cè)工具內(nèi)發(fā)起采樣請求 CreateMessageRequest request new CreateMessageRequest( List.of(contentBlock, systemPrompt), new ModelPreferences(...)); CreateMessageResult result samplingClient.createMessage(request);Sampling 機(jī)制讓 Server 不再只是一個“被動執(zhí)行者”它可以借助模型能力完成輕量級決策。這個設(shè)計非常巧妙它避免了很多場景下“所有邏輯都要在模型側(cè)做意圖識別”的笨重做法。但代價是鏈路變長、延遲變高。我建議只在確實需要模型判斷時使用而且要給采樣調(diào)用設(shè)置超時和兜底策略不能因為模型沒響應(yīng)就把整個工具調(diào)用阻塞住。4. 雙端聯(lián)動典型集成落地與驗證4.1 從零搭一個本地 MCP 服務(wù)講了這么多原理我們實操一把。假設(shè)現(xiàn)在要做一個“內(nèi)部用戶查詢”的 MCP Server暴露兩個工具根據(jù) userId 查用戶、根據(jù)部門查用戶列表。第一步引入 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(); } }本地開發(fā)階段用標(biāo)準(zhǔn)輸入輸出stdio作為傳輸是最省事的。模型應(yīng)用通過子進(jìn)程方式啟動這個 Server雙方在管道里交換 JSON-RPC 消息不需要處理端口、防火墻。如果要給遠(yuǎn)程調(diào)用則換成 HTTP 流式傳輸指定監(jiān)聽端口即可。4.2 用 Client 連接并調(diào)用服務(wù)的三種方式Server 跑起來之后我們用 Client 去連接。方式一同進(jìn)程內(nèi)連接。這是集成測試時最方便的方式Client 和 Server 都在一個 JVM 里不經(jīng)過網(wǎng)絡(luò)直接通過傳輸層對接。方式二stdio 方式連接。Client 以本地子進(jìn)程方式啟動 Server適合命令行工具或本地開發(fā)。方式三HTTP 方式連接。Server 部署在遠(yuǎn)端或者本地監(jiān)聽端口Client 通過 HTTP 連接。我用得最多的是第三種因為它在環(huán)境隔離和排障上最清晰——Server 獨(dú)立部署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());有一個隱性要點(diǎn)連接成功后要先listTools()拿到工具定義再調(diào)用工具。很多初次接觸的人會省略第一步直接callTool雖然也能調(diào)用但你沒有拿到 Server 最新的 Schema遇到參數(shù)變更就直接懵了。規(guī)范的調(diào)用鏈一定是“連接 → 拉能力清單 → 按 Schema 構(gòu)造參數(shù) → 調(diào)用”。4.3 驗證與監(jiān)控如何判斷調(diào)用走了協(xié)議層一個失敗的工具調(diào)用可能斷在四個環(huán)節(jié)Client 發(fā)起前、協(xié)議傳輸中、Server 執(zhí)行中、結(jié)果回傳中。所以驗證要做分環(huán)節(jié)斷言。冒煙測試階段我習(xí)慣用一個最小驗證腳本連接、拉工具列表、調(diào)用一個無副作用的工具比如echo或getCurrentTime確認(rèn)全鏈路通了。再測試一個真正有業(yè)務(wù)邏輯的工具。監(jiān)控方面有兩個實用點(diǎn)協(xié)議報文抓包本地 HTTP 傳輸模式下可以用抓包工具看請求體里的 JSON-RPC 結(jié)構(gòu)確認(rèn)tools/call的 params 是否按預(yù)期組織Server 端日志埋點(diǎn)每個工具方法入?yún)⒑秃臅r打點(diǎn)配合 Client 端調(diào)用耗時可以快速定位耗時在傳輸層還是在業(yè)務(wù)層。只要這兩個觀測點(diǎn)做好MCP 鏈路對普通開發(fā)來說就不再是黑盒。4.4 配置管理多環(huán)境連接信息怎么拆工具鏈一旦涉及多個環(huán)境開發(fā)、測試、生產(chǎn)連接管理就會成為實際痛點(diǎn)。我的建議是將 MCP Client 的連接信息當(dāng)作普通的外部依賴配置來管理不要硬編碼。用配置中心或環(huán)境變量維護(hù)以下內(nèi)容Server 的 baseUrl傳輸類型stdio 還是 HTTP鑒權(quán)憑證連接超時、調(diào)用超時啟動時是否自動連接。舉例mcp: servers: user-server: base-url: ${MCP_USER_SERVER_URL} transport: http auth-token: ${MCP_USER_SERVER_TOKEN} connect-timeout: 5s call-timeout: 10s不同環(huán)境用不同的配置項注入既不會把測試環(huán)境的地址帶到生產(chǎn)也能在同一條代碼里適配多種連接拓?fù)?。集成測試時用本地 Server 地址生產(chǎn)切到正式集群地址代碼層面完全不用改。5. 我會踩的坑真實問題與排查思路5.1 協(xié)議版本與 SDK 版本強(qiáng)綁定MCP 協(xié)議還在快速演進(jìn)中Java SDK 的版本與協(xié)議版本是強(qiáng)綁定的。不同版本的 SDK 初始化的默認(rèn)協(xié)議版本可能不同如果 Client 和 Server 用的 SDK 版本差距過大可能出現(xiàn)握手失敗或能力協(xié)商異?！，F(xiàn)象一般表現(xiàn)為連接時報Unsupported protocol version或者連接成功了但listTools()返回空集合。排查鏈路抓初始化握手報文看 Client 發(fā)出去的protocolVersion和 Server 回應(yīng)的版本檢查兩端 SDK 對應(yīng)的協(xié)議版本范圍確認(rèn)是否有交集優(yōu)先把兩端 SDK 升級到一致版本。這個問題治本的辦法是統(tǒng)一版本管理。MCP SDK 版本號應(yīng)該在項目依賴鎖文件里固定雙端共用同一套 BOM 或版本目錄不要各自引入不同小版本。5.2 線程模型與連接泄漏一個我實際遇到過的線上問題我在一個內(nèi)部項目里把 MCP Server 集成到一個已有的 Spring Boot 應(yīng)用中。服務(wù)剛上線時一切正常一周后開始出現(xiàn)連接超時、響應(yīng)變慢。排查后發(fā)現(xiàn)是線程池被打滿。原因不復(fù)雜SDK 的同步接口在等待協(xié)議響應(yīng)時會占用調(diào)用線程而我的業(yè)務(wù)代碼把多次工具調(diào)用放在了同一個同步塊里且沒有設(shè)置調(diào)用超時。當(dāng)某個工具調(diào)用的底層接口響應(yīng)變慢時一個慢調(diào)用就卡住了一個線程隨著流量積壓線程池被慢調(diào)用占滿健康請求反而被餓死。處理方案有三個層面所有工具調(diào)用必須有明確超時不能依賴默認(rèn)值或無限等待慢工具要隔離不要和快工具共用同一個線程池或調(diào)用通道連接數(shù)要與業(yè)務(wù)并發(fā)模型匹配。從我個人的經(jīng)驗看任何“連接不上”或“卡住沒反應(yīng)”的問題先檢查三件事線程有沒有泄漏、連接有沒有超時、底層有沒有慢調(diào)用。這三件事查完大部分問題都能定位。5.3 超時與重試默認(rèn)策略不一定適合你Java SDK 的默認(rèn)超時和重試策略通常是為通用場景設(shè)計的不一定適合你的業(yè)務(wù)。比如一個工具調(diào)用正常耗時只要 200ms但偶爾因為依賴抖動會到 3 秒。如果你不設(shè)置超時一個抖動就可能讓調(diào)用線程掛住很久。反之如果一個工具本身平均耗時就需要 8 秒你把超時設(shè)成 1 秒那這個工具永遠(yuǎn)不會成功。這表明超時設(shè)置必須“一工具一策”。每個callTool調(diào)用最好針對該方法設(shè)定獨(dú)立的超時時間而不是全局一套。重試也類似。協(xié)議層重試和業(yè)務(wù)層重試要區(qū)分開協(xié)議層重試連接失敗、握手失敗這類通道問題適合有限重試業(yè)務(wù)層重試工具方法內(nèi)部因為依賴抖動失敗而拋異常這個不該由 MCP 協(xié)議層重試而應(yīng)該在業(yè)務(wù)層按冪等規(guī)則處理。我見到的一個典型反例有人在 Client 側(cè)把callTool包了一個全局重試遇到超時就重試兩遍。結(jié)果 Server 端的工具是“創(chuàng)建訂單”這種非冪等操作一個慢響應(yīng)被判定超時但 Server 側(cè)實際創(chuàng)建成功了Client 側(cè)又發(fā)起重試產(chǎn)生了一筆重復(fù)訂單。在工具調(diào)用鏈路上默認(rèn)不要亂加重試尤其不要在高風(fēng)險操作上加。5.4 日志與調(diào)試技巧看到協(xié)議層實際交換MCP 調(diào)試的難點(diǎn)在于“兩端都正常但合在一起就不對”。這時候最有效的手段是把協(xié)議層的實際消息打出來。我調(diào)試 MCP Java SDK 問題時通常會做兩件事第一開啟 SDK 的日志級別到DEBUG觀察初始化請求的參數(shù)結(jié)構(gòu)、工具定義的實際 JSON Schema 長什么樣。這能快速發(fā)現(xiàn)序列化問題比如某個參數(shù)類型被序列化成了期望之外的結(jié)構(gòu)。第二在 HTTP 模式下用工具抓包直接看 HTTP 請求體和響應(yīng)體。如果請求能正常到達(dá) Server 但返回異常問題大概率在 Server 工具方法的參數(shù)綁定或異常處理上。有一個高頻問題值得單獨(dú)說工具方法的返回值序列化失敗。比如返回對象里有循環(huán)引用、有無法序列化的InputStream、或者有個LocalDateTime字段但序列化配置沒適配。SDK 在把返回值轉(zhuǎn)成協(xié)議 Content 塊時如果遇到無法序列化的對象通常會拋異常或返回空內(nèi)容。開發(fā)時一定要用真實對象做一次端到端測試不要只測簡單字符串返回。6. 擴(kuò)展玩法與邊界6.1 從“單工具”到“工具網(wǎng)關(guān)”鑒權(quán)與多租戶改造MCP Server 一旦多了就會自然想做一個統(tǒng)一網(wǎng)關(guān)對外是一個 MCP Server對內(nèi)路由到多個業(yè)務(wù)服務(wù)。Java SDK 完全支持這種改造。核心思路是做一層工具轉(zhuǎn)發(fā)器Server 掃描時注冊的都是“代理工具”真正調(diào)用時根據(jù)參數(shù)里的路由字段從工具注冊表中找到實際執(zhí)行類并調(diào)用。多租戶場景下每個租戶的工具可見性可能不同。這時不要把工具清單寫死而應(yīng)當(dāng)根據(jù)調(diào)用方身份動態(tài)生成工具列表。MCP 單次會話里Client 和 Server 是一對一的所以“租戶身份”通常在連接初始化或請求 Header 里注入。Server 側(cè)可以基于身份信息過濾工具注冊表實現(xiàn)了“不同租戶看到不同工具集合”的效果。6.2 攔截器與請求上下文的擴(kuò)展Java SDK 一般會提供在請求鏈路上插入自定義邏輯的擴(kuò)展點(diǎn)如攔截器、過濾器我強(qiáng)烈建議不要錯過這個能力。攔截器適合做幾類橫向邏輯調(diào)用耗時統(tǒng)計和審計日志參數(shù)脫敏比如把請求里的密碼字段提前打碼權(quán)限二次校驗灰度放量。這類邏輯如果寫進(jìn)每個Tool方法里代碼會非常臟。放進(jìn)攔截器后工具方法只關(guān)心業(yè)務(wù)實現(xiàn)橫切邏輯統(tǒng)一處理整體可維護(hù)性提升非常明顯。6.3 不只是 AI 應(yīng)用MCP 的跨界用法回到標(biāo)題的關(guān)鍵詞“Client 和 Server 功能”其實這兩端組合起來的能力邊界遠(yuǎn)不止給大模型當(dāng)工具這么窄。我見過一個有意思的用法把一個“配置查詢服務(wù)”做成 MCP Server然后一個運(yùn)維腳本通過 MCP Client 去讀取配置。這樣做的價值在于所有配置讀取都走同一條協(xié)議鏈路統(tǒng)一了鑒權(quán)、審計、限流。配置系統(tǒng)本身并不知道自己在一個 MCP 生態(tài)里它只是暴露了資源。還有一個用法是把測試數(shù)據(jù)工廠包成 MCP Server測試框架通過 Client 在集成測試?yán)飫討B(tài)造數(shù)。工具就是“創(chuàng)建用戶”“創(chuàng)建訂單”這些方法測試代碼不用再寫一坨工具類而是通過標(biāo)準(zhǔn)協(xié)議去調(diào)用測試數(shù)據(jù)和業(yè)務(wù)邏輯的耦合也被切斷了。這些案例的共同點(diǎn)是當(dāng)一套能力被標(biāo)準(zhǔn)化為可發(fā)現(xiàn)、可調(diào)用、可組合的協(xié)議接口之后消費(fèi)方不一定是模型也可以是腳本、測試框架、運(yùn)維工具。Java SDK 在這條路上最重要的價值就是讓 JVM 生態(tài)的開發(fā)者能以最低的改造成本把自己的服務(wù)升級為可組合的協(xié)議節(jié)點(diǎn)。我自己的經(jīng)驗是第一次跑通 MCP 雙端鏈路時最大的收獲不是“AI 能調(diào)用工具了”而是理解了“標(biāo)準(zhǔn)化連接”這件事本身的價值。工具注冊、資源暴露、采樣回連這些設(shè)計每一條都是沖著“讓系統(tǒng)之間以統(tǒng)一語言協(xié)作”去的。如果你正在做一個有多種消費(fèi)者、需要動態(tài)擴(kuò)展能力的服務(wù)MCP Java SDK 值得認(rèn)真評估。 MCP Java SDK實戰(zhàn)：Client與Server雙端集成核心解析
MCPModel Context Protocol這兩年火得很快周邊生態(tài)也已經(jīng)從早期的“Python 獨(dú)大”擴(kuò)展到了 Java、Go、TypeScript 等主流語言。Java 生態(tài)里官方 SDK 的定位很明確讓 JVM 系的應(yīng)用能快速當(dāng)一個 MCP Client去連接外部工具服務(wù)也能快速把一個內(nèi)部能力包成一個 MCP Server供 AI 應(yīng)用或其他客戶端調(diào)用。這篇博文我按自己實際跑通的經(jīng)驗來寫重點(diǎn)拆 MCP Java SDK 的 Client 和 Server 兩端的核心功能它們解決什么問題、初始化流程長什么樣、工具和資源是怎么暴露與發(fā)現(xiàn)的、雙端聯(lián)動怎么驗證以及我踩過的幾個比較典型的坑。適合剛接觸 MCP、準(zhǔn)備在 Java 項目里落地 AI 工具接入的開發(fā)者參考。1. MCP 與 Java SDK先搞清楚我們在集成什么1.1 沒有 MCP 時AI 應(yīng)用接入工具為什么這么痛苦在 MCP 出現(xiàn)之前一個 AI 應(yīng)用想調(diào)用外部能力通常是一條“點(diǎn)對點(diǎn)”的集成路線你有一個大模型對話框架想加一個查數(shù)據(jù)庫的能力那就寫一段函數(shù)把這個函數(shù)注冊進(jìn)模型的工具列表再處理模型返回的參數(shù)調(diào)用請求。這本身不復(fù)雜復(fù)雜的是工具一多就亂了。比如我們有天氣查詢、內(nèi)部訂單查詢、Git 倉庫操作、監(jiān)控告警查詢這四組能力。如果沒有統(tǒng)一協(xié)議每組能力都要定義一套參數(shù)格式、一套鑒權(quán)方式、一套調(diào)用約定。模型側(cè)則要維護(hù)一個“越來越大的工具描述集合”每接一個新系統(tǒng)不僅要改調(diào)用代碼還要重新設(shè)計工具的描述文本讓模型能準(zhǔn)確理解該調(diào)哪個、參數(shù)怎么填。MCP 想解決的核心問題是“把 AI 應(yīng)用和工具之間的連接方式標(biāo)準(zhǔn)化”。它定義了一套 JSON-RPC 風(fēng)格的消息格式約定 Client 和 Server 之間怎么握手、怎么發(fā)現(xiàn)能力、怎么調(diào)用工具、怎么傳輸資源。這樣模型應(yīng)用只需實現(xiàn)一個 MCP Client工具方只需實現(xiàn)一個 MCP Server兩邊通過協(xié)議對話而不是靠一堆散亂的內(nèi)部 API。1.2 MCP 的 Client/Server 模型和 Java SDK 的定位MCP 的架構(gòu)是典型的主從模式但這里的“主從”只體現(xiàn)在會話管理上兩端在協(xié)議層面是平等的協(xié)商關(guān)系。MCP Server持有實際能力的一方。它能暴露三類東西——工具Tool、資源Resource、提示詞模板Prompt。工具是用來被調(diào)用執(zhí)行的資源是用來讀取上下文信息的提示詞模板是給模型用的語料片段。MCP Client連接 Server 的一方。它負(fù)責(zé)發(fā)起握手、拉取 Server 的能力清單、調(diào)用工具、讀取資源并把結(jié)果交給上層 AI 應(yīng)用。Java SDK 的價值是把這套協(xié)議封裝成符合 Java 習(xí)慣的 API。你不用手工構(gòu)造 JSON-RPC 報文、不用自己維護(hù)連接狀態(tài)、也不用自己解析 Server 返回的 Content 塊SDK 把這些都做了。而且接口有同步和異步兩套風(fēng)格Spring 環(huán)境里也有適配能力這對 Java 開發(fā)者的集成成本是個很實際的降低。1.3 SDK 在 JVM 場景下的適用邊界使用 Java SDK 的項目大致有三類第一類是已有 AI 編排服務(wù)的后端應(yīng)用。你有一個調(diào)度引擎需要讓大模型去調(diào)用企業(yè)內(nèi)部工具那么你在引擎層內(nèi)嵌一個 MCP Client連接各個內(nèi)部的 MCP Server就實現(xiàn)了工具統(tǒng)一接入。第二類是工具提供方。你想把自己維護(hù)的一套 API 暴露給模型用與其開發(fā)一個“專用模型接口”不如做一層 MCP Server 適配把現(xiàn)有服務(wù)包成標(biāo)準(zhǔn)協(xié)議誰都能連。第三類是本地開發(fā)調(diào)試工具。比如希望 CLI 工具能訪問 MCP 生態(tài)里的服務(wù)通過 Java SDK 起一個 Client再配合標(biāo)準(zhǔn)輸入輸出傳輸方式就能把本地命令接到遠(yuǎn)端 Server 上。SDK 的適用范圍不是只能做“AI 應(yīng)用”它本質(zhì)上是讓任意 Java 進(jìn)程具備 MCP 會話能力。所以如果你有一個中間件想接入 MCP 生態(tài)也可以直接用這套 SDK 完成協(xié)議層工作。2. 先啃 Client 端連接、發(fā)現(xiàn)、調(diào)用這條主線2.1 初始化與連接生命周期Client 端使用 SDK 時的第一件事是創(chuàng)建一個客戶端實例。SDK 提供了同步 ClientSync和異步 ClientAsync兩類核心入口。平時開發(fā)我建議先從同步接口入手因為它符合 Java 開發(fā)者對“方法調(diào)用返回結(jié)果”的直覺排查問題也簡單。業(yè)務(wù)真正跑起來再評估是否需要異步換取更好的吞吐。創(chuàng)建同步 Client 的典型流程分為三步構(gòu)造傳輸層配置指定 Server 的地址和通信方式構(gòu)造 Client 配置設(shè)置協(xié)議版本、客戶端標(biāo)識、能力聲明調(diào)用初始化連接完成握手。代碼示意以實際引入版本的 API 為準(zhǔn)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(); // 連接并完成協(xié)議握手 client.connect();這個connect()不是簡單的 TCP 建連。對應(yīng) MCP 協(xié)議里的 initialize 請求Client 會告訴 Server“我是誰、我支持哪些能力”Server 會返回它的協(xié)議版本、Server 信息、以及它支持哪些能力。雙方完成能力協(xié)商后連接才真正處于可用狀態(tài)。斷開連接時調(diào)用close()或closeGracefully()。前者立即關(guān)閉底層傳輸后者會先嘗試把已發(fā)出的請求處理完適合優(yōu)雅停機(jī)。這部分連接生命周期控制在誤用線程池之后特別重要后面踩坑一節(jié)會詳細(xì)說。2.2 能力協(xié)商與動態(tài)工具發(fā)現(xiàn)MCP 協(xié)議里有個很關(guān)鍵的機(jī)制是能力協(xié)商。初始化階段Client 聲明roots、sampling等能力Server 聲明resources、tools、prompts等能力。協(xié)商完成之后雙方才確認(rèn)“這段會話里哪些功能是可用的”?？蛻舳四玫?Server 能力之后需要主動拉取工具列表。這個動作對應(yīng) 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告訴模型參數(shù)怎么填 }這一步要理解它的本質(zhì)工具不是寫死在代碼里的而是運(yùn)行時動態(tài)發(fā)現(xiàn)的。這意味著服務(wù)端可以隨時加新工具客戶端不用改代碼重啟后拉一次列表就能感知。這也是 MCP 相對“硬編碼工具注冊”的核心優(yōu)勢。調(diào)用工具走的是tools/call請求SDK 里用callTool(name, arguments)CallToolResult result client.callTool( getUser, Map.of(userId, u_12345) ); result.content().forEach(content - { // 拿到工具返回的文本、圖片、資源鏈接 });這里有個容易忽略的細(xì)節(jié)arguments是一個MapString, Object它的結(jié)構(gòu)必須和 Server 暴露的inputSchema吻合。如果參數(shù)類型對不上Server 端 JSON Schema 校驗會直接報錯。實際項目里我建議在調(diào)用前先拉一次工具列表把 Schema 傳給模型做參考而不是寫死參數(shù)結(jié)構(gòu)——不然服務(wù)端稍微改個參數(shù)名客戶端就直接斷掉。2.3 同步、異步、阻塞式 API 的選擇Java SDK 的 Client 除了McpSyncClient還有McpAsyncClient。兩者的定位區(qū)別是同步接口內(nèi)部會用阻塞方式等待響應(yīng)適合請求量可控、鏈路要求直觀的場景異步接口則基于CompletableFuture適合高并發(fā)、或者調(diào)用發(fā)起處不希望阻塞線程的場景。McpAsyncClient asyncClient McpAsyncClient.builder() .clientConfig(config) .build(); asyncClient.connect() .thenCompose(v - asyncClient.listTools()) .thenAccept(tools - System.out.println(tools.tools().size()));實際使用中我傾向于在異步接口外層保留一個同步門面而不是層層嵌套thenCompose。原因很簡單MCP 調(diào)用鏈里除了協(xié)議請求外還有業(yè)務(wù)邏輯、鑒權(quán)、日志埋點(diǎn)等全鏈路異步會讓出錯的排查路徑變得很隱晦。大多數(shù) Java 后端項目的請求入口本身就是多線程模型同步阻塞一個業(yè)務(wù)線程換取的是清晰的調(diào)用鏈這在工具調(diào)用這種低頻率、高單次代價的場景下是劃算的。如果你的應(yīng)用是用 Spring WebFlux 這類全響應(yīng)式框架那就直接擁抱異步接口把CompletableFuture轉(zhuǎn)換到響應(yīng)式流里。2.4 Client 端的安全邊界與鑒權(quán)開銷MCP 協(xié)議本身沒規(guī)定鑒權(quán)方式Java SDK 也不會替你攔截“誰在調(diào)用工具”。這意味著你在 Client 側(cè)必須自己把控好安全邊界。我遇到過的實際場景是內(nèi)部一個數(shù)據(jù)查詢服務(wù)接入 MCP 后所有能訪問 Client 端接口的人理論上都能通過 Client 去調(diào)用 Server 端暴露的工具。如果 Server 端工具背后直接是數(shù)據(jù)庫敏感表那這就變成了一個繞過業(yè)務(wù)權(quán)限體系的“后門”。務(wù)實做法分三層傳輸層安全遠(yuǎn)端傳輸必須走 HTTPS本地調(diào)試用 HTTP 也要限定監(jiān)聽地址接入層鑒權(quán)Client 與 Server 之間增加 Token 或 mTLS。Java SDK 的傳輸層一般支持自定義 Headers可以在啟動時注入認(rèn)證憑證工具級授權(quán)Server 端不要無腦暴露所有工具。至少做一個白名單機(jī)制根據(jù)調(diào)用方身份過濾可 List 的工具。// 傳輸層注入 token 的示意 HttpClientTransport transport HttpClientTransport.builder() .baseUrl(https://mcp.example.com/mcp) .headers(Map.of(Authorization, Bearer token)) .build();鑒權(quán)不是 MCP 特有的負(fù)擔(dān)但協(xié)議標(biāo)準(zhǔn)化之后安全問題更容易被忽略。很多人以為“走協(xié)議就安全了”這是一個必須盡早打破的錯覺。3. Server 端要做的事注冊、暴露、回連3.1 工具注冊從方法注解到協(xié)議消息Server 端最核心的工作是把 Java 方法暴露成 MCP 工具。SDK 里最直觀的方式是用Tool注解。Tool(description 根據(jù) userId 查詢用戶基礎(chǔ)信息) public UserInfo getUser(ToolParam(description 用戶ID) String userId) { // 業(yè)務(wù)實現(xiàn) return userRepository.findById(userId); }這個注解的作用不只是標(biāo)記方法。SDK 在啟動時會對帶Tool注解的方法做掃描通過反射提取方法名、描述、參數(shù)列表再結(jié)合參數(shù)上的ToolParam注解自動生成符合 JSON Schema 的工具定義。也就是說你寫一個普通 Java 方法SDK 幫你把它變成了模型可感知、可調(diào)用的協(xié)議工具。這里有幾個設(shè)計原則值得注意方法名就是工具名。模型調(diào)用時依賴這個名字做語義匹配所以名字要直觀、且符合團(tuán)隊內(nèi)部統(tǒng)一規(guī)范description不能寫得太短。模型的工具選擇很大程度依賴描述文本寫“查詢用戶”就遠(yuǎn)不如寫“根據(jù)內(nèi)部統(tǒng)一用戶ID查詢用戶基礎(chǔ)信息常用于訂單、權(quán)限模塊的用戶維度查詢”效果好參數(shù)對象如果比較復(fù)雜可以定義一個 POJO 作為入?yún)DK 會按 POJO 的字段結(jié)構(gòu)生成嵌套 JSON Schema比散列一堆 String 參數(shù)可讀性好很多。工具注冊后Server 啟動時會自動完成協(xié)議側(cè)的tools/list響應(yīng)和tools/call分發(fā)。3.2 資源與提示詞模板的暴露工具之外Server 還能暴露資源Resource和提示詞模板Prompt。資源本質(zhì)上是可讀取的數(shù)據(jù)源比如文件內(nèi)容、數(shù)據(jù)庫查詢結(jié)果、項目文檔片段。它們不觸發(fā)執(zhí)行邏輯而是把“上下文”提供給客戶端供模型理解某個主題。SDK 里資源一般通過注解或注冊器暴露。McpResource(name current-user, description 當(dāng)前登錄用戶信息, uri user://current) public String getUserResource() { return userSessionService.currentUserSummary(); }資源的 URI 是協(xié)議層定位資源的標(biāo)識客戶端通過resources/read請求讀取。實際項目中可以把監(jiān)控大盤的數(shù)據(jù)、灰度開關(guān)狀態(tài)、配置中心內(nèi)容這類“低變更、常需要”的信息作為資源暴露而不是做成工具。因為資源讀取的語義是“給我看”而工具的語義是“幫我做”兩者在模型側(cè)的使用方式完全不同。提示詞模板則是預(yù)定義的對話片段。它適合做分層 Prompt 管理比如把“代碼評審規(guī)則”“SQL 生成規(guī)范”這類不常變化的指令文本放到 Server 端。客戶端發(fā)起 prompts/get 請求拿到模板后填充變量再注入對話上下文。工具、資源、提示詞模板是 Server 能力的三根支柱但大多數(shù)項目真正高頻使用的還是工具。資源和提示詞模板更適合作為進(jìn)階能力逐步引入不用一開始就全部鋪開。3.3 Server 的日志、遙測與采樣回連Server 端的運(yùn)行觀測是個容易被忽略的點(diǎn)。由于 MCP 協(xié)議鏈路是“模型應(yīng)用 → Client → Server”一旦工具調(diào)用失敗用戶感知到的是模型回答“出錯了”但問題可能出在 Server 端的方法異常、參數(shù)校驗、依賴服務(wù)超時等環(huán)節(jié)。沒有日志鏈路排查會非常痛苦。我的做法是在 Server 端每個Tool方法內(nèi)至少記錄三件事入?yún)⒄?、?zhí)行耗時、出參摘要。不需要額外的鏈路追蹤組件先確?！澳膫€工具、什么參數(shù)、耗了多久”一目了然。Java SDK 在協(xié)議層面也支持日志/遙測透傳。你可以在 Client 端上報請求耗時、錯誤碼、重試次數(shù)等指標(biāo)與 Server 端的執(zhí)行日志在時間維度對齊就能大致還原一次調(diào)用在鏈路里的分布情況。3.4 采樣回連機(jī)制Server 反向請求模型MCP 協(xié)議有個看起來很不起眼、但非常重要的能力叫Sampling采樣它允許 Server 請求 Client 發(fā)起一次 LLM 補(bǔ)全。這就是“Server 反向調(diào)用模型”的機(jī)制。什么場景需要它典型的是一個專業(yè)領(lǐng)域的工具 Server 在處理請求時發(fā)現(xiàn)需要找模型做一次中間判斷比如“這段用戶輸入屬于哪個業(yè)務(wù)意圖”。此時 Server 可以通過sampling/create請求把上下文和提示詞發(fā)給 Client由 Client 調(diào)用它所連接的模型拿到補(bǔ)全結(jié)果后返回給 Server。在 Java SDK 里啟用采樣Client 初始化時要聲明sampling能力并實現(xiàn)一個回調(diào)處理器。Server 端在部署服務(wù)時把采樣回調(diào)傳給某些工具方法業(yè)務(wù)代碼里就能發(fā)起一次模型請求。// 示意Client 側(cè)處理 Server 的采樣請求 McpClientConfig config McpClientConfig.builder() .capabilities(new ClientCapabilities( null, null, new SamplingCapability())) .build(); // Server 側(cè)工具內(nèi)發(fā)起采樣請求 CreateMessageRequest request new CreateMessageRequest( List.of(contentBlock, systemPrompt), new ModelPreferences(...)); CreateMessageResult result samplingClient.createMessage(request);Sampling 機(jī)制讓 Server 不再只是一個“被動執(zhí)行者”它可以借助模型能力完成輕量級決策。這個設(shè)計非常巧妙它避免了很多場景下“所有邏輯都要在模型側(cè)做意圖識別”的笨重做法。但代價是鏈路變長、延遲變高。我建議只在確實需要模型判斷時使用而且要給采樣調(diào)用設(shè)置超時和兜底策略不能因為模型沒響應(yīng)就把整個工具調(diào)用阻塞住。4. 雙端聯(lián)動典型集成落地與驗證4.1 從零搭一個本地 MCP 服務(wù)講了這么多原理我們實操一把。假設(shè)現(xiàn)在要做一個“內(nèi)部用戶查詢”的 MCP Server暴露兩個工具根據(jù) userId 查用戶、根據(jù)部門查用戶列表。第一步引入 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(); } }本地開發(fā)階段用標(biāo)準(zhǔn)輸入輸出stdio作為傳輸是最省事的。模型應(yīng)用通過子進(jìn)程方式啟動這個 Server雙方在管道里交換 JSON-RPC 消息不需要處理端口、防火墻。如果要給遠(yuǎn)程調(diào)用則換成 HTTP 流式傳輸指定監(jiān)聽端口即可。4.2 用 Client 連接并調(diào)用服務(wù)的三種方式Server 跑起來之后我們用 Client 去連接。方式一同進(jìn)程內(nèi)連接。這是集成測試時最方便的方式Client 和 Server 都在一個 JVM 里不經(jīng)過網(wǎng)絡(luò)直接通過傳輸層對接。方式二stdio 方式連接。Client 以本地子進(jìn)程方式啟動 Server適合命令行工具或本地開發(fā)。方式三HTTP 方式連接。Server 部署在遠(yuǎn)端或者本地監(jiān)聽端口Client 通過 HTTP 連接。我用得最多的是第三種因為它在環(huán)境隔離和排障上最清晰——Server 獨(dú)立部署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());有一個隱性要點(diǎn)連接成功后要先listTools()拿到工具定義再調(diào)用工具。很多初次接觸的人會省略第一步直接callTool雖然也能調(diào)用但你沒有拿到 Server 最新的 Schema遇到參數(shù)變更就直接懵了。規(guī)范的調(diào)用鏈一定是“連接 → 拉能力清單 → 按 Schema 構(gòu)造參數(shù) → 調(diào)用”。4.3 驗證與監(jiān)控如何判斷調(diào)用走了協(xié)議層一個失敗的工具調(diào)用可能斷在四個環(huán)節(jié)Client 發(fā)起前、協(xié)議傳輸中、Server 執(zhí)行中、結(jié)果回傳中。所以驗證要做分環(huán)節(jié)斷言。冒煙測試階段我習(xí)慣用一個最小驗證腳本連接、拉工具列表、調(diào)用一個無副作用的工具比如echo或getCurrentTime確認(rèn)全鏈路通了。再測試一個真正有業(yè)務(wù)邏輯的工具。監(jiān)控方面有兩個實用點(diǎn)協(xié)議報文抓包本地 HTTP 傳輸模式下可以用抓包工具看請求體里的 JSON-RPC 結(jié)構(gòu)確認(rèn)tools/call的 params 是否按預(yù)期組織Server 端日志埋點(diǎn)每個工具方法入?yún)⒑秃臅r打點(diǎn)配合 Client 端調(diào)用耗時可以快速定位耗時在傳輸層還是在業(yè)務(wù)層。只要這兩個觀測點(diǎn)做好MCP 鏈路對普通開發(fā)來說就不再是黑盒。4.4 配置管理多環(huán)境連接信息怎么拆工具鏈一旦涉及多個環(huán)境開發(fā)、測試、生產(chǎn)連接管理就會成為實際痛點(diǎn)。我的建議是將 MCP Client 的連接信息當(dāng)作普通的外部依賴配置來管理不要硬編碼。用配置中心或環(huán)境變量維護(hù)以下內(nèi)容Server 的 baseUrl傳輸類型stdio 還是 HTTP鑒權(quán)憑證連接超時、調(diào)用超時啟動時是否自動連接。舉例mcp: servers: user-server: base-url: ${MCP_USER_SERVER_URL} transport: http auth-token: ${MCP_USER_SERVER_TOKEN} connect-timeout: 5s call-timeout: 10s不同環(huán)境用不同的配置項注入既不會把測試環(huán)境的地址帶到生產(chǎn)也能在同一條代碼里適配多種連接拓?fù)?。集成測試時用本地 Server 地址生產(chǎn)切到正式集群地址代碼層面完全不用改。5. 我會踩的坑真實問題與排查思路5.1 協(xié)議版本與 SDK 版本強(qiáng)綁定MCP 協(xié)議還在快速演進(jìn)中Java SDK 的版本與協(xié)議版本是強(qiáng)綁定的。不同版本的 SDK 初始化的默認(rèn)協(xié)議版本可能不同如果 Client 和 Server 用的 SDK 版本差距過大可能出現(xiàn)握手失敗或能力協(xié)商異?！，F(xiàn)象一般表現(xiàn)為連接時報Unsupported protocol version或者連接成功了但listTools()返回空集合。排查鏈路抓初始化握手報文看 Client 發(fā)出去的protocolVersion和 Server 回應(yīng)的版本檢查兩端 SDK 對應(yīng)的協(xié)議版本范圍確認(rèn)是否有交集優(yōu)先把兩端 SDK 升級到一致版本。這個問題治本的辦法是統(tǒng)一版本管理。MCP SDK 版本號應(yīng)該在項目依賴鎖文件里固定雙端共用同一套 BOM 或版本目錄不要各自引入不同小版本。5.2 線程模型與連接泄漏一個我實際遇到過的線上問題我在一個內(nèi)部項目里把 MCP Server 集成到一個已有的 Spring Boot 應(yīng)用中。服務(wù)剛上線時一切正常一周后開始出現(xiàn)連接超時、響應(yīng)變慢。排查后發(fā)現(xiàn)是線程池被打滿。原因不復(fù)雜SDK 的同步接口在等待協(xié)議響應(yīng)時會占用調(diào)用線程而我的業(yè)務(wù)代碼把多次工具調(diào)用放在了同一個同步塊里且沒有設(shè)置調(diào)用超時。當(dāng)某個工具調(diào)用的底層接口響應(yīng)變慢時一個慢調(diào)用就卡住了一個線程隨著流量積壓線程池被慢調(diào)用占滿健康請求反而被餓死。處理方案有三個層面所有工具調(diào)用必須有明確超時不能依賴默認(rèn)值或無限等待慢工具要隔離不要和快工具共用同一個線程池或調(diào)用通道連接數(shù)要與業(yè)務(wù)并發(fā)模型匹配。從我個人的經(jīng)驗看任何“連接不上”或“卡住沒反應(yīng)”的問題先檢查三件事線程有沒有泄漏、連接有沒有超時、底層有沒有慢調(diào)用。這三件事查完大部分問題都能定位。5.3 超時與重試默認(rèn)策略不一定適合你Java SDK 的默認(rèn)超時和重試策略通常是為通用場景設(shè)計的不一定適合你的業(yè)務(wù)。比如一個工具調(diào)用正常耗時只要 200ms但偶爾因為依賴抖動會到 3 秒。如果你不設(shè)置超時一個抖動就可能讓調(diào)用線程掛住很久。反之如果一個工具本身平均耗時就需要 8 秒你把超時設(shè)成 1 秒那這個工具永遠(yuǎn)不會成功。這表明超時設(shè)置必須“一工具一策”。每個callTool調(diào)用最好針對該方法設(shè)定獨(dú)立的超時時間而不是全局一套。重試也類似。協(xié)議層重試和業(yè)務(wù)層重試要區(qū)分開協(xié)議層重試連接失敗、握手失敗這類通道問題適合有限重試業(yè)務(wù)層重試工具方法內(nèi)部因為依賴抖動失敗而拋異常這個不該由 MCP 協(xié)議層重試而應(yīng)該在業(yè)務(wù)層按冪等規(guī)則處理。我見到的一個典型反例有人在 Client 側(cè)把callTool包了一個全局重試遇到超時就重試兩遍。結(jié)果 Server 端的工具是“創(chuàng)建訂單”這種非冪等操作一個慢響應(yīng)被判定超時但 Server 側(cè)實際創(chuàng)建成功了Client 側(cè)又發(fā)起重試產(chǎn)生了一筆重復(fù)訂單。在工具調(diào)用鏈路上默認(rèn)不要亂加重試尤其不要在高風(fēng)險操作上加。5.4 日志與調(diào)試技巧看到協(xié)議層實際交換MCP 調(diào)試的難點(diǎn)在于“兩端都正常但合在一起就不對”。這時候最有效的手段是把協(xié)議層的實際消息打出來。我調(diào)試 MCP Java SDK 問題時通常會做兩件事第一開啟 SDK 的日志級別到DEBUG觀察初始化請求的參數(shù)結(jié)構(gòu)、工具定義的實際 JSON Schema 長什么樣。這能快速發(fā)現(xiàn)序列化問題比如某個參數(shù)類型被序列化成了期望之外的結(jié)構(gòu)。第二在 HTTP 模式下用工具抓包直接看 HTTP 請求體和響應(yīng)體。如果請求能正常到達(dá) Server 但返回異常問題大概率在 Server 工具方法的參數(shù)綁定或異常處理上。有一個高頻問題值得單獨(dú)說工具方法的返回值序列化失敗。比如返回對象里有循環(huán)引用、有無法序列化的InputStream、或者有個LocalDateTime字段但序列化配置沒適配。SDK 在把返回值轉(zhuǎn)成協(xié)議 Content 塊時如果遇到無法序列化的對象通常會拋異常或返回空內(nèi)容。開發(fā)時一定要用真實對象做一次端到端測試不要只測簡單字符串返回。6. 擴(kuò)展玩法與邊界6.1 從“單工具”到“工具網(wǎng)關(guān)”鑒權(quán)與多租戶改造MCP Server 一旦多了就會自然想做一個統(tǒng)一網(wǎng)關(guān)對外是一個 MCP Server對內(nèi)路由到多個業(yè)務(wù)服務(wù)。Java SDK 完全支持這種改造。核心思路是做一層工具轉(zhuǎn)發(fā)器Server 掃描時注冊的都是“代理工具”真正調(diào)用時根據(jù)參數(shù)里的路由字段從工具注冊表中找到實際執(zhí)行類并調(diào)用。多租戶場景下每個租戶的工具可見性可能不同。這時不要把工具清單寫死而應(yīng)當(dāng)根據(jù)調(diào)用方身份動態(tài)生成工具列表。MCP 單次會話里Client 和 Server 是一對一的所以“租戶身份”通常在連接初始化或請求 Header 里注入。Server 側(cè)可以基于身份信息過濾工具注冊表實現(xiàn)了“不同租戶看到不同工具集合”的效果。6.2 攔截器與請求上下文的擴(kuò)展Java SDK 一般會提供在請求鏈路上插入自定義邏輯的擴(kuò)展點(diǎn)如攔截器、過濾器我強(qiáng)烈建議不要錯過這個能力。攔截器適合做幾類橫向邏輯調(diào)用耗時統(tǒng)計和審計日志參數(shù)脫敏比如把請求里的密碼字段提前打碼權(quán)限二次校驗灰度放量。這類邏輯如果寫進(jìn)每個Tool方法里代碼會非常臟。放進(jìn)攔截器后工具方法只關(guān)心業(yè)務(wù)實現(xiàn)橫切邏輯統(tǒng)一處理整體可維護(hù)性提升非常明顯。6.3 不只是 AI 應(yīng)用MCP 的跨界用法回到標(biāo)題的關(guān)鍵詞“Client 和 Server 功能”其實這兩端組合起來的能力邊界遠(yuǎn)不止給大模型當(dāng)工具這么窄。我見過一個有意思的用法把一個“配置查詢服務(wù)”做成 MCP Server然后一個運(yùn)維腳本通過 MCP Client 去讀取配置。這樣做的價值在于所有配置讀取都走同一條協(xié)議鏈路統(tǒng)一了鑒權(quán)、審計、限流。配置系統(tǒng)本身并不知道自己在一個 MCP 生態(tài)里它只是暴露了資源。還有一個用法是把測試數(shù)據(jù)工廠包成 MCP Server測試框架通過 Client 在集成測試?yán)飫討B(tài)造數(shù)。工具就是“創(chuàng)建用戶”“創(chuàng)建訂單”這些方法測試代碼不用再寫一坨工具類而是通過標(biāo)準(zhǔn)協(xié)議去調(diào)用測試數(shù)據(jù)和業(yè)務(wù)邏輯的耦合也被切斷了。這些案例的共同點(diǎn)是當(dāng)一套能力被標(biāo)準(zhǔn)化為可發(fā)現(xiàn)、可調(diào)用、可組合的協(xié)議接口之后消費(fèi)方不一定是模型也可以是腳本、測試框架、運(yùn)維工具。Java SDK 在這條路上最重要的價值就是讓 JVM 生態(tài)的開發(fā)者能以最低的改造成本把自己的服務(wù)升級為可組合的協(xié)議節(jié)點(diǎn)。我自己的經(jīng)驗是第一次跑通 MCP 雙端鏈路時最大的收獲不是“AI 能調(diào)用工具了”而是理解了“標(biāo)準(zhǔn)化連接”這件事本身的價值。工具注冊、資源暴露、采樣回連這些設(shè)計每一條都是沖著“讓系統(tǒng)之間以統(tǒng)一語言協(xié)作”去的。如果你正在做一個有多種消費(fèi)者、需要動態(tài)擴(kuò)展能力的服務(wù)MCP Java SDK 值得認(rèn)真評估。