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