戰(zhàn)指南：連接Claude Code與外部工具的兩種核心模式)
1. 項(xiàng)目概述Headroom 與兩種核心接入模式最近在折騰 AI 輔助編程工具鏈Headroom 這個(gè)名字出現(xiàn)的頻率越來(lái)越高。簡(jiǎn)單來(lái)說(shuō)Headroom 是一個(gè)旨在連接 Claude Code或 Codex與外部工具、數(shù)據(jù)源的“中間件”或“適配器”平臺(tái)。它本身不直接提供 AI 能力而是扮演一個(gè)“接線員”的角色讓 Claude Code 這個(gè)強(qiáng)大的“大腦”能夠安全、可控地調(diào)用你本地的文件系統(tǒng)、數(shù)據(jù)庫(kù)、API甚至是像藍(lán)湖這樣的設(shè)計(jì)平臺(tái)。這背后的核心協(xié)議是 MCPModel Context Protocol你可以把它理解為 AI 模型與外部世界通信的一種標(biāo)準(zhǔn)化“語(yǔ)言”。為什么需要 Headroom直接讓 Claude Code 訪問(wèn)一切不是更簡(jiǎn)單嗎這里涉及到安全、權(quán)限和可控性。想象一下你不可能讓一個(gè)剛認(rèn)識(shí)的助手即使是 AI直接擁有你電腦的所有權(quán)限。Headroom 就是那個(gè)“管家”它根據(jù)你的配置決定 AI 可以“看到”和“操作”哪些資源。在實(shí)際操作中尤其是團(tuán)隊(duì)協(xié)作或企業(yè)環(huán)境這種可控的接入方式至關(guān)重要。目前Headroom 主要提供了兩種接入 Claude Code 的方式wrap和proxy。這兩種方式聽起來(lái)有點(diǎn)技術(shù)化但理解它們的區(qū)別是順利上手的核心。wrap 模式更像是給 Claude Code “套上”一個(gè)定制的“外殼”讓它天生就具備某些能力而 proxy 模式則是在 Claude Code 和外部資源之間建立一個(gè)“中轉(zhuǎn)站”所有的請(qǐng)求都經(jīng)過(guò)這個(gè)站點(diǎn)的檢查和轉(zhuǎn)發(fā)。選擇哪種方式取決于你的具體需求、技術(shù)棧和對(duì)控制權(quán)的要求。接下來(lái)我會(huì)結(jié)合實(shí)戰(zhàn)把這兩種方式的配置、使用和背后的考量掰開揉碎講清楚。2. 環(huán)境準(zhǔn)備與核心概念澄清在動(dòng)手之前我們需要把基礎(chǔ)環(huán)境搭好并明確幾個(gè)關(guān)鍵概念避免后續(xù)操作中出現(xiàn)“unexpected status 404”或“connection timed out”這類讓人頭疼的錯(cuò)誤。2.1 基礎(chǔ)環(huán)境搭建首先你需要安裝 Claude Code或 Codex。這是使用 Headroom 的前提。根據(jù)你的操作系統(tǒng)安裝步驟略有不同Windows/macOS通常從 Claude 官網(wǎng)下載桌面客戶端安裝即可。安裝后確保你能正常打開并使用 Claude Code 的基本聊天和代碼編寫功能。Linux (如 Ubuntu)可能需要通過(guò)命令行或下載 AppImage 等格式的包進(jìn)行安裝。重點(diǎn)檢查系統(tǒng)依賴特別是網(wǎng)絡(luò)相關(guān)的庫(kù)是否完整。安裝完成后一個(gè)關(guān)鍵的準(zhǔn)備工作是檢查你的網(wǎng)絡(luò)環(huán)境。很多連接問(wèn)題比如“connection timed out: getsockopt”或“if you are behind an http proxy, please configure”都源于此。如果你的公司或網(wǎng)絡(luò)強(qiáng)制使用了 HTTP 代理即常說(shuō)的內(nèi)網(wǎng)代理你需要在系統(tǒng)環(huán)境變量或 Claude Code 的啟動(dòng)參數(shù)中正確配置代理地址。例如在終端中設(shè)置export http_proxyhttp://your-proxy-address:port export https_proxyhttp://your-proxy-address:port然后從該終端啟動(dòng) Claude Code。切記這里討論的“proxy”是網(wǎng)絡(luò)層的 HTTP 代理與 Headroom 的 proxy 接入模式是兩個(gè)完全不同的概念務(wù)必區(qū)分開。2.2 核心組件解析MCP、Server 與工具理解 Headroom 的架構(gòu)需要先搞懂 MCP 和 MCP Server。MCPModel Context Protocol這是由 Anthropic 提出的一種開放協(xié)議。你可以把它想象成 USB 協(xié)議。你的電腦Claude Code有 USB 接口支持 MCP而你的 U 盤、鍵盤外部工具需要遵循 USB 規(guī)范實(shí)現(xiàn) MCP Server才能被電腦識(shí)別和使用。MCP 定義了 AI 模型如何發(fā)現(xiàn)、調(diào)用工具以及如何傳遞數(shù)據(jù)的一套標(biāo)準(zhǔn)。MCP Server這是具體工具或數(shù)據(jù)源提供的服務(wù)端程序。它實(shí)現(xiàn)了 MCP 協(xié)議對(duì)外暴露出一系列“工具”tools。例如一個(gè)“文件系統(tǒng) MCP Server”可以提供“讀取文件”、“寫入文件”等工具一個(gè)“藍(lán)湖 MCP Server”可以提供“獲取設(shè)計(jì)稿列表”、“下載切圖”等工具。Headroom 的核心工作之一就是管理和連接這些 MCP Server。Claude Code / Codex這是 AI 客戶端。它內(nèi)置了對(duì) MCP 客戶端的支持可以通過(guò)配置去發(fā)現(xiàn)和調(diào)用 MCP Server 提供的工具。當(dāng)你說(shuō)“請(qǐng)幫我分析當(dāng)前目錄下的 main.py 文件”Claude Code 就會(huì)通過(guò) MCP 協(xié)議向配置好的文件系統(tǒng) MCP Server 發(fā)送“讀取文件”的請(qǐng)求。Headroom 在這個(gè)生態(tài)中的位置就是幫助 Claude Code 更方便、更安全地連接到各種各樣的 MCP Server無(wú)論是本地運(yùn)行的還是遠(yuǎn)程的。它提供了統(tǒng)一的管理界面和配置方式。3. Wrap 模式實(shí)戰(zhàn)深度集成與定制Wrap 模式我更喜歡稱之為“封裝模式”。它的核心思想是將 Headroom 的功能直接“打包”進(jìn)一個(gè)定制化的 Claude Code 應(yīng)用中。你下載和使用的不再是一個(gè)標(biāo)準(zhǔn)的 Claude Code而是一個(gè)已經(jīng)內(nèi)置了 Headroom 橋接能力和預(yù)配置了某些 MCP Server 的“增強(qiáng)版”客戶端。3.1 Wrap 模式的工作原理與適用場(chǎng)景在這種模式下Headroom 的代碼和邏輯在應(yīng)用構(gòu)建階段就被集成進(jìn)去了。當(dāng)你啟動(dòng)這個(gè)定制版應(yīng)用時(shí)Headroom 服務(wù)也隨之啟動(dòng)并自動(dòng)按照預(yù)設(shè)的配置去連接指定的 MCP Server。對(duì)用戶而言整個(gè)過(guò)程是無(wú)感的打開即用。適用場(chǎng)景團(tuán)隊(duì)標(biāo)準(zhǔn)化部署開發(fā)團(tuán)隊(duì)或公司希望為所有成員提供一套開箱即用、預(yù)置了公司內(nèi)部工具如內(nèi)部 API 文檔查詢、項(xiàng)目管理系統(tǒng)連接的 AI 編程助手。簡(jiǎn)化用戶操作面向非技術(shù)背景或追求極致簡(jiǎn)便的用戶他們不希望處理任何配置問(wèn)題。分發(fā)特定工具集如果你想將一個(gè)搭配了特定 MCP 工具鏈例如專為前端開發(fā)配置了藍(lán)湖 MCP、Chrome DevTools MCP的 Claude Code 打包分發(fā)給特定人群wrap 模式是最佳選擇。它的優(yōu)點(diǎn)很明顯用戶體驗(yàn)無(wú)縫無(wú)需額外配置啟動(dòng)速度快。缺點(diǎn)也很突出靈活性差。用戶無(wú)法自行添加或刪除 MCP Server所有能力在打包時(shí)就已經(jīng)固定。要更新工具集必須重新分發(fā)新的應(yīng)用版本。3.2 構(gòu)建與使用 Wrap 版本目前Headroom 官方可能提供一些預(yù)構(gòu)建的 wrap 版本但更常見的做法是開發(fā)者根據(jù)自己的需求進(jìn)行定制構(gòu)建。這通常涉及以下步驟獲取 Claude Code 源碼或構(gòu)建模板你需要有 Claude Code 的源代碼或者 Headroom 提供的專門用于 wrap 的模板項(xiàng)目。集成 Headroom 庫(kù)在項(xiàng)目的依賴文件中如package.json對(duì)于 JS 項(xiàng)目添加 Headroom 的客戶端庫(kù)。編寫集成代碼在應(yīng)用初始化代碼中導(dǎo)入并啟動(dòng) Headroom 客戶端并傳入你的 MCP Server 配置列表。這個(gè)配置列表是一個(gè)數(shù)組定義了每個(gè) Server 的類型、啟動(dòng)命令或連接地址。// 示例性代碼展示概念 import { HeadroomClient } from headroomai/sdk; const headroom new HeadroomClient(); await headroom.addServer({ name: filesystem, type: stdio, command: npx, // 使用 npx 運(yùn)行一個(gè)本地的 MCP Server args: [-y, modelcontextprotocol/server-filesystem, /path/to/allowd/dir] }); await headroom.addServer({ name: brave-search, type: sse, // 連接一個(gè)遠(yuǎn)程的 SSE 類型 Server url: https://your-brave-search-mcp-server.com/sse }); await headroom.connectToCodex(); // 連接到 Claude Code 的核心構(gòu)建與分發(fā)使用 Electron、Tauri 或其他桌面應(yīng)用框架將整個(gè)項(xiàng)目打包成可執(zhí)行文件.exe, .dmg, .AppImage然后分發(fā)給最終用戶。對(duì)于使用者來(lái)說(shuō)過(guò)程非常簡(jiǎn)單下載這個(gè)定制版應(yīng)用雙擊打開。你會(huì)發(fā)現(xiàn)在 Claude Code 的界面中可能多了一個(gè)“工具”面板里面直接列出了可用的文件操作、搜索等功能無(wú)需任何設(shè)置即可使用。注意構(gòu)建 wrap 版本需要一定的前端/桌面應(yīng)用開發(fā)經(jīng)驗(yàn)。如果你只是個(gè)人用戶想快速嘗試多種 MCP 工具proxy 模式可能更合適。4. Proxy 模式實(shí)戰(zhàn)靈活的中轉(zhuǎn)與配置Proxy 模式我稱之為“網(wǎng)關(guān)模式”或“中轉(zhuǎn)模式”。這是目前個(gè)人用戶和小團(tuán)隊(duì)最常用、最靈活的方式。在這種模式下Headroom 作為一個(gè)獨(dú)立的服務(wù)進(jìn)程運(yùn)行在你的電腦上。標(biāo)準(zhǔn)的 Claude Code 客戶端通過(guò)網(wǎng)絡(luò)連接到這個(gè) Headroom 服務(wù)Headroom 再負(fù)責(zé)去管理和調(diào)用后端的各個(gè) MCP Server。你可以把 Headroom Proxy 想象成你家中的路由器。你的手機(jī)、電腦Claude Code都連接到這個(gè)路由器路由器后面則連接著打印機(jī)、NAS、智能燈各種 MCP Server。設(shè)備不需要知道打印機(jī)具體在哪只需要告訴路由器“我要打印”路由器會(huì)負(fù)責(zé)轉(zhuǎn)發(fā)這個(gè)請(qǐng)求。4.1 Proxy 模式架構(gòu)詳解工作流程如下啟動(dòng) Headroom 服務(wù)你在終端運(yùn)行一條命令啟動(dòng) Headroom 的代理服務(wù)。這個(gè)服務(wù)會(huì)監(jiān)聽一個(gè)本地端口例如localhost:3000。配置 Claude Code在 Claude Code 的設(shè)置中找到 MCP 或 Advanced 設(shè)置項(xiàng)填入 Headroom 服務(wù)的地址如http://localhost:3000/sse。這相當(dāng)于告訴 Claude Code“以后你要找工具都去這個(gè)地址問(wèn)”。Headroom 配置 MCP Server你通過(guò) Headroom 的配置文件通常是headroom.config.json或config.yaml定義需要管理的 MCP Server 列表。每個(gè) Server 可以是通過(guò)命令行啟動(dòng)的本地進(jìn)程stdio也可以是遠(yuǎn)程的 HTTP/SSE 服務(wù)。交互過(guò)程當(dāng)你在 Claude Code 中提出需求如“搜索最新的 React 資訊”Claude Code 會(huì)將這個(gè)請(qǐng)求發(fā)送給localhost:3000。Headroom 收到請(qǐng)求后查看自己的配置發(fā)現(xiàn)有一個(gè)brave-search的 MCP Server 可以提供搜索工具于是它將請(qǐng)求轉(zhuǎn)發(fā)給這個(gè) Server。Server 執(zhí)行搜索并返回結(jié)果Headroom 再將結(jié)果原路返回給 Claude Code最終呈現(xiàn)給你。4.2 一步步配置 Proxy 模式讓我們以一個(gè)典型的前端開發(fā)者環(huán)境為例配置一個(gè)包含文件系統(tǒng)和 Brave 搜索的 Headroom Proxy。步驟 1安裝 Headroom通常 Headroom 是一個(gè) npm 包或獨(dú)立的二進(jìn)制文件。我們以 npm 全局安裝為例npm install -g headroomai/cli安裝后可以使用headroom --version檢查是否成功。步驟 2創(chuàng)建配置文件在你的用戶目錄如~/.config/headroom/或項(xiàng)目根目錄下創(chuàng)建一個(gè)headroom.config.json文件。{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/YourName/Projects // 允許訪問(wèn)的項(xiàng)目目錄限制范圍保證安全 ] }, braveSearch: { command: npx, args: [ -y, modelcontextprotocol/server-brave-search ], env: { BRAVE_API_KEY: your_brave_search_api_key_here // 需要去 Brave 官網(wǎng)申請(qǐng) } } // 你可以繼續(xù)添加更多如 figma: { ... }, github: { ... } } }這個(gè)配置定義了兩個(gè) MCP Server。filesystem使用 stdio 方式啟動(dòng)一個(gè)本地進(jìn)程braveSearch同理但需要注入環(huán)境變量BRAVE_API_KEY。步驟 3啟動(dòng) Headroom 服務(wù)在終端運(yùn)行headroom proxy如果配置文件不在默認(rèn)位置需要指定headroom proxy --config ./path/to/your/headroom.config.json服務(wù)啟動(dòng)后你會(huì)看到日志輸出顯示服務(wù)正在監(jiān)聽某個(gè)地址例如Server running on http://localhost:3000并且會(huì)顯示已成功加載的 MCP Server。步驟 4配置 Claude Code打開 Claude Code 桌面應(yīng)用。進(jìn)入設(shè)置Settings。找到 “Advanced” 或 “Developer” 或 “MCP” 設(shè)置部分。尋找 “MCP Servers” 或 “External Tools” 的配置項(xiàng)。這里通常是一個(gè) JSON 配置框。輸入以下配置將 Claude Code 指向本地運(yùn)行的 Headroom 服務(wù)[ { name: headroom-gateway, type: sse, url: http://localhost:3000/sse } ]保存設(shè)置并重啟 Claude Code。步驟 5驗(yàn)證與使用重啟后在 Claude Code 的聊天界面你可以嘗試輸入“請(qǐng)列出我 Projects 目錄下的所有文件?！?如果配置成功Claude Code 會(huì)調(diào)用 filesystem 工具并返回目錄列表。你也可以問(wèn)“搜索一下今天關(guān)于 Headroom 的最新消息?！?它會(huì)調(diào)用 braveSearch 工具并返回搜索結(jié)果。4.3 Proxy 模式的高級(jí)配置與故障排查動(dòng)態(tài)添加 ServerHeadroom Proxy 的優(yōu)勢(shì)在于你不需要重啟服務(wù)來(lái)更新配置。某些 Headroom 實(shí)現(xiàn)支持通過(guò)管理 API 動(dòng)態(tài)添加或移除 MCP Server這為工具鏈的熱插拔提供了可能。安全配置在配置文件中務(wù)必注意為文件系統(tǒng) Server 指定明確的、最小必要的目錄路徑不要使用根目錄/。API 密鑰等敏感信息不要硬編碼在配置文件中應(yīng)使用環(huán)境變量如上面的env字段或系統(tǒng)的密鑰管理服務(wù)。常見問(wèn)題與排查FAQClaude Code 提示 “unexpected status 404 not found”原因Claude Code 連接 Headroom 的 URL 不正確或者 Headroom 服務(wù)沒(méi)有正常運(yùn)行。排查首先在瀏覽器訪問(wèn)http://localhost:3000或你配置的端口看 Headroom 的服務(wù)狀態(tài)頁(yè)是否正常顯示。然后檢查 Claude Code 配置中的url是否精確到/sse端點(diǎn)。提示 “unexpected status 401 unauthorized” 或 “402 payment required”原因這通常是 Headroom 服務(wù)在連接某個(gè)遠(yuǎn)程 MCP Server 時(shí)該 Server 返回的認(rèn)證或付費(fèi)錯(cuò)誤。例如你配置的搜索 Server 的 API 密鑰無(wú)效或余額不足。排查查看 Headroom 啟動(dòng)時(shí)的日志找到具體是哪個(gè) Server 報(bào)錯(cuò)。檢查該 Server 的配置尤其是 API 密鑰等認(rèn)證信息是否正確且有效。提示 “connection timed out”原因網(wǎng)絡(luò)連接問(wèn)題?？赡苁?Headroom 服務(wù)未啟動(dòng)防火墻阻止了端口訪問(wèn)或者 Claude Code 被系統(tǒng)級(jí) HTTP 代理阻擋。排查運(yùn)行curl http://localhost:3000測(cè)試服務(wù)是否可達(dá)。確認(rèn) Claude Code 是否運(yùn)行在需要特殊代理的網(wǎng)絡(luò)環(huán)境下并正確配置了系統(tǒng)或 Claude Code 的 HTTP 代理設(shè)置文章開頭環(huán)境準(zhǔn)備部分已提及。工具調(diào)用無(wú)反應(yīng)或報(bào)錯(cuò)原因MCP Server 本身啟動(dòng)失敗或命令路徑錯(cuò)誤。排查仔細(xì)查看 Headroom 的啟動(dòng)日志確認(rèn)每個(gè)mcpServers下的command是否能在終端中直接運(yùn)行。例如手動(dòng)執(zhí)行npx -y modelcontextprotocol/server-filesystem /tmp看能否成功啟動(dòng)一個(gè)文件系統(tǒng) Server。5. 兩種模式對(duì)比與選型建議經(jīng)過(guò)上面的實(shí)戰(zhàn)你應(yīng)該對(duì) wrap 和 proxy 兩種模式有了直觀的感受。下面用一個(gè)表格來(lái)系統(tǒng)對(duì)比一下方便你根據(jù)實(shí)際情況做出選擇特性維度Wrap (封裝) 模式Proxy (代理) 模式集成度高。與 Claude Code 客戶端深度集成一體分發(fā)。低。獨(dú)立進(jìn)程通過(guò)標(biāo)準(zhǔn) MCP 協(xié)議與 Claude Code 通信。用戶配置無(wú)需配置。開箱即用能力預(yù)置。需要配置。需手動(dòng)啟動(dòng)服務(wù)并在 Claude Code 中設(shè)置連接。靈活性低。功能在構(gòu)建時(shí)固定用戶無(wú)法修改。高。通過(guò)修改配置文件可隨時(shí)增刪 MCP Server無(wú)需更新客戶端。更新復(fù)雜度高。需要重新構(gòu)建并分發(fā)整個(gè)客戶端。低。更新 Headroom 服務(wù)端或配置文件即可客戶端不變。適用場(chǎng)景1. 企業(yè)/團(tuán)隊(duì)標(biāo)準(zhǔn)化部署2. 面向非技術(shù)用戶的成品工具3. 特定垂直領(lǐng)域的打包方案1. 開發(fā)者個(gè)人使用2. 需要頻繁嘗試新 MCP 工具的場(chǎng)景3. 工具鏈需要?jiǎng)討B(tài)調(diào)整的環(huán)境技術(shù)門檻高。需要桌面應(yīng)用開發(fā)和構(gòu)建知識(shí)。中。主要需要理解配置文件和網(wǎng)絡(luò)調(diào)試。性能通常更好因?yàn)榧稍谕粋€(gè)進(jìn)程內(nèi)通信開銷小。略有開銷因?yàn)槎嗔艘淮尉W(wǎng)絡(luò)轉(zhuǎn)發(fā)本地回環(huán)網(wǎng)絡(luò)延遲極低。選型建議如果你是獨(dú)立開發(fā)者或小團(tuán)隊(duì)強(qiáng)烈建議從Proxy 模式開始。它提供了最大的靈活性和試錯(cuò)空間你可以像搭積木一樣隨時(shí)更換、添加新的 MCP 工具如今天加個(gè) GitHub Server明天加個(gè) Playwright 測(cè)試 Server而不用動(dòng)輒重新安裝 Claude Code。如果你是為一個(gè)大型技術(shù)團(tuán)隊(duì)或公司構(gòu)建統(tǒng)一的 AI 編程環(huán)境并且希望做到集中管控、開箱即用那么投入資源構(gòu)建一個(gè)定制的Wrap 模式客戶端是值得的。這能極大降低團(tuán)隊(duì)成員的配置成本并確保環(huán)境一致性。如果你是一個(gè)工具開發(fā)者想要分發(fā)一個(gè)包含你獨(dú)家 MCP 工具的 Claude Code 給用戶Wrap 模式能提供最干凈、最專業(yè)的用戶體驗(yàn)。6. 拓展構(gòu)建與連接自定義 MCP ServerHeadroom 的真正威力在于它能連接豐富的 MCP Server 生態(tài)。除了使用社區(qū)已有的 Server如 filesystem, brave-search你完全可以為自己公司的內(nèi)部系統(tǒng)或某個(gè)特定工具構(gòu)建一個(gè) MCP Server。6.1 MCP Server 開發(fā)概覽開發(fā)一個(gè) MCP Server 并不復(fù)雜核心是實(shí)現(xiàn) MCP 協(xié)議規(guī)定的幾個(gè)接口。協(xié)議支持多種傳輸方式最常見的是stdio標(biāo)準(zhǔn)輸入輸出和sseServer-Sent Events。stdio 適合本地命令行工具sse 適合遠(yuǎn)程 HTTP 服務(wù)。一個(gè)最簡(jiǎn)單的 MCP Server以 Node.js 為例結(jié)構(gòu)如下// server.js import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; // 1. 創(chuàng)建 Server 實(shí)例 const server new Server( { name: my-custom-tool-server, version: 1.0.0, }, { capabilities: { tools: {}, // 聲明本 Server 提供工具 }, } ); // 2. 定義工具 server.setRequestHandler(tools/list, async () { return { tools: [ { name: get_weather, description: 獲取指定城市的天氣, inputSchema: { type: object, properties: { city: { type: string, description: 城市名 } }, required: [city] } } ] }; }); server.setRequestHandler(tools/call, async (request) { if (request.params.name get_weather) { const city request.params.arguments?.city; // 這里實(shí)現(xiàn)實(shí)際的天氣查詢邏輯比如調(diào)用一個(gè)天氣 API return { content: [{ type: text, text: 查詢到城市 ${city} 的天氣是晴朗25度。 }], }; } throw new Error(未知的工具); }); // 3. 啟動(dòng)傳輸層這里使用 stdio const transport new StdioServerTransport(); await server.connect(transport); console.error(My MCP Server 已啟動(dòng) (stdio));這個(gè) Server 定義了一個(gè)get_weather工具。你可以使用npx來(lái)運(yùn)行它node server.js。它會(huì)在 stdio 上等待連接。6.2 將自定義 Server 接入 Headroom Proxy開發(fā)完成后如何讓 Claude Code 通過(guò) Headroom 使用它非常簡(jiǎn)單只需在headroom.config.json中添加一項(xiàng)配置{ mcpServers: { myWeather: { command: node, args: [/absolute/path/to/your/server.js] } } }重啟 Headroom 服務(wù)它就會(huì)啟動(dòng)你的自定義 Server。之后在 Claude Code 中你就可以直接說(shuō)“使用 get_weather 工具查詢北京的天氣?！?Claude Code 會(huì)通過(guò) Headroom 調(diào)用你的 Server并返回結(jié)果。對(duì)于遠(yuǎn)程的 SSE Server配置更簡(jiǎn)單{ mcpServers: { remoteTools: { type: sse, url: https://your-remote-mcp-server.com/sse } } }6.3 生態(tài)與社區(qū)工具探索目前 MCP 生態(tài)正在快速增長(zhǎng)社區(qū)已經(jīng)有很多優(yōu)秀的 MCP Server 可以直接使用極大地?cái)U(kuò)展了 Claude Code 的能力數(shù)據(jù)與搜索brave-search-mcp,tavily-mcp提供網(wǎng)絡(luò)搜索能力。開發(fā)工具server-filesystem文件操作server-githubGitHub 交互playwright-mcp瀏覽器自動(dòng)化chrome-devtools-mcp調(diào)試。設(shè)計(jì)工具figma-mcp,藍(lán)湖-mcp需自行尋找或開發(fā)用于連接設(shè)計(jì)平臺(tái)。專業(yè)工具ida-mcp反匯編工具 IDA Pro 集成burp-mcp安全測(cè)試工具 Burp Suite 集成。你可以在 npm 上搜索mcp-server-*或*-mcp或者在 Anthropic 的官方 MCP 倉(cāng)庫(kù)中尋找靈感。將這些工具通過(guò) Headroom 聚合起來(lái)你就能打造出一個(gè)無(wú)比強(qiáng)大的、專屬的 AI 編程工作站。 Headroom實(shí)戰(zhàn)指南：連接Claude Code與外部工具的兩種核心模式
1. 項(xiàng)目概述Headroom 與兩種核心接入模式最近在折騰 AI 輔助編程工具鏈Headroom 這個(gè)名字出現(xiàn)的頻率越來(lái)越高。簡(jiǎn)單來(lái)說(shuō)Headroom 是一個(gè)旨在連接 Claude Code或 Codex與外部工具、數(shù)據(jù)源的“中間件”或“適配器”平臺(tái)。它本身不直接提供 AI 能力而是扮演一個(gè)“接線員”的角色讓 Claude Code 這個(gè)強(qiáng)大的“大腦”能夠安全、可控地調(diào)用你本地的文件系統(tǒng)、數(shù)據(jù)庫(kù)、API甚至是像藍(lán)湖這樣的設(shè)計(jì)平臺(tái)。這背后的核心協(xié)議是 MCPModel Context Protocol你可以把它理解為 AI 模型與外部世界通信的一種標(biāo)準(zhǔn)化“語(yǔ)言”。為什么需要 Headroom直接讓 Claude Code 訪問(wèn)一切不是更簡(jiǎn)單嗎這里涉及到安全、權(quán)限和可控性。想象一下你不可能讓一個(gè)剛認(rèn)識(shí)的助手即使是 AI直接擁有你電腦的所有權(quán)限。Headroom 就是那個(gè)“管家”它根據(jù)你的配置決定 AI 可以“看到”和“操作”哪些資源。在實(shí)際操作中尤其是團(tuán)隊(duì)協(xié)作或企業(yè)環(huán)境這種可控的接入方式至關(guān)重要。目前Headroom 主要提供了兩種接入 Claude Code 的方式wrap和proxy。這兩種方式聽起來(lái)有點(diǎn)技術(shù)化但理解它們的區(qū)別是順利上手的核心。wrap 模式更像是給 Claude Code “套上”一個(gè)定制的“外殼”讓它天生就具備某些能力而 proxy 模式則是在 Claude Code 和外部資源之間建立一個(gè)“中轉(zhuǎn)站”所有的請(qǐng)求都經(jīng)過(guò)這個(gè)站點(diǎn)的檢查和轉(zhuǎn)發(fā)。選擇哪種方式取決于你的具體需求、技術(shù)棧和對(duì)控制權(quán)的要求。接下來(lái)我會(huì)結(jié)合實(shí)戰(zhàn)把這兩種方式的配置、使用和背后的考量掰開揉碎講清楚。2. 環(huán)境準(zhǔn)備與核心概念澄清在動(dòng)手之前我們需要把基礎(chǔ)環(huán)境搭好并明確幾個(gè)關(guān)鍵概念避免后續(xù)操作中出現(xiàn)“unexpected status 404”或“connection timed out”這類讓人頭疼的錯(cuò)誤。2.1 基礎(chǔ)環(huán)境搭建首先你需要安裝 Claude Code或 Codex。這是使用 Headroom 的前提。根據(jù)你的操作系統(tǒng)安裝步驟略有不同Windows/macOS通常從 Claude 官網(wǎng)下載桌面客戶端安裝即可。安裝后確保你能正常打開并使用 Claude Code 的基本聊天和代碼編寫功能。Linux (如 Ubuntu)可能需要通過(guò)命令行或下載 AppImage 等格式的包進(jìn)行安裝。重點(diǎn)檢查系統(tǒng)依賴特別是網(wǎng)絡(luò)相關(guān)的庫(kù)是否完整。安裝完成后一個(gè)關(guān)鍵的準(zhǔn)備工作是檢查你的網(wǎng)絡(luò)環(huán)境。很多連接問(wèn)題比如“connection timed out: getsockopt”或“if you are behind an http proxy, please configure”都源于此。如果你的公司或網(wǎng)絡(luò)強(qiáng)制使用了 HTTP 代理即常說(shuō)的內(nèi)網(wǎng)代理你需要在系統(tǒng)環(huán)境變量或 Claude Code 的啟動(dòng)參數(shù)中正確配置代理地址。例如在終端中設(shè)置export http_proxyhttp://your-proxy-address:port export https_proxyhttp://your-proxy-address:port然后從該終端啟動(dòng) Claude Code。切記這里討論的“proxy”是網(wǎng)絡(luò)層的 HTTP 代理與 Headroom 的 proxy 接入模式是兩個(gè)完全不同的概念務(wù)必區(qū)分開。2.2 核心組件解析MCP、Server 與工具理解 Headroom 的架構(gòu)需要先搞懂 MCP 和 MCP Server。MCPModel Context Protocol這是由 Anthropic 提出的一種開放協(xié)議。你可以把它想象成 USB 協(xié)議。你的電腦Claude Code有 USB 接口支持 MCP而你的 U 盤、鍵盤外部工具需要遵循 USB 規(guī)范實(shí)現(xiàn) MCP Server才能被電腦識(shí)別和使用。MCP 定義了 AI 模型如何發(fā)現(xiàn)、調(diào)用工具以及如何傳遞數(shù)據(jù)的一套標(biāo)準(zhǔn)。MCP Server這是具體工具或數(shù)據(jù)源提供的服務(wù)端程序。它實(shí)現(xiàn)了 MCP 協(xié)議對(duì)外暴露出一系列“工具”tools。例如一個(gè)“文件系統(tǒng) MCP Server”可以提供“讀取文件”、“寫入文件”等工具一個(gè)“藍(lán)湖 MCP Server”可以提供“獲取設(shè)計(jì)稿列表”、“下載切圖”等工具。Headroom 的核心工作之一就是管理和連接這些 MCP Server。Claude Code / Codex這是 AI 客戶端。它內(nèi)置了對(duì) MCP 客戶端的支持可以通過(guò)配置去發(fā)現(xiàn)和調(diào)用 MCP Server 提供的工具。當(dāng)你說(shuō)“請(qǐng)幫我分析當(dāng)前目錄下的 main.py 文件”Claude Code 就會(huì)通過(guò) MCP 協(xié)議向配置好的文件系統(tǒng) MCP Server 發(fā)送“讀取文件”的請(qǐng)求。Headroom 在這個(gè)生態(tài)中的位置就是幫助 Claude Code 更方便、更安全地連接到各種各樣的 MCP Server無(wú)論是本地運(yùn)行的還是遠(yuǎn)程的。它提供了統(tǒng)一的管理界面和配置方式。3. Wrap 模式實(shí)戰(zhàn)深度集成與定制Wrap 模式我更喜歡稱之為“封裝模式”。它的核心思想是將 Headroom 的功能直接“打包”進(jìn)一個(gè)定制化的 Claude Code 應(yīng)用中。你下載和使用的不再是一個(gè)標(biāo)準(zhǔn)的 Claude Code而是一個(gè)已經(jīng)內(nèi)置了 Headroom 橋接能力和預(yù)配置了某些 MCP Server 的“增強(qiáng)版”客戶端。3.1 Wrap 模式的工作原理與適用場(chǎng)景在這種模式下Headroom 的代碼和邏輯在應(yīng)用構(gòu)建階段就被集成進(jìn)去了。當(dāng)你啟動(dòng)這個(gè)定制版應(yīng)用時(shí)Headroom 服務(wù)也隨之啟動(dòng)并自動(dòng)按照預(yù)設(shè)的配置去連接指定的 MCP Server。對(duì)用戶而言整個(gè)過(guò)程是無(wú)感的打開即用。適用場(chǎng)景團(tuán)隊(duì)標(biāo)準(zhǔn)化部署開發(fā)團(tuán)隊(duì)或公司希望為所有成員提供一套開箱即用、預(yù)置了公司內(nèi)部工具如內(nèi)部 API 文檔查詢、項(xiàng)目管理系統(tǒng)連接的 AI 編程助手。簡(jiǎn)化用戶操作面向非技術(shù)背景或追求極致簡(jiǎn)便的用戶他們不希望處理任何配置問(wèn)題。分發(fā)特定工具集如果你想將一個(gè)搭配了特定 MCP 工具鏈例如專為前端開發(fā)配置了藍(lán)湖 MCP、Chrome DevTools MCP的 Claude Code 打包分發(fā)給特定人群wrap 模式是最佳選擇。它的優(yōu)點(diǎn)很明顯用戶體驗(yàn)無(wú)縫無(wú)需額外配置啟動(dòng)速度快。缺點(diǎn)也很突出靈活性差。用戶無(wú)法自行添加或刪除 MCP Server所有能力在打包時(shí)就已經(jīng)固定。要更新工具集必須重新分發(fā)新的應(yīng)用版本。3.2 構(gòu)建與使用 Wrap 版本目前Headroom 官方可能提供一些預(yù)構(gòu)建的 wrap 版本但更常見的做法是開發(fā)者根據(jù)自己的需求進(jìn)行定制構(gòu)建。這通常涉及以下步驟獲取 Claude Code 源碼或構(gòu)建模板你需要有 Claude Code 的源代碼或者 Headroom 提供的專門用于 wrap 的模板項(xiàng)目。集成 Headroom 庫(kù)在項(xiàng)目的依賴文件中如package.json對(duì)于 JS 項(xiàng)目添加 Headroom 的客戶端庫(kù)。編寫集成代碼在應(yīng)用初始化代碼中導(dǎo)入并啟動(dòng) Headroom 客戶端并傳入你的 MCP Server 配置列表。這個(gè)配置列表是一個(gè)數(shù)組定義了每個(gè) Server 的類型、啟動(dòng)命令或連接地址。// 示例性代碼展示概念 import { HeadroomClient } from headroomai/sdk; const headroom new HeadroomClient(); await headroom.addServer({ name: filesystem, type: stdio, command: npx, // 使用 npx 運(yùn)行一個(gè)本地的 MCP Server args: [-y, modelcontextprotocol/server-filesystem, /path/to/allowd/dir] }); await headroom.addServer({ name: brave-search, type: sse, // 連接一個(gè)遠(yuǎn)程的 SSE 類型 Server url: https://your-brave-search-mcp-server.com/sse }); await headroom.connectToCodex(); // 連接到 Claude Code 的核心構(gòu)建與分發(fā)使用 Electron、Tauri 或其他桌面應(yīng)用框架將整個(gè)項(xiàng)目打包成可執(zhí)行文件.exe, .dmg, .AppImage然后分發(fā)給最終用戶。對(duì)于使用者來(lái)說(shuō)過(guò)程非常簡(jiǎn)單下載這個(gè)定制版應(yīng)用雙擊打開。你會(huì)發(fā)現(xiàn)在 Claude Code 的界面中可能多了一個(gè)“工具”面板里面直接列出了可用的文件操作、搜索等功能無(wú)需任何設(shè)置即可使用。注意構(gòu)建 wrap 版本需要一定的前端/桌面應(yīng)用開發(fā)經(jīng)驗(yàn)。如果你只是個(gè)人用戶想快速嘗試多種 MCP 工具proxy 模式可能更合適。4. Proxy 模式實(shí)戰(zhàn)靈活的中轉(zhuǎn)與配置Proxy 模式我稱之為“網(wǎng)關(guān)模式”或“中轉(zhuǎn)模式”。這是目前個(gè)人用戶和小團(tuán)隊(duì)最常用、最靈活的方式。在這種模式下Headroom 作為一個(gè)獨(dú)立的服務(wù)進(jìn)程運(yùn)行在你的電腦上。標(biāo)準(zhǔn)的 Claude Code 客戶端通過(guò)網(wǎng)絡(luò)連接到這個(gè) Headroom 服務(wù)Headroom 再負(fù)責(zé)去管理和調(diào)用后端的各個(gè) MCP Server。你可以把 Headroom Proxy 想象成你家中的路由器。你的手機(jī)、電腦Claude Code都連接到這個(gè)路由器路由器后面則連接著打印機(jī)、NAS、智能燈各種 MCP Server。設(shè)備不需要知道打印機(jī)具體在哪只需要告訴路由器“我要打印”路由器會(huì)負(fù)責(zé)轉(zhuǎn)發(fā)這個(gè)請(qǐng)求。4.1 Proxy 模式架構(gòu)詳解工作流程如下啟動(dòng) Headroom 服務(wù)你在終端運(yùn)行一條命令啟動(dòng) Headroom 的代理服務(wù)。這個(gè)服務(wù)會(huì)監(jiān)聽一個(gè)本地端口例如localhost:3000。配置 Claude Code在 Claude Code 的設(shè)置中找到 MCP 或 Advanced 設(shè)置項(xiàng)填入 Headroom 服務(wù)的地址如http://localhost:3000/sse。這相當(dāng)于告訴 Claude Code“以后你要找工具都去這個(gè)地址問(wèn)”。Headroom 配置 MCP Server你通過(guò) Headroom 的配置文件通常是headroom.config.json或config.yaml定義需要管理的 MCP Server 列表。每個(gè) Server 可以是通過(guò)命令行啟動(dòng)的本地進(jìn)程stdio也可以是遠(yuǎn)程的 HTTP/SSE 服務(wù)。交互過(guò)程當(dāng)你在 Claude Code 中提出需求如“搜索最新的 React 資訊”Claude Code 會(huì)將這個(gè)請(qǐng)求發(fā)送給localhost:3000。Headroom 收到請(qǐng)求后查看自己的配置發(fā)現(xiàn)有一個(gè)brave-search的 MCP Server 可以提供搜索工具于是它將請(qǐng)求轉(zhuǎn)發(fā)給這個(gè) Server。Server 執(zhí)行搜索并返回結(jié)果Headroom 再將結(jié)果原路返回給 Claude Code最終呈現(xiàn)給你。4.2 一步步配置 Proxy 模式讓我們以一個(gè)典型的前端開發(fā)者環(huán)境為例配置一個(gè)包含文件系統(tǒng)和 Brave 搜索的 Headroom Proxy。步驟 1安裝 Headroom通常 Headroom 是一個(gè) npm 包或獨(dú)立的二進(jìn)制文件。我們以 npm 全局安裝為例npm install -g headroomai/cli安裝后可以使用headroom --version檢查是否成功。步驟 2創(chuàng)建配置文件在你的用戶目錄如~/.config/headroom/或項(xiàng)目根目錄下創(chuàng)建一個(gè)headroom.config.json文件。{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/YourName/Projects // 允許訪問(wèn)的項(xiàng)目目錄限制范圍保證安全 ] }, braveSearch: { command: npx, args: [ -y, modelcontextprotocol/server-brave-search ], env: { BRAVE_API_KEY: your_brave_search_api_key_here // 需要去 Brave 官網(wǎng)申請(qǐng) } } // 你可以繼續(xù)添加更多如 figma: { ... }, github: { ... } } }這個(gè)配置定義了兩個(gè) MCP Server。filesystem使用 stdio 方式啟動(dòng)一個(gè)本地進(jìn)程braveSearch同理但需要注入環(huán)境變量BRAVE_API_KEY。步驟 3啟動(dòng) Headroom 服務(wù)在終端運(yùn)行headroom proxy如果配置文件不在默認(rèn)位置需要指定headroom proxy --config ./path/to/your/headroom.config.json服務(wù)啟動(dòng)后你會(huì)看到日志輸出顯示服務(wù)正在監(jiān)聽某個(gè)地址例如Server running on http://localhost:3000并且會(huì)顯示已成功加載的 MCP Server。步驟 4配置 Claude Code打開 Claude Code 桌面應(yīng)用。進(jìn)入設(shè)置Settings。找到 “Advanced” 或 “Developer” 或 “MCP” 設(shè)置部分。尋找 “MCP Servers” 或 “External Tools” 的配置項(xiàng)。這里通常是一個(gè) JSON 配置框。輸入以下配置將 Claude Code 指向本地運(yùn)行的 Headroom 服務(wù)[ { name: headroom-gateway, type: sse, url: http://localhost:3000/sse } ]保存設(shè)置并重啟 Claude Code。步驟 5驗(yàn)證與使用重啟后在 Claude Code 的聊天界面你可以嘗試輸入“請(qǐng)列出我 Projects 目錄下的所有文件?！?如果配置成功Claude Code 會(huì)調(diào)用 filesystem 工具并返回目錄列表。你也可以問(wèn)“搜索一下今天關(guān)于 Headroom 的最新消息?！?它會(huì)調(diào)用 braveSearch 工具并返回搜索結(jié)果。4.3 Proxy 模式的高級(jí)配置與故障排查動(dòng)態(tài)添加 ServerHeadroom Proxy 的優(yōu)勢(shì)在于你不需要重啟服務(wù)來(lái)更新配置。某些 Headroom 實(shí)現(xiàn)支持通過(guò)管理 API 動(dòng)態(tài)添加或移除 MCP Server這為工具鏈的熱插拔提供了可能。安全配置在配置文件中務(wù)必注意為文件系統(tǒng) Server 指定明確的、最小必要的目錄路徑不要使用根目錄/。API 密鑰等敏感信息不要硬編碼在配置文件中應(yīng)使用環(huán)境變量如上面的env字段或系統(tǒng)的密鑰管理服務(wù)。常見問(wèn)題與排查FAQClaude Code 提示 “unexpected status 404 not found”原因Claude Code 連接 Headroom 的 URL 不正確或者 Headroom 服務(wù)沒(méi)有正常運(yùn)行。排查首先在瀏覽器訪問(wèn)http://localhost:3000或你配置的端口看 Headroom 的服務(wù)狀態(tài)頁(yè)是否正常顯示。然后檢查 Claude Code 配置中的url是否精確到/sse端點(diǎn)。提示 “unexpected status 401 unauthorized” 或 “402 payment required”原因這通常是 Headroom 服務(wù)在連接某個(gè)遠(yuǎn)程 MCP Server 時(shí)該 Server 返回的認(rèn)證或付費(fèi)錯(cuò)誤。例如你配置的搜索 Server 的 API 密鑰無(wú)效或余額不足。排查查看 Headroom 啟動(dòng)時(shí)的日志找到具體是哪個(gè) Server 報(bào)錯(cuò)。檢查該 Server 的配置尤其是 API 密鑰等認(rèn)證信息是否正確且有效。提示 “connection timed out”原因網(wǎng)絡(luò)連接問(wèn)題?？赡苁?Headroom 服務(wù)未啟動(dòng)防火墻阻止了端口訪問(wèn)或者 Claude Code 被系統(tǒng)級(jí) HTTP 代理阻擋。排查運(yùn)行curl http://localhost:3000測(cè)試服務(wù)是否可達(dá)。確認(rèn) Claude Code 是否運(yùn)行在需要特殊代理的網(wǎng)絡(luò)環(huán)境下并正確配置了系統(tǒng)或 Claude Code 的 HTTP 代理設(shè)置文章開頭環(huán)境準(zhǔn)備部分已提及。工具調(diào)用無(wú)反應(yīng)或報(bào)錯(cuò)原因MCP Server 本身啟動(dòng)失敗或命令路徑錯(cuò)誤。排查仔細(xì)查看 Headroom 的啟動(dòng)日志確認(rèn)每個(gè)mcpServers下的command是否能在終端中直接運(yùn)行。例如手動(dòng)執(zhí)行npx -y modelcontextprotocol/server-filesystem /tmp看能否成功啟動(dòng)一個(gè)文件系統(tǒng) Server。5. 兩種模式對(duì)比與選型建議經(jīng)過(guò)上面的實(shí)戰(zhàn)你應(yīng)該對(duì) wrap 和 proxy 兩種模式有了直觀的感受。下面用一個(gè)表格來(lái)系統(tǒng)對(duì)比一下方便你根據(jù)實(shí)際情況做出選擇特性維度Wrap (封裝) 模式Proxy (代理) 模式集成度高。與 Claude Code 客戶端深度集成一體分發(fā)。低。獨(dú)立進(jìn)程通過(guò)標(biāo)準(zhǔn) MCP 協(xié)議與 Claude Code 通信。用戶配置無(wú)需配置。開箱即用能力預(yù)置。需要配置。需手動(dòng)啟動(dòng)服務(wù)并在 Claude Code 中設(shè)置連接。靈活性低。功能在構(gòu)建時(shí)固定用戶無(wú)法修改。高。通過(guò)修改配置文件可隨時(shí)增刪 MCP Server無(wú)需更新客戶端。更新復(fù)雜度高。需要重新構(gòu)建并分發(fā)整個(gè)客戶端。低。更新 Headroom 服務(wù)端或配置文件即可客戶端不變。適用場(chǎng)景1. 企業(yè)/團(tuán)隊(duì)標(biāo)準(zhǔn)化部署2. 面向非技術(shù)用戶的成品工具3. 特定垂直領(lǐng)域的打包方案1. 開發(fā)者個(gè)人使用2. 需要頻繁嘗試新 MCP 工具的場(chǎng)景3. 工具鏈需要?jiǎng)討B(tài)調(diào)整的環(huán)境技術(shù)門檻高。需要桌面應(yīng)用開發(fā)和構(gòu)建知識(shí)。中。主要需要理解配置文件和網(wǎng)絡(luò)調(diào)試。性能通常更好因?yàn)榧稍谕粋€(gè)進(jìn)程內(nèi)通信開銷小。略有開銷因?yàn)槎嗔艘淮尉W(wǎng)絡(luò)轉(zhuǎn)發(fā)本地回環(huán)網(wǎng)絡(luò)延遲極低。選型建議如果你是獨(dú)立開發(fā)者或小團(tuán)隊(duì)強(qiáng)烈建議從Proxy 模式開始。它提供了最大的靈活性和試錯(cuò)空間你可以像搭積木一樣隨時(shí)更換、添加新的 MCP 工具如今天加個(gè) GitHub Server明天加個(gè) Playwright 測(cè)試 Server而不用動(dòng)輒重新安裝 Claude Code。如果你是為一個(gè)大型技術(shù)團(tuán)隊(duì)或公司構(gòu)建統(tǒng)一的 AI 編程環(huán)境并且希望做到集中管控、開箱即用那么投入資源構(gòu)建一個(gè)定制的Wrap 模式客戶端是值得的。這能極大降低團(tuán)隊(duì)成員的配置成本并確保環(huán)境一致性。如果你是一個(gè)工具開發(fā)者想要分發(fā)一個(gè)包含你獨(dú)家 MCP 工具的 Claude Code 給用戶Wrap 模式能提供最干凈、最專業(yè)的用戶體驗(yàn)。6. 拓展構(gòu)建與連接自定義 MCP ServerHeadroom 的真正威力在于它能連接豐富的 MCP Server 生態(tài)。除了使用社區(qū)已有的 Server如 filesystem, brave-search你完全可以為自己公司的內(nèi)部系統(tǒng)或某個(gè)特定工具構(gòu)建一個(gè) MCP Server。6.1 MCP Server 開發(fā)概覽開發(fā)一個(gè) MCP Server 并不復(fù)雜核心是實(shí)現(xiàn) MCP 協(xié)議規(guī)定的幾個(gè)接口。協(xié)議支持多種傳輸方式最常見的是stdio標(biāo)準(zhǔn)輸入輸出和sseServer-Sent Events。stdio 適合本地命令行工具sse 適合遠(yuǎn)程 HTTP 服務(wù)。一個(gè)最簡(jiǎn)單的 MCP Server以 Node.js 為例結(jié)構(gòu)如下// server.js import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; // 1. 創(chuàng)建 Server 實(shí)例 const server new Server( { name: my-custom-tool-server, version: 1.0.0, }, { capabilities: { tools: {}, // 聲明本 Server 提供工具 }, } ); // 2. 定義工具 server.setRequestHandler(tools/list, async () { return { tools: [ { name: get_weather, description: 獲取指定城市的天氣, inputSchema: { type: object, properties: { city: { type: string, description: 城市名 } }, required: [city] } } ] }; }); server.setRequestHandler(tools/call, async (request) { if (request.params.name get_weather) { const city request.params.arguments?.city; // 這里實(shí)現(xiàn)實(shí)際的天氣查詢邏輯比如調(diào)用一個(gè)天氣 API return { content: [{ type: text, text: 查詢到城市 ${city} 的天氣是晴朗25度。 }], }; } throw new Error(未知的工具); }); // 3. 啟動(dòng)傳輸層這里使用 stdio const transport new StdioServerTransport(); await server.connect(transport); console.error(My MCP Server 已啟動(dòng) (stdio));這個(gè) Server 定義了一個(gè)get_weather工具。你可以使用npx來(lái)運(yùn)行它node server.js。它會(huì)在 stdio 上等待連接。6.2 將自定義 Server 接入 Headroom Proxy開發(fā)完成后如何讓 Claude Code 通過(guò) Headroom 使用它非常簡(jiǎn)單只需在headroom.config.json中添加一項(xiàng)配置{ mcpServers: { myWeather: { command: node, args: [/absolute/path/to/your/server.js] } } }重啟 Headroom 服務(wù)它就會(huì)啟動(dòng)你的自定義 Server。之后在 Claude Code 中你就可以直接說(shuō)“使用 get_weather 工具查詢北京的天氣?！?Claude Code 會(huì)通過(guò) Headroom 調(diào)用你的 Server并返回結(jié)果。對(duì)于遠(yuǎn)程的 SSE Server配置更簡(jiǎn)單{ mcpServers: { remoteTools: { type: sse, url: https://your-remote-mcp-server.com/sse } } }6.3 生態(tài)與社區(qū)工具探索目前 MCP 生態(tài)正在快速增長(zhǎng)社區(qū)已經(jīng)有很多優(yōu)秀的 MCP Server 可以直接使用極大地?cái)U(kuò)展了 Claude Code 的能力數(shù)據(jù)與搜索brave-search-mcp,tavily-mcp提供網(wǎng)絡(luò)搜索能力。開發(fā)工具server-filesystem文件操作server-githubGitHub 交互playwright-mcp瀏覽器自動(dòng)化chrome-devtools-mcp調(diào)試。設(shè)計(jì)工具figma-mcp,藍(lán)湖-mcp需自行尋找或開發(fā)用于連接設(shè)計(jì)平臺(tái)。專業(yè)工具ida-mcp反匯編工具 IDA Pro 集成burp-mcp安全測(cè)試工具 Burp Suite 集成。你可以在 npm 上搜索mcp-server-*或*-mcp或者在 Anthropic 的官方 MCP 倉(cāng)庫(kù)中尋找靈感。將這些工具通過(guò) Headroom 聚合起來(lái)你就能打造出一個(gè)無(wú)比強(qiáng)大的、專屬的 AI 編程工作站。