如果你已經(jīng)到了準(zhǔn)備配置 Claude Code MCP 這一步說明你大概率已經(jīng)遇到了那個典型場景Claude Code 很聰明但它的手夠不到你的 MySQL、你的內(nèi)部接口、你打開的瀏覽器標(biāo)簽頁。我最早碰到這個問題是在拿 Claude Code 做自動化測試的時候——它能寫出很漂亮的測試代碼卻沒法自己打開頁面看渲染結(jié)果因?yàn)闉g覽器根本不在它的工具范圍內(nèi)。后來查了一圈才弄明白有個東西叫 MCPModel Context Protocol相當(dāng)于給 Claude Code 加外設(shè)的統(tǒng)一接口。這篇不是從官方文檔里謄出來的說明書是我從零配置、被各種報錯按在地上摩擦之后整理的一份完整記錄覆蓋三塊MCP 到底在 Claude Code 里解決什么問題、我實(shí)際用下來的配置步驟和選型思路、以及那些能卡你一整天的報錯到底應(yīng)該按什么鏈路去查。適合剛接觸 MCP 的 Claude Code 用戶也適合已經(jīng)配了一半但被某個報錯攔住的人。1. MCP在Claude Code里到底解決什么問題1.1 沒有MCP時Claude Code的工具邊界在哪先說清楚一個前提Claude Code 本身不是什么都能做。它能讀寫文件、在終端里跑命令、接管 git 操作本質(zhì)上是一個活在終端環(huán)境里的編程助手。但是你想讓它查一下遠(yuǎn)程數(shù)據(jù)庫里的表結(jié)構(gòu)它做不到因?yàn)樗鼪]有數(shù)據(jù)庫驅(qū)動也沒有連接憑據(jù)只能給你寫一段 Python 腳本讓你復(fù)制到別處自己執(zhí)行。這就是沒有 MCP 之前的典型體驗(yàn)AI 只會說不會動手。它能理解你的訴求卻碰不到那些真實(shí)存在的系統(tǒng)。想讓 Claude 操作瀏覽器、讀取內(nèi)部 API、查詢線上數(shù)據(jù)庫、甚至幫你點(diǎn)兩下運(yùn)維平臺你得先自己解決工具調(diào)用這一層。說白了模型和外部世界之間缺了一道橋。我在實(shí)際使用中最大的感受是Claude Code 的能力天花板不在模型本身而在它能調(diào)用的工具范圍。模型再聰明沒有工具入口它也只能通過生產(chǎn)代碼來間接完成任務(wù)。而 MCP 要解決的恰好就是讓 Claude Code 能安全、標(biāo)準(zhǔn)化地調(diào)用外部工具和數(shù)據(jù)源這件事。1.2 MCP是一個協(xié)議不是一個插件MCP 的全稱是 Model Context ProtocolAnthropic 在 2024 年把它開源了。它的定位是一個開放協(xié)議用來定義 AI 應(yīng)用客戶端和外部工具/數(shù)據(jù)源服務(wù)端之間的交互標(biāo)準(zhǔn)。注意關(guān)鍵詞協(xié)議。它不是一個 npm 包不是某個 IDE 里的插件而是一套消息格式和調(diào)用規(guī)則。你可以把它類比成 USB-C 接口。以前每個外設(shè)都要專門的線鼠標(biāo)一根、鍵盤一根、顯示器一根現(xiàn)在全走同一個接口廠商只要按標(biāo)準(zhǔn)生產(chǎn)設(shè)備插上就能用。MCP 做的事情差不多MCP Server 按統(tǒng)一協(xié)議暴露工具Tools和資源ResourcesClaude Code 作為 MCP 客戶端啟動時發(fā)現(xiàn)這些工具把它們的描述塞進(jìn)上下文然后在對話里按需調(diào)用。它的底層通信是 JSON-RPC 2.0關(guān)鍵消息包括 initialize握手協(xié)商、tools/list獲取工具列表、tools/call調(diào)用具體工具。這套機(jī)制看起來不復(fù)雜但正是因?yàn)樗鼧?biāo)準(zhǔn)化了一個 MCP Server 寫出來之后Claude Code 能用其他支持 MCP 的客戶端也能用不用重復(fù)做集成。1.3 和Function Calling類似但不是一回事很多第一次接觸 MCP 的人會把它和 Function Calling 搞混包括我自己一開始也迷糊。簡單區(qū)分一下Function Calling 是某個模型 API 內(nèi)部的機(jī)制你在 API 請求里傳一段函數(shù)定義模型根據(jù)用戶輸入決定返回哪個函數(shù)和參數(shù)屬于模型側(cè)的能力。MCP 是模型外部的開放標(biāo)準(zhǔn)它不關(guān)心你是哪個模型只規(guī)定客戶端和工具服務(wù)端之間怎么對話。Claude Code 會把連接到的所有 MCP 工具統(tǒng)一轉(zhuǎn)化成模型能理解的工具集合再走模型側(cè)的調(diào)用鏈路。你可以理解成Function Calling 是主板上的固定接口MCP 是通用 USB-C 口外設(shè)只需要按標(biāo)準(zhǔn)做好驅(qū)動主板不用為每個外設(shè)定制接口。能力Function CallingMCP歸屬邊界模型 API 自帶特性開放協(xié)議標(biāo)準(zhǔn)復(fù)用性鎖定單家模型任意 MCP 客戶端可復(fù)用實(shí)現(xiàn)重心開發(fā)者寫函數(shù) Schema服務(wù)端按協(xié)議暴露工具在 Claude Code 中的角色模型調(diào)用工具的底層通道外部工具接入的統(tǒng)一入口1.4 哪些場景值得你花時間配MCP不是所有用法都需要 MCP。如果你只是寫點(diǎn)腳本、整理代碼Claude Code 內(nèi)置能力就夠了。但如果你遇到下面幾類場景MCP 就是繞不開的想讓 Claude Code 操作瀏覽器做端到端測試通過 Playwright MCP 或 Chrome DevTools MCP 實(shí)現(xiàn)想讓它直接查本地或遠(yuǎn)程數(shù)據(jù)庫而不是生成 SQL 讓你手動執(zhí)行想讓它訪問公司內(nèi)部系統(tǒng)、知識庫、監(jiān)控平臺的接口想讓同一套工具能力在不同 AI 客戶端之間共享。我的判斷標(biāo)準(zhǔn)很簡單只要 Claude Code 需要主動訪問某個外部系統(tǒng)并帶回結(jié)果就值得配一個 MCP Server。如果只是它寫好代碼、你去手工運(yùn)行那 MCP 起不到本質(zhì)作用。配置之前先想清楚這個邊界能幫你避免把協(xié)議用成擺設(shè)。2. 配置前必須想明白的三件事傳輸通道、Server來源、權(quán)限邊界2.1 stdio與HTTP/WSS兩條通道MCP 支持兩種傳輸方式這決定你后面怎么配。第一種是 stdioClaude Code 按配置里的 command 啟動一個本地子進(jìn)程父子進(jìn)程之間通過標(biāo)準(zhǔn)輸入輸出傳輸 JSON-RPC 消息。這種方式?jīng)]有網(wǎng)絡(luò)端口暴露server 的聲明周期跟客戶端會話綁定非常適合本地調(diào)試和本機(jī)工具。第二種是 Streamable HTTP / WSSClaude Code 作為 HTTP 客戶端去連一個遠(yuǎn)程地址。你在網(wǎng)上看到的 wss://api.example.com/mcp/?tokenxxx 這類地址就是這種。優(yōu)點(diǎn)是 server 可以部署在服務(wù)器上多人共享缺點(diǎn)是涉及鑒權(quán)、網(wǎng)絡(luò)、延遲、證書排查鏈更長。兩種方式?jīng)]有絕對優(yōu)劣。本地開發(fā)、自己一個人用我優(yōu)先選 stdio團(tuán)隊(duì)要統(tǒng)一接入同一套服務(wù)或者 server 本身需要常駐比如連著一個共享的瀏覽器集群就選遠(yuǎn)程 WSS。選型想清楚了后面配置才不會反復(fù)返工。2.2 MCP Server的三種來源配置 MCP 的另一個前置問題Server 從哪來目前我接觸到的有三類來源。第一類是官方和社區(qū)的現(xiàn)成包比如 modelcontextprotocol/server- 系列、playwright/mcp、文件系統(tǒng)、數(shù)據(jù)庫這類 npm 包直接 npx 啟動即可。第二類是自己用 MCP SDK 寫的Node 或 Python 都行能夠精確對接內(nèi)部業(yè)務(wù)系統(tǒng)。第三類是遠(yuǎn)程托管服務(wù)對方給你一個帶 token 的 WSS 或 HTTPS 地址你只需要配置 URL 就能用比較省事但數(shù)據(jù)會經(jīng)過第三方服務(wù)需要自己權(quán)衡。我個人的習(xí)慣是凡是本機(jī)能力瀏覽器、文件、數(shù)據(jù)庫用第一類內(nèi)部系統(tǒng)用第二類自己寫外部聚合服務(wù)只在確認(rèn)過數(shù)據(jù)流向和權(quán)限邊界之后才用。這個習(xí)慣幫我避開了很多安全上的不確定性。2.3 token、權(quán)限、數(shù)據(jù)流向要提前預(yù)判配置遠(yuǎn)程 WSS server 時token 是訪問憑據(jù)本質(zhì)上是對方確認(rèn)你身份和權(quán)限的證明。你要清楚兩件事第一token 是否有最小權(quán)限設(shè)計能不能做到只讀某些資源而不是全量第二你發(fā)給 Claude Code 的上下文、業(yè)務(wù)數(shù)據(jù)在你調(diào)用遠(yuǎn)程 server 時會被發(fā)送到那個服務(wù)端。如果你無法審查服務(wù)端的處理邏輯就不要把高敏感數(shù)據(jù)交給它。本地 stdio server 同樣有權(quán)限問題。npx -y 會在本機(jī)執(zhí)行第三方包包能讀取當(dāng)前用戶權(quán)限能讀到的所有文件。所以別隨手加一個來源不明的 MCP 包裝之前至少去 npm 頁面看一眼包名、作者、周下載量。市面上已經(jīng)出現(xiàn)過通過偽裝包名做供應(yīng)鏈投毒的先例這一點(diǎn)不是危言聳聽。2.4 本地優(yōu)先還是遠(yuǎn)程優(yōu)先我的選型判斷維度本地 stdio遠(yuǎn)程 WSS/HTTP部署成本零裝依賴就能跑需要服務(wù)器、域名、證書、運(yùn)維數(shù)據(jù)隱私數(shù)據(jù)不出本機(jī)數(shù)據(jù)經(jīng)過網(wǎng)絡(luò)鏈路狀態(tài)保持隨客戶端進(jìn)程銷毀Server 可常駐狀態(tài)可控鑒權(quán)復(fù)雜度低基本靠本地權(quán)限隔離需要 token/API Key 管理適合場景個人開發(fā)調(diào)試、本地工具團(tuán)隊(duì)共享、集中式服務(wù)一個簡單結(jié)論個人場合不要為了看起來高級去部署遠(yuǎn)程 server本地 stdio 夠用且安全邊界更好管理。團(tuán)隊(duì)場景才值得做遠(yuǎn)程部署同時必須把 token 的簽發(fā)、輪換、最小權(quán)限列進(jìn)運(yùn)維清單。3. 從零到跑通Claude Code配MCP的實(shí)操記錄3.1 環(huán)境準(zhǔn)備最少要確認(rèn)的三件事動手之前先確認(rèn)三件事能省掉后面一大半報錯。第一Node.js 版本。大多數(shù)現(xiàn)成 MCP Server 基于 Node SDK 構(gòu)建建議 18 以上最好 20。第二Claude Code 已經(jīng)登錄、版本不要老到?jīng)]有 mcp 子命令。第三本機(jī)能正常訪問 npm registry不然 npx 拉取包會卡在下載階段。這三點(diǎn)屬于基礎(chǔ)環(huán)境很多人報錯半天最后發(fā)現(xiàn)是 Node 版本太低真的不冤。node -v npm -v claude --version claude update claude mcp --help看到 claude mcp --help 輸出了 add、list、get、remove 這些子命令說明環(huán)境支持 MCP 管理可以繼續(xù)。3.2 用CLI添加本地ServerCLI 方式是最快的命令格式是這樣claude mcp add name -- command [args...]scope 參數(shù)控制這個配置在哪些范圍生效。我用得最多的是這兩個--scope user配置到當(dāng)前系統(tǒng)用戶所有 Claude Code 項(xiàng)目都能用--scope project寫入項(xiàng)目級配置適合團(tuán)隊(duì)共享。實(shí)際示例claude mcp add --scope user my-db -- npx -y modelcontextprotocol/server-sqlite claude mcp add --scope project my-api -- node ./mcp-server.js注意第一個例子為什么用 npx -y它會在沒有確認(rèn)步驟的情況下下載并執(zhí)行 npm 包省去交互但代價是首次啟動有下載延遲。第二個例子里 mcp-server.js 是本地文件寫成相對路徑有一定風(fēng)險原因我放到后面報錯部分細(xì)說這里建議直接寫絕對路徑。3.3 配置文件的兩種形態(tài)CLI 命令本質(zhì)上是在幫你改配置文件所以理解配置文件長什么樣很重要。Claude Code 的 MCP 配置和 Claude Desktop 不是同一個文件桌面版用的是 claude_desktop_config.jsonClaude Code 用的是用戶級 ~/.claude.json 和項(xiàng)目級 .mcp.json。我強(qiáng)烈建議項(xiàng)目相關(guān)配置放 .mcp.json因?yàn)樗蓛簟⒖商峤粓F(tuán)隊(duì)倉庫、新同學(xué)拉下來就能用。手動編輯的 JSON 結(jié)構(gòu)長這樣{ mcpServers: { my-db: { command: npx, args: [-y, modelcontextprotocol/server-sqlite], type: stdio }, my-api: { command: node, args: [/absolute/path/to/mcp-server.js], env: { API_KEY: abc123 } } } }字段不多容易錯的是幾個細(xì)節(jié)JSON 里不能寫注釋字段名固定是 command、args、env、typestdio 類型的 server 不要寫 url 字段。type 默認(rèn)就是 stdio但為了可讀性我還是會顯式寫上。env 用來傳環(huán)境變量是給本地 server 注入密鑰的主要方式。3.4 添加遠(yuǎn)程WSS Server并處理好Token遠(yuǎn)程 server 用 CLI 加是這樣claude mcp add --transport http my-remote wss://api.xiaozhi.me/mcp/?tokenxxx--transport http 表示走 HTTP 通道遠(yuǎn)程 server 的 url 就是一個完整的 WSS 地址。對應(yīng)到配置文件里是這樣{ mcpServers: { my-remote: { type: http, url: wss://api.xiaozhi.me/mcp/?tokenxxx } } }有些遠(yuǎn)程 server 要求額外在 Header 里帶鑒權(quán)信息也可以在配置里寫明 URL 和 Header。關(guān)于 token最重要的一條經(jīng)驗(yàn)絕對不要把帶 token 的完整 URL 直接提交進(jìn) git 倉庫。倉庫會流傳到多少人手里你根本控制不住一旦泄露對方就能用你的身份去調(diào)用遠(yuǎn)程能力輕則浪費(fèi)額度重則數(shù)據(jù)被拖走。我自己的做法是用環(huán)境變量或本地不提交的配置文件去動態(tài)注入比如在 env 里放一個 MCP_TOKEN具體注入邏輯看 server 支持哪種方式。3.5 驗(yàn)證、清理、調(diào)試三條命令配置完不是直接開聊就行建議按三步驗(yàn)證claude mcp list claude mcp get name claude mcp remove namelist 會列出所有已配置的 server名字、傳輸方式、狀態(tài)都能看到get 查看某個 server 的詳細(xì)配置確認(rèn)參數(shù)沒寫錯remove 用來清理不再使用的 server。注意MCP 連接是在 Claude Code 會話啟動時建立的所以配置改完之后最好新開一個會話再驗(yàn)證。很多配了但沒生效的問題就是舊會話沒有重新加載配置導(dǎo)致的。3.6 一次完整演示Playwright MCP舉個最容易看到效果的例子用 Playwright MCP 讓 Claude Code 操作瀏覽器。先添加 serverclaude mcp add --scope user playwright -- npx -y playwright/mcplatest然后啟動 Claude Code在會話里輸入類似這樣的指令用 Playwright 打開 example.com把頁面的 main 區(qū)域內(nèi)容總結(jié)給我。如果配置正確Claude 會調(diào)用 browser_navigate 工具打開頁面再調(diào)用相關(guān)工具讀取頁面內(nèi)容。整個過程你在對話里能看到工具調(diào)用的痕跡。我第一次跑通這個場景時直觀感受到的沖擊是AI 真的能看著網(wǎng)頁說話了。這也是理解 MCP 價值的最好入門實(shí)驗(yàn)。4. Claude Code配MCP高頻報錯與完整排查鏈路4.1 Server沒出現(xiàn)在列表里最基礎(chǔ)但最容易被忽略的問題配完之后 claude mcp list 里看不到你要的 server。先不要懷疑配置語法按這個鏈路排查。第一步確認(rèn) scope 范圍。如果你在 /project/a 下用了 --scope local 配置切到 /project/b 當(dāng)然看不到local 是目錄級的。第二步確認(rèn) add 命令真的執(zhí)行成功有些情況是命令中途報錯但你沒注意。第三步確認(rèn)讀的是哪個配置文件手動編輯 .mcp.json 時尤其容易放錯位置。另外注意一個行為同一個 name 重復(fù) add 會覆蓋前面的配置。如果你之前配了個 my-db后面想改命令重新 add 一次原來那個會被覆蓋而不會出現(xiàn)兩條同名配置。這個設(shè)計本身沒什么問題但如果你忘了前面配過排查時容易以為是新增了兩個 server結(jié)果只看到一個會嚇一跳。4.2 本地Server進(jìn)程秒退報錯長這樣MCP server my-db failed to start: Command failed with exit code 1。這類問題根因幾乎都在進(jìn)程根本沒有正常起來。最有效的排查手段只有一招把配置里的命令原樣復(fù)制到終端里手動跑一遍。npx -y modelcontextprotocol/server-sqlite如果手動跑能看到 server 的正常日志說明命令本身沒問題問題出在 Claude Code 拉起的子進(jìn)程環(huán)境和你的終端環(huán)境不一致。如果手動跑就報錯那就是環(huán)境問題Node 版本太低、npm 包沒裝上、入口文件路徑不對。我遇到過的隱蔽情況是 npm 包首次需要下載網(wǎng)絡(luò)超時后 npx 返回非零退出碼Claude Code 就判定啟動失敗手動重跑一遍等下載完成就好了。還有一個容易忽略的點(diǎn)如果你的本地 server 是一個自己寫的 Node 項(xiàng)目配置文件里寫的是 node ./dist/index.js請務(wù)必確認(rèn) Claude Code 的工作目錄。終端里你在項(xiàng)目根目錄手動執(zhí)行沒問題但 Claude Code 拉起子進(jìn)程時的工作目錄不一定是你以為的那個。改用絕對路徑能直接消掉這一類問題。4.3 手動編輯配置導(dǎo)致加載失敗很多人包括我喜歡手改 JSON改完就報 invalid config 或 parse error。常見原因就四個JSON 里多了注釋比如 // 注釋殘留逗號位置不對對象最后一個成員后面加了逗號字段名寫錯command 寫成 cmdargs 寫成 argumentsstdio 類型的 server 里塞了 url 字段。這些看著都是小問題但 MCP 配置解析通常很嚴(yán)格一個標(biāo)點(diǎn)錯了整個 server 就廢了。排查方式是先做 JSON 校驗(yàn)再對照模板逐字段檢查。把配置內(nèi)容復(fù)制到任意 JSON 校驗(yàn)工具里跑一下語法能直接定位是不是標(biāo)點(diǎn)問題。字段檢查的話參照前面我給的示例結(jié)構(gòu)stdio 型有 command、args、envhttp 型有 type、url、headers。兩類別混寫。4.4 遠(yuǎn)程WSS連接失敗的三大類原因遠(yuǎn)程 WSS server 的報錯比本地更煩因?yàn)殒溌防镉芯W(wǎng)絡(luò)和鑒權(quán)兩個額外環(huán)節(jié)。我把它拆成三類來排查。第一類是鑒權(quán)問題表現(xiàn)是 401、403、token invalid。先確認(rèn) token 有沒有過期再確認(rèn) token 是放在 URL 參數(shù)里還是 Header 里放錯位置就是 403最后確認(rèn)服務(wù)方要求的 scheme有些服務(wù)要求 Authorization: Bearer 頭有些要求自定義參數(shù)。第二類是網(wǎng)絡(luò)層問題表現(xiàn)是連接超時、連接重置、SSL 證書錯誤。用 curl 直接試一下 HTTP 化端點(diǎn)能區(qū)分是網(wǎng)絡(luò)不通還是協(xié)議不匹配。curl -X POST https://api.example.com/mcp/?tokenxxx \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:curl,version:1.0}}}第三類是端點(diǎn)類型寫錯了。wss 和 https 不是一回事ws 和 wss 也不是一回事。如果說 MCP server 給的是 wss://api.example.com/mcp/?tokenxxx你在配置里寫成了 https:// 同一個路徑大概率握手會失敗因?yàn)榉?wù)端沒有按 HTTPS 協(xié)議去響應(yīng)。URL 有 token 參數(shù)時尤其要整段復(fù)制別手抖刪掉問號后面的內(nèi)容。如果遠(yuǎn)程 server 走的是 WebSocket 而非普通 HTTP也可以用 wscat 這類通用 WebSocket 客戶端去做消息級測試手動發(fā)送 initialize 消息看有沒有響應(yīng)。這一步能直接判斷 server 本身是否健康、token 是否有效。4.5 配置成功但模型就是不調(diào)用工具這種是最讓人上火的mcp list 能看到 serverget 也正常新會話里模型卻完全不用這些工具跟沒配一樣。我總結(jié)下來有四個原因。第一會話沒有重啟。MCP 工具列表在會話啟動時注入配置中途改完不重啟新工具不會出現(xiàn)在當(dāng)次會話里。第二工具總數(shù)太多把上下文塞爆了。Claude Code 的上下文窗口有限MCP 工具描述也要占空間配了幾十個 server 后模型可能看不到后面那些工具。減少無用的 server或者按項(xiàng)目拆分比硬塞更有效。第三工具描述不清晰。MCP server 返回的工具名、描述、參數(shù) schema 如果寫得很含糊模型不知道什么時候該用。這個多發(fā)生在自建 server 上解決方式是回到 server 代碼里把 description 寫得直白一點(diǎn)。第四觸發(fā)指令不夠明確。別期待模型自己能想到去調(diào)用工具直接說調(diào)用你配置的 Playwright 工具打開 example.com成功率會高很多。4.6 我習(xí)慣的排查順序先分層再動手混亂排查是大忌。我給自己的固定順序是配置層、進(jìn)程層、網(wǎng)絡(luò)層、對話層一層一層往下剝。配置層就是 mcp list、get確認(rèn) server 存在且參數(shù)正確進(jìn)程層是手動跑命令確認(rèn) server 能啟動、能打印日志網(wǎng)絡(luò)層用 curl 或 wscat確認(rèn)端點(diǎn)可通、token 有效對話層最后才查確認(rèn)會話重啟過、指令足夠明確、工具描述沒有歧義。每一步花一兩分鐘比在配置文件里反復(fù)瞎改有效十倍。我過去踩過的坑絕大多數(shù)在前兩層就能找到根因。5. 配置完成之后的邊界情況與工作習(xí)慣5.1 Token的安全使用習(xí)慣配置完成不等于可以放飛。帶 token 的完整 URL 一旦提交進(jìn)依賴倉庫就等于把鑰匙掛在門口。我現(xiàn)在的底線是token 不進(jìn) git、不進(jìn)聊天記錄、不進(jìn)截圖能用環(huán)境變量注入就不用字面量硬編碼能申請最小權(quán)限 token 就不拿全量權(quán)限。遠(yuǎn)程 server 的數(shù)據(jù)流向也要心里有數(shù)調(diào)用它之前問自己一句這個工具需要看我的哪些數(shù)據(jù)這些數(shù)據(jù)能被第三方拿到嗎如果答案讓你猶豫就別配。5.2 Server的狀態(tài)丟失與長連接穩(wěn)定性本地 stdio server 有一個特性容易被忽略它的生命周期和 Claude Code 會話綁定會話重啟后 server 會重新拉起但進(jìn)程里的內(nèi)存狀態(tài)全部丟失。依賴緩存的本地 server 要寫成定時釋放或崩潰可重建不要假設(shè)進(jìn)程一直活著。遠(yuǎn)程 server 也有類似問題服務(wù)端一旦重啟或者網(wǎng)絡(luò)中斷正在進(jìn)行的會話里工具可能直接不可用而且不會自動重連需要重開會話。如果你的遠(yuǎn)程 server 是給團(tuán)隊(duì)用的最好有一個健康檢查和自動拉起機(jī)制否則你就會被同事反復(fù)問怎么又連不上了。5.3 scope與團(tuán)隊(duì)協(xié)作配置協(xié)作場景下我強(qiáng)烈建議用項(xiàng)目級 .mcp.json 而不是用戶級配置。原因很簡單用戶級配置只在你自己的機(jī)器上生效換個人拉下來項(xiàng)目配的還是空白的項(xiàng)目級配置跟代碼一起走新同學(xué) clone 完項(xiàng)目只要跑一條安裝命令MCP server 就齊了。命名也要講規(guī)矩mcp-company-db、mcp-frontend-playwright比 a、b、test1 這種不知道強(qiáng)到哪去了。另外項(xiàng)目 README 里至少寫清楚每個 MCP server 是干什么的、需要什么環(huán)境變量、從哪拿到 license 或 token。配置本身不是文檔人和人之間傳遞的上下文才是團(tuán)隊(duì)協(xié)作里最貴的。5.4 一個非常隱蔽的坑工作目錄假設(shè)最后分享一個讓我翻過車的細(xì)節(jié)。我寫過一個本地 MCP server啟動命令是 node ./mcp-server.js單獨(dú)在終端跑一切正常配置進(jìn) Claude Code 之后一直報文件找不到。排了半天才發(fā)現(xiàn)Claude Code 拉起子進(jìn)程時的工作目錄并不是我項(xiàng)目所在的目錄而是它自己啟動時的上下文目錄。相對路徑在這里全部失效。解決方式有兩個而且我建議兩個都做配置文件的 args 里寫絕對路徑server 代碼內(nèi)部不要用 process.cwd() 去拼文件路徑改用模塊所在目錄 __dirname。這兩個改完這類問題再沒出現(xiàn)過。這個坑很偏但遇到一次就會記住一輩子客戶端幫你啟動的進(jìn)程環(huán)境和你手動啟動的進(jìn)程并不等價。調(diào)試 MCP server 時還有一個壓箱底的方法在 server 的 env 里加上 DEBUG 環(huán)境變量并設(shè)置為通配多數(shù)基于 MCP SDK 的 Node server 都會打印出詳細(xì)的 JSON-RPC 通信日志。配合 Claude Code 自己的調(diào)試模式啟動你能直接看到客戶端和服務(wù)端之間每一句對話。我靠這一招解決過至少三次server 明明啟動了但工具就是不出來的詭異問題。配置 MCP 這件事文檔里寫的是怎么配真正值錢的其實(shí)是配壞了怎么查。希望上面這些記錄能幫你繞開我踩過的那些坑。