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