建自定義 MCP Server 的完整配置與驗(yàn)證)
1. 為什么團(tuán)隊內(nèi)部系統(tǒng)總?cè)币粋€ MCP Server你可能已經(jīng)用 Claude Code 連過 Jira、GitHub、Postgres這些現(xiàn)成的 MCP Server 開箱即用體驗(yàn)很順。但真正卡住大多數(shù)人的是團(tuán)隊內(nèi)部那套沒人寫 Server 的系統(tǒng)自研工單、私有知識庫、內(nèi)部腳本、某個只有你懂的本地工具。它們沒有官方 MCP 實(shí)現(xiàn)你只能眼睜睜看著 Claude 在對話里知道有這個東西卻沒法真正調(diào)用。mcp-builder 就是為這個缺口準(zhǔn)備的。它是 Anthropic 在 anthropics/skills 倉庫里維護(hù)的官方 Skill注意它的定位——不是代碼生成器而是一套工程方法論。它教你的不是復(fù)制粘貼一段模板而是四件事怎么規(guī)劃 tool 的命名和 API 覆蓋范圍、怎么用 FastMCPPython或 MCP SDKTypeScript落地實(shí)現(xiàn)、怎么用 MCP Inspector 單獨(dú)調(diào)試、怎么設(shè)計 Eval 驗(yàn)證 Agent 是否真的會用你的 Server。我試過直接手寫 MCP Server最容易翻車的地方不是代碼本身而是 tool 的 docstring 寫得太隨意導(dǎo)致 Claude 填參數(shù)時全靠猜。mcp-builder 的價值就在于把這些隱性規(guī)范顯性化tool 名要有前綴加動作、docstring 要說清每個參數(shù)含義、錯誤要返回可行動文案而不是拋異常、只讀 tool 不寫盤。這些規(guī)則聽起來瑣碎但決定了你的 Server 是能跑還是Agent 真的會用。這篇聚焦一條完整實(shí)操路徑從零用 FastMCP 搭一個本地筆記 Server走完腳手架生成、MCP Inspector 調(diào)試、本地聯(lián)調(diào)、接入 Claude Code、對話驗(yàn)收。全程 80 行 Python任何機(jī)器都能跑通不需要 API Key。適合已經(jīng)會用 Claude Code、想給自己內(nèi)部工具補(bǔ)一個 MCP 接口的開發(fā)者。讀完你能獨(dú)立完成一次端到端跑通而不是停留在知道有這么個東西。2. 前置準(zhǔn)備安裝 mcp-builder 與 FastMCP 環(huán)境在動手寫 Server 之前先把兩樣?xùn)|西裝好Claude Code 里的 mcp-builder Skill以及本機(jī)的 Python MCP 運(yùn)行環(huán)境。這兩件事分開做別混在一起否則后面排錯會很痛苦。先說 Skill 安裝。在 Claude Code 里分兩條命令走第一條是添加 marketplace/plugin marketplace add anthropics/skills第二條是安裝 example-skills 包mcp-builder 就在這個包里/plugin install example-skillsanthropic-agent-skills如果你只想裝 mcp-builder 這一個 Skill不想把整個 example-skills 都拉下來可以用 npx 單獨(dú)裝npx skills add anthropics/skills --skill mcp-builder --agent claude-code裝完之后你在 Claude Code 里就能通過 Skill 的方式調(diào)用 mcp-builder 的規(guī)劃指引。它不會替你寫代碼但會在你規(guī)劃 tool 命名、設(shè)計 docstring 時給出規(guī)范建議這部分后面 Phase 1 會用到。再說本機(jī)環(huán)境。寫 Python 版 Server 需要 Python 3.10 及以上然后裝 mcp 包FastMCP 框架就在里面python --version pip install mcp這里有個坑要提前說pip install mcp 裝到的環(huán)境必須和你后面運(yùn)行 server.py 的 python 是同一個。很多人機(jī)器上有多個 Python系統(tǒng)自帶、conda、venv裝的時候用了一個跑的時候用了另一個結(jié)果就是ModuleNotFoundError: No module named mcp。建議直接建一個干凈的虛擬環(huán)境python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install mcp激活后which pythonWindows 用where python確認(rèn)路徑指向 .venv再往下走。這一步花兩分鐘能省掉后面半小時的排錯。關(guān)于 TaoToken 的前置說明本篇的 MCP Server 是純本地 stdio 工具不依賴任何遠(yuǎn)程模型網(wǎng)關(guān)就能跑通 Inspector 和 Claude Code 聯(lián)調(diào)。如果你后續(xù)想把 Server 接到遠(yuǎn)程模型做 Eval或者團(tuán)隊要共享一個 streamable HTTP 的 Server可以先把 TaoToken 的 API Key 準(zhǔn)備好接入文檔在 https://taotoken.net/api Key 在 https://taotoken.net/api-keys 生成。本地 stdio 這條鏈路不需要它但提前備著不虧。環(huán)境確認(rèn)清單Python 3.10、mcp 包已裝、虛擬環(huán)境已激活、Claude Code 已裝 mcp-builder Skill。四項都打勾進(jìn)入下一步。3. 可復(fù)制配置用 FastMCP 寫一個 pocket-notes Server這一節(jié)是全文的核心直接給你可復(fù)制的完整代碼和配置片段。我們做一個 pocket-notes MCP Server功能是讓 Claude 幫你管理本地純文本筆記添加、列表、搜索。數(shù)據(jù)存在用戶目錄的 JSON 文件里不需要 API Key任何機(jī)器都能跑通。先建目錄mkdir pocket-notes-mcp cd pocket-notes-mcp然后創(chuàng)建 server.py下面是完整可運(yùn)行代碼import json from pathlib import Path from mcp.server.fastmcp import FastMCP mcp FastMCP(pocket-notes) NOTES_FILE Path.home() / .pocket-notes / notes.json def _load(): if not NOTES_FILE.exists(): return [] return json.loads(NOTES_FILE.read_text(encodingutf-8)) def _save(notes): NOTES_FILE.parent.mkdir(parentsTrue, exist_okTrue) NOTES_FILE.write_text( json.dumps(notes, ensure_asciiFalse, indent2), encodingutf-8) mcp.tool() def notes_add(title: str, content: str) - str: Add a note. title: note title; content: note body. title title.strip() if not title: return Error: title cannot be empty. Provide a title and retry. notes _load() note_id len(notes) 1 notes.append({id: note_id, title: title, content: content.strip()}) _save(notes) return fAdded note #{note_id}: {title} mcp.tool() def notes_list() - str: List all notes (id and title only). notes _load() if not notes: return No notes yet. Use notes_add first. return \n.join(f#{n[id]} {n[title]} for n in notes) mcp.tool() def notes_search(keyword: str) - str: Search notes by keyword in title or content. kw keyword.strip().lower() if not kw: return Error: keyword cannot be empty. hits [n for n in _load() if kw in n[title].lower() or kw in n[content].lower()] if not hits: return fNo notes matching {keyword}. return \n\n.join(f#{n[id]} {n[title]}\n{n[content]} for n in hits) if __name__ __main__: mcp.run(transportstdio)對照 mcp-builder 的規(guī)范這段代碼有幾個刻意的設(shè)計點(diǎn)值得說。Tool 名用notes_前綴加動作Agent 在發(fā)現(xiàn)工具時更容易歸類docstring 里明確寫了每個參數(shù)的含義Claude 靠它填參寫含糊了它就會瞎猜錯誤返回的是可行動文案Provide a title and retry而不是拋未捕獲異常這樣 Agent 能自己糾正只讀 toolnotes_list、notes_search不寫盤寫盤 toolnotes_add邊界清晰。Transport 選型上個人本地工具用 stdio 就夠了。如果你要團(tuán)隊遠(yuǎn)程共享才需要換成 streamable HTTP那是進(jìn)階場景本篇先不展開。本地先驗(yàn)證一下能不能起來python server.py如果掛起沒有報錯說明 Server 正常啟動按 CtrlC 退出。這一步只是確認(rèn)進(jìn)程能跑真正的功能驗(yàn)證交給下一節(jié)的 Inspector。接入 Claude Code 有兩種方式先給命令行方式個人 scope推薦先試claude mcp add --transport stdio pocket-notes -- python /絕對路徑/pocket-notes-mcp/server.pyWindows 示例claude mcp add --transport stdio pocket-notes -- python E:\pocket-notes-mcp\server.py再給項目級配置方式適合團(tuán)隊共享、可以提交 Git。在項目根目錄建.mcp.json{ mcpServers: { pocket-notes: { type: stdio, command: python, args: [E:/tools/pocket-notes-mcp/server.py] } } }注意 args 里的路徑用正斜杠Windows 下反斜杠在 JSON 里要轉(zhuǎn)義容易出錯。項目級配置首次加載時 Claude Code 可能會彈交互讓你批準(zhǔn)這是正常的安全機(jī)制。4. 驗(yàn)證請求MCP Inspector 調(diào)試與對話驗(yàn)收代碼寫完不等于能用。接入 Claude 之前先用官方 MCP Inspector 單獨(dú)測 tool把 Server 邏輯和 Claude 的調(diào)用行為分開驗(yàn)證這樣出問題時你能快速定位是 Server 的鍋還是配置的鍋。啟動 Inspectornpx modelcontextprotocol/inspector python server.py它會啟動一個本地服務(wù)并打印一個瀏覽器地址打開后你會看到 Inspector 界面左側(cè)列出你的三個 tool。按順序測三步第一步調(diào) notes_add參數(shù) title購物清單content牛奶、雞蛋。預(yù)期返回Added note #1: 購物清單。第二步調(diào) notes_list預(yù)期返回#1 購物清單。第三步調(diào) notes_search參數(shù) keyword牛奶預(yù)期返回完整條目包含標(biāo)題和內(nèi)容。三步全過說明 Server 邏輯正確可以接入 Claude Code 了。如果某一步失敗先看 Inspector 里的錯誤信息再對照下一節(jié)的排查表。接入后完全重啟 Claude Code輸入/mcp你應(yīng)該能看到 pocket-notes 以及它下面的 3 個 tool。如果沒看到先claude mcp list查狀態(tài)。然后是對話驗(yàn)收在 Claude Code 里依次說三句話第一句用 pocket-notes 添加筆記標(biāo)題「學(xué)習(xí)計劃」內(nèi)容「本周完成 MCP 教程」。第二句列出我所有筆記。第三句搜索包含 MCP 的筆記。成功標(biāo)志有兩個一是 Claude 實(shí)際調(diào)用了 MCP tool你會在對話里看到工具調(diào)用記錄二是打開~/.pocket-notes/notes.jsonWindows 是C:\Users\你的用戶名\.pocket-notes\notes.json內(nèi)容與對話一致。這里補(bǔ)一句關(guān)于 Eval 的思路。mcp-builder 的 Phase 4 強(qiáng)調(diào)設(shè)計 Eval 驗(yàn)證 Agent 能否真正用好你的 Server。最簡單的 Eval 就是上面這三句話如果 Claude 能正確選 tool、正確填參、正確解讀返回說明你的 docstring 和 tool 設(shè)計到位了。如果它選錯 tool 或者參數(shù)填錯回去改 docstring而不是改代碼邏輯。5. 常見報錯排查401、local proxy failed 與 reading choices這一節(jié)對照真實(shí)報錯把最容易踩的坑列出來。注意本篇的本地 stdio Server 本身不涉及遠(yuǎn)程鑒權(quán)所以 401 這類錯誤通常出現(xiàn)在你后續(xù)接遠(yuǎn)程模型或 HTTP transport 的場景這里一并說清。先看 Inspector 連不上的情況。最常見原因是路徑問題python server.py用的是相對路徑但 Inspector 啟動時工作目錄可能變了。解決辦法是統(tǒng)一用絕對路徑npx modelcontextprotocol/inspector python /絕對路徑/server.py。第二個原因是環(huán)境不一致pip install mcp 裝的環(huán)境和運(yùn)行 server.py 的 python 不是同一個回到第 2 節(jié)用 venv 統(tǒng)一。再看/mcp里看不到 Server。先跑claude mcp list查狀態(tài)如果顯示未連接重啟 Claude Code。項目級.mcp.json首次加載需要交互批準(zhǔn)如果你跳過了批準(zhǔn)Server 不會生效。另外檢查 JSON 語法多一個逗號都會導(dǎo)致整個配置解析失敗。Tool 調(diào)用失敗時看終端里的 MCP 日志。FastMCP 會把異常打到 stderr如果日志里出現(xiàn)ModuleNotFoundError還是環(huán)境問題如果出現(xiàn)文件權(quán)限錯誤檢查~/.pocket-notes/目錄是否可寫。關(guān)于 401 和 local proxy failed這兩個報錯一般出現(xiàn)在你把 Server 接到遠(yuǎn)程模型網(wǎng)關(guān)做 Eval 的時候。401 是 Key 無效或過期去 https://taotoken.net/api-keys 重新生成local proxy failed 通常是本地網(wǎng)絡(luò)配置或 Base URL 寫錯確認(rèn)你填的是 https://taotoken.net/api 而不是別的地址。如果你在 Claude Code 里配了遠(yuǎn)程模型檢查 settings 里的 Base URL、Key、Model ID 三件套是否齊全缺一個都會失敗。關(guān)于reading choices報錯這通常出現(xiàn)在調(diào)用遠(yuǎn)程模型返回體解析時說明返回結(jié)構(gòu)和你預(yù)期的不一致多半是 Base URL 指向了錯誤的端點(diǎn)或者 Model ID 填了一個不存在的模型。對照接入文檔 https://taotoken.net/doc 確認(rèn)端點(diǎn)格式。關(guān)于 OAuth 報錯如果你用的是需要 OAuth 的遠(yuǎn)程 MCP Servertoken 過期會報這個。本地 stdio Server 不涉及但如果你在 Cline MCP 或 Codex 的 auth.json 里配了遠(yuǎn)程 Server檢查 token 是否刷新。想換 TypeScript 實(shí)現(xiàn)的話mcp-builder Skill 里有 node_mcp_server.md適合做遠(yuǎn)程 HTTP Server。Python 版適合本地快速驗(yàn)證TypeScript 版適合團(tuán)隊共享和部署?，F(xiàn)象處理Inspector 連不上用絕對路徑確認(rèn) python 和 pip install mcp 在同一環(huán)境/mcp 無 Server重啟 Claudeclaude mcp list 查狀態(tài)檢查 .mcp.json 語法Tool 調(diào)用失敗看終端 MCP 日志確認(rèn) venv 路徑一致401Key 無效去 api-keys 重新生成local proxy failed檢查 Base URL 是否為 https://taotoken.net/apireading choices端點(diǎn)或 Model ID 錯誤對照接入文檔OAuth 報錯遠(yuǎn)程 Server token 過期刷新 token想換 TypeScript看 Skill 內(nèi) node_mcp_server.md6. 把 Server 接到長期編碼流Coding Plan 與后續(xù)擴(kuò)展跑通第一個 Server 之后你大概率會想把它接到日常編碼流里讓 Claude 在寫代碼時順手調(diào)用你的內(nèi)部工具。這時候有幾個方向可以擴(kuò)展。第一個方向是把 stdio 換成 streamable HTTP讓團(tuán)隊共享。stdio 是單機(jī)進(jìn)程每個人都要本地裝一份HTTP transport 可以部署到內(nèi)網(wǎng)團(tuán)隊成員通過 URL 接入。mcp-builder 的 Skill 里有對應(yīng)的指引TypeScript 版更適合這個場景。第二個方向是擴(kuò)充 tool 覆蓋范圍。pocket-notes 只有三個 tool真實(shí)內(nèi)部系統(tǒng)往往需要十幾個。mcp-builder 的 Phase 1 規(guī)劃方法在這里很關(guān)鍵先列出所有 API 端點(diǎn)再決定哪些暴露成 tool、怎么命名、怎么分組。不要一股腦全暴露Agent 面對太多 tool 會選錯。第三個方向是接遠(yuǎn)程模型做 Eval。本地 stdio 不需要遠(yuǎn)程模型但如果你想批量測試 Agent 在不同模型下的 tool 調(diào)用準(zhǔn)確率就需要一個穩(wěn)定的模型網(wǎng)關(guān)。這時候 TaoToken 的 Coding Plan 比較合適適合長期編碼和 Agent 場景地址在 https://taotoken.net/coding-plan 。模型對話調(diào)試可以用 https://taotoken.net/models 控制臺在 https://taotoken.net/console 。如果你用的是 Claude Code 的 Anthropic 兼容接入配置片段大致是這樣注意 Base URL、Key、Model ID 三件套要齊全{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的Key, ANTHROPIC_MODEL: 你的ModelID } }Claude Code 的 Anthropic 接入文檔在 https://taotoken.net/claudecode-anthropic 里面有完整的 settings 示例。Cline MCP 和 Codex 的 auth.json 配置同理都是 Base URL 加 Key 加 Model ID缺一不可。最后說一個真實(shí)經(jīng)驗(yàn)MCP Server 的調(diào)試成本八成花在 docstring 和錯誤文案上而不是業(yè)務(wù)邏輯。業(yè)務(wù)邏輯你寫十行就完了但讓 Agent 正確選 tool、正確填參、正確解讀返回需要反復(fù)打磨 docstring。mcp-builder 的價值就在這——它把 MCP 工程規(guī)范沉淀成了可復(fù)用的方法你照著走能少踩很多坑。80 行 Python 走完編寫、Inspector、Claude Code 全鏈路這就是你的第一個 MCP Server。 Claude Code（22）：用 mcp-builder 構(gòu)建自定義 MCP Server 的完整配置與驗(yàn)證
1. 為什么團(tuán)隊內(nèi)部系統(tǒng)總?cè)币粋€ MCP Server你可能已經(jīng)用 Claude Code 連過 Jira、GitHub、Postgres這些現(xiàn)成的 MCP Server 開箱即用體驗(yàn)很順。但真正卡住大多數(shù)人的是團(tuán)隊內(nèi)部那套沒人寫 Server 的系統(tǒng)自研工單、私有知識庫、內(nèi)部腳本、某個只有你懂的本地工具。它們沒有官方 MCP 實(shí)現(xiàn)你只能眼睜睜看著 Claude 在對話里知道有這個東西卻沒法真正調(diào)用。mcp-builder 就是為這個缺口準(zhǔn)備的。它是 Anthropic 在 anthropics/skills 倉庫里維護(hù)的官方 Skill注意它的定位——不是代碼生成器而是一套工程方法論。它教你的不是復(fù)制粘貼一段模板而是四件事怎么規(guī)劃 tool 的命名和 API 覆蓋范圍、怎么用 FastMCPPython或 MCP SDKTypeScript落地實(shí)現(xiàn)、怎么用 MCP Inspector 單獨(dú)調(diào)試、怎么設(shè)計 Eval 驗(yàn)證 Agent 是否真的會用你的 Server。我試過直接手寫 MCP Server最容易翻車的地方不是代碼本身而是 tool 的 docstring 寫得太隨意導(dǎo)致 Claude 填參數(shù)時全靠猜。mcp-builder 的價值就在于把這些隱性規(guī)范顯性化tool 名要有前綴加動作、docstring 要說清每個參數(shù)含義、錯誤要返回可行動文案而不是拋異常、只讀 tool 不寫盤。這些規(guī)則聽起來瑣碎但決定了你的 Server 是能跑還是Agent 真的會用。這篇聚焦一條完整實(shí)操路徑從零用 FastMCP 搭一個本地筆記 Server走完腳手架生成、MCP Inspector 調(diào)試、本地聯(lián)調(diào)、接入 Claude Code、對話驗(yàn)收。全程 80 行 Python任何機(jī)器都能跑通不需要 API Key。適合已經(jīng)會用 Claude Code、想給自己內(nèi)部工具補(bǔ)一個 MCP 接口的開發(fā)者。讀完你能獨(dú)立完成一次端到端跑通而不是停留在知道有這么個東西。2. 前置準(zhǔn)備安裝 mcp-builder 與 FastMCP 環(huán)境在動手寫 Server 之前先把兩樣?xùn)|西裝好Claude Code 里的 mcp-builder Skill以及本機(jī)的 Python MCP 運(yùn)行環(huán)境。這兩件事分開做別混在一起否則后面排錯會很痛苦。先說 Skill 安裝。在 Claude Code 里分兩條命令走第一條是添加 marketplace/plugin marketplace add anthropics/skills第二條是安裝 example-skills 包mcp-builder 就在這個包里/plugin install example-skillsanthropic-agent-skills如果你只想裝 mcp-builder 這一個 Skill不想把整個 example-skills 都拉下來可以用 npx 單獨(dú)裝npx skills add anthropics/skills --skill mcp-builder --agent claude-code裝完之后你在 Claude Code 里就能通過 Skill 的方式調(diào)用 mcp-builder 的規(guī)劃指引。它不會替你寫代碼但會在你規(guī)劃 tool 命名、設(shè)計 docstring 時給出規(guī)范建議這部分后面 Phase 1 會用到。再說本機(jī)環(huán)境。寫 Python 版 Server 需要 Python 3.10 及以上然后裝 mcp 包FastMCP 框架就在里面python --version pip install mcp這里有個坑要提前說pip install mcp 裝到的環(huán)境必須和你后面運(yùn)行 server.py 的 python 是同一個。很多人機(jī)器上有多個 Python系統(tǒng)自帶、conda、venv裝的時候用了一個跑的時候用了另一個結(jié)果就是ModuleNotFoundError: No module named mcp。建議直接建一個干凈的虛擬環(huán)境python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install mcp激活后which pythonWindows 用where python確認(rèn)路徑指向 .venv再往下走。這一步花兩分鐘能省掉后面半小時的排錯。關(guān)于 TaoToken 的前置說明本篇的 MCP Server 是純本地 stdio 工具不依賴任何遠(yuǎn)程模型網(wǎng)關(guān)就能跑通 Inspector 和 Claude Code 聯(lián)調(diào)。如果你后續(xù)想把 Server 接到遠(yuǎn)程模型做 Eval或者團(tuán)隊要共享一個 streamable HTTP 的 Server可以先把 TaoToken 的 API Key 準(zhǔn)備好接入文檔在 https://taotoken.net/api Key 在 https://taotoken.net/api-keys 生成。本地 stdio 這條鏈路不需要它但提前備著不虧。環(huán)境確認(rèn)清單Python 3.10、mcp 包已裝、虛擬環(huán)境已激活、Claude Code 已裝 mcp-builder Skill。四項都打勾進(jìn)入下一步。3. 可復(fù)制配置用 FastMCP 寫一個 pocket-notes Server這一節(jié)是全文的核心直接給你可復(fù)制的完整代碼和配置片段。我們做一個 pocket-notes MCP Server功能是讓 Claude 幫你管理本地純文本筆記添加、列表、搜索。數(shù)據(jù)存在用戶目錄的 JSON 文件里不需要 API Key任何機(jī)器都能跑通。先建目錄mkdir pocket-notes-mcp cd pocket-notes-mcp然后創(chuàng)建 server.py下面是完整可運(yùn)行代碼import json from pathlib import Path from mcp.server.fastmcp import FastMCP mcp FastMCP(pocket-notes) NOTES_FILE Path.home() / .pocket-notes / notes.json def _load(): if not NOTES_FILE.exists(): return [] return json.loads(NOTES_FILE.read_text(encodingutf-8)) def _save(notes): NOTES_FILE.parent.mkdir(parentsTrue, exist_okTrue) NOTES_FILE.write_text( json.dumps(notes, ensure_asciiFalse, indent2), encodingutf-8) mcp.tool() def notes_add(title: str, content: str) - str: Add a note. title: note title; content: note body. title title.strip() if not title: return Error: title cannot be empty. Provide a title and retry. notes _load() note_id len(notes) 1 notes.append({id: note_id, title: title, content: content.strip()}) _save(notes) return fAdded note #{note_id}: {title} mcp.tool() def notes_list() - str: List all notes (id and title only). notes _load() if not notes: return No notes yet. Use notes_add first. return \n.join(f#{n[id]} {n[title]} for n in notes) mcp.tool() def notes_search(keyword: str) - str: Search notes by keyword in title or content. kw keyword.strip().lower() if not kw: return Error: keyword cannot be empty. hits [n for n in _load() if kw in n[title].lower() or kw in n[content].lower()] if not hits: return fNo notes matching {keyword}. return \n\n.join(f#{n[id]} {n[title]}\n{n[content]} for n in hits) if __name__ __main__: mcp.run(transportstdio)對照 mcp-builder 的規(guī)范這段代碼有幾個刻意的設(shè)計點(diǎn)值得說。Tool 名用notes_前綴加動作Agent 在發(fā)現(xiàn)工具時更容易歸類docstring 里明確寫了每個參數(shù)的含義Claude 靠它填參寫含糊了它就會瞎猜錯誤返回的是可行動文案Provide a title and retry而不是拋未捕獲異常這樣 Agent 能自己糾正只讀 toolnotes_list、notes_search不寫盤寫盤 toolnotes_add邊界清晰。Transport 選型上個人本地工具用 stdio 就夠了。如果你要團(tuán)隊遠(yuǎn)程共享才需要換成 streamable HTTP那是進(jìn)階場景本篇先不展開。本地先驗(yàn)證一下能不能起來python server.py如果掛起沒有報錯說明 Server 正常啟動按 CtrlC 退出。這一步只是確認(rèn)進(jìn)程能跑真正的功能驗(yàn)證交給下一節(jié)的 Inspector。接入 Claude Code 有兩種方式先給命令行方式個人 scope推薦先試claude mcp add --transport stdio pocket-notes -- python /絕對路徑/pocket-notes-mcp/server.pyWindows 示例claude mcp add --transport stdio pocket-notes -- python E:\pocket-notes-mcp\server.py再給項目級配置方式適合團(tuán)隊共享、可以提交 Git。在項目根目錄建.mcp.json{ mcpServers: { pocket-notes: { type: stdio, command: python, args: [E:/tools/pocket-notes-mcp/server.py] } } }注意 args 里的路徑用正斜杠Windows 下反斜杠在 JSON 里要轉(zhuǎn)義容易出錯。項目級配置首次加載時 Claude Code 可能會彈交互讓你批準(zhǔn)這是正常的安全機(jī)制。4. 驗(yàn)證請求MCP Inspector 調(diào)試與對話驗(yàn)收代碼寫完不等于能用。接入 Claude 之前先用官方 MCP Inspector 單獨(dú)測 tool把 Server 邏輯和 Claude 的調(diào)用行為分開驗(yàn)證這樣出問題時你能快速定位是 Server 的鍋還是配置的鍋。啟動 Inspectornpx modelcontextprotocol/inspector python server.py它會啟動一個本地服務(wù)并打印一個瀏覽器地址打開后你會看到 Inspector 界面左側(cè)列出你的三個 tool。按順序測三步第一步調(diào) notes_add參數(shù) title購物清單content牛奶、雞蛋。預(yù)期返回Added note #1: 購物清單。第二步調(diào) notes_list預(yù)期返回#1 購物清單。第三步調(diào) notes_search參數(shù) keyword牛奶預(yù)期返回完整條目包含標(biāo)題和內(nèi)容。三步全過說明 Server 邏輯正確可以接入 Claude Code 了。如果某一步失敗先看 Inspector 里的錯誤信息再對照下一節(jié)的排查表。接入后完全重啟 Claude Code輸入/mcp你應(yīng)該能看到 pocket-notes 以及它下面的 3 個 tool。如果沒看到先claude mcp list查狀態(tài)。然后是對話驗(yàn)收在 Claude Code 里依次說三句話第一句用 pocket-notes 添加筆記標(biāo)題「學(xué)習(xí)計劃」內(nèi)容「本周完成 MCP 教程」。第二句列出我所有筆記。第三句搜索包含 MCP 的筆記。成功標(biāo)志有兩個一是 Claude 實(shí)際調(diào)用了 MCP tool你會在對話里看到工具調(diào)用記錄二是打開~/.pocket-notes/notes.jsonWindows 是C:\Users\你的用戶名\.pocket-notes\notes.json內(nèi)容與對話一致。這里補(bǔ)一句關(guān)于 Eval 的思路。mcp-builder 的 Phase 4 強(qiáng)調(diào)設(shè)計 Eval 驗(yàn)證 Agent 能否真正用好你的 Server。最簡單的 Eval 就是上面這三句話如果 Claude 能正確選 tool、正確填參、正確解讀返回說明你的 docstring 和 tool 設(shè)計到位了。如果它選錯 tool 或者參數(shù)填錯回去改 docstring而不是改代碼邏輯。5. 常見報錯排查401、local proxy failed 與 reading choices這一節(jié)對照真實(shí)報錯把最容易踩的坑列出來。注意本篇的本地 stdio Server 本身不涉及遠(yuǎn)程鑒權(quán)所以 401 這類錯誤通常出現(xiàn)在你后續(xù)接遠(yuǎn)程模型或 HTTP transport 的場景這里一并說清。先看 Inspector 連不上的情況。最常見原因是路徑問題python server.py用的是相對路徑但 Inspector 啟動時工作目錄可能變了。解決辦法是統(tǒng)一用絕對路徑npx modelcontextprotocol/inspector python /絕對路徑/server.py。第二個原因是環(huán)境不一致pip install mcp 裝的環(huán)境和運(yùn)行 server.py 的 python 不是同一個回到第 2 節(jié)用 venv 統(tǒng)一。再看/mcp里看不到 Server。先跑claude mcp list查狀態(tài)如果顯示未連接重啟 Claude Code。項目級.mcp.json首次加載需要交互批準(zhǔn)如果你跳過了批準(zhǔn)Server 不會生效。另外檢查 JSON 語法多一個逗號都會導(dǎo)致整個配置解析失敗。Tool 調(diào)用失敗時看終端里的 MCP 日志。FastMCP 會把異常打到 stderr如果日志里出現(xiàn)ModuleNotFoundError還是環(huán)境問題如果出現(xiàn)文件權(quán)限錯誤檢查~/.pocket-notes/目錄是否可寫。關(guān)于 401 和 local proxy failed這兩個報錯一般出現(xiàn)在你把 Server 接到遠(yuǎn)程模型網(wǎng)關(guān)做 Eval 的時候。401 是 Key 無效或過期去 https://taotoken.net/api-keys 重新生成local proxy failed 通常是本地網(wǎng)絡(luò)配置或 Base URL 寫錯確認(rèn)你填的是 https://taotoken.net/api 而不是別的地址。如果你在 Claude Code 里配了遠(yuǎn)程模型檢查 settings 里的 Base URL、Key、Model ID 三件套是否齊全缺一個都會失敗。關(guān)于reading choices報錯這通常出現(xiàn)在調(diào)用遠(yuǎn)程模型返回體解析時說明返回結(jié)構(gòu)和你預(yù)期的不一致多半是 Base URL 指向了錯誤的端點(diǎn)或者 Model ID 填了一個不存在的模型。對照接入文檔 https://taotoken.net/doc 確認(rèn)端點(diǎn)格式。關(guān)于 OAuth 報錯如果你用的是需要 OAuth 的遠(yuǎn)程 MCP Servertoken 過期會報這個。本地 stdio Server 不涉及但如果你在 Cline MCP 或 Codex 的 auth.json 里配了遠(yuǎn)程 Server檢查 token 是否刷新。想換 TypeScript 實(shí)現(xiàn)的話mcp-builder Skill 里有 node_mcp_server.md適合做遠(yuǎn)程 HTTP Server。Python 版適合本地快速驗(yàn)證TypeScript 版適合團(tuán)隊共享和部署?，F(xiàn)象處理Inspector 連不上用絕對路徑確認(rèn) python 和 pip install mcp 在同一環(huán)境/mcp 無 Server重啟 Claudeclaude mcp list 查狀態(tài)檢查 .mcp.json 語法Tool 調(diào)用失敗看終端 MCP 日志確認(rèn) venv 路徑一致401Key 無效去 api-keys 重新生成local proxy failed檢查 Base URL 是否為 https://taotoken.net/apireading choices端點(diǎn)或 Model ID 錯誤對照接入文檔OAuth 報錯遠(yuǎn)程 Server token 過期刷新 token想換 TypeScript看 Skill 內(nèi) node_mcp_server.md6. 把 Server 接到長期編碼流Coding Plan 與后續(xù)擴(kuò)展跑通第一個 Server 之后你大概率會想把它接到日常編碼流里讓 Claude 在寫代碼時順手調(diào)用你的內(nèi)部工具。這時候有幾個方向可以擴(kuò)展。第一個方向是把 stdio 換成 streamable HTTP讓團(tuán)隊共享。stdio 是單機(jī)進(jìn)程每個人都要本地裝一份HTTP transport 可以部署到內(nèi)網(wǎng)團(tuán)隊成員通過 URL 接入。mcp-builder 的 Skill 里有對應(yīng)的指引TypeScript 版更適合這個場景。第二個方向是擴(kuò)充 tool 覆蓋范圍。pocket-notes 只有三個 tool真實(shí)內(nèi)部系統(tǒng)往往需要十幾個。mcp-builder 的 Phase 1 規(guī)劃方法在這里很關(guān)鍵先列出所有 API 端點(diǎn)再決定哪些暴露成 tool、怎么命名、怎么分組。不要一股腦全暴露Agent 面對太多 tool 會選錯。第三個方向是接遠(yuǎn)程模型做 Eval。本地 stdio 不需要遠(yuǎn)程模型但如果你想批量測試 Agent 在不同模型下的 tool 調(diào)用準(zhǔn)確率就需要一個穩(wěn)定的模型網(wǎng)關(guān)。這時候 TaoToken 的 Coding Plan 比較合適適合長期編碼和 Agent 場景地址在 https://taotoken.net/coding-plan 。模型對話調(diào)試可以用 https://taotoken.net/models 控制臺在 https://taotoken.net/console 。如果你用的是 Claude Code 的 Anthropic 兼容接入配置片段大致是這樣注意 Base URL、Key、Model ID 三件套要齊全{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的Key, ANTHROPIC_MODEL: 你的ModelID } }Claude Code 的 Anthropic 接入文檔在 https://taotoken.net/claudecode-anthropic 里面有完整的 settings 示例。Cline MCP 和 Codex 的 auth.json 配置同理都是 Base URL 加 Key 加 Model ID缺一不可。最后說一個真實(shí)經(jīng)驗(yàn)MCP Server 的調(diào)試成本八成花在 docstring 和錯誤文案上而不是業(yè)務(wù)邏輯。業(yè)務(wù)邏輯你寫十行就完了但讓 Agent 正確選 tool、正確填參、正確解讀返回需要反復(fù)打磨 docstring。mcp-builder 的價值就在這——它把 MCP 工程規(guī)范沉淀成了可復(fù)用的方法你照著走能少踩很多坑。80 行 Python 走完編寫、Inspector、Claude Code 全鏈路這就是你的第一個 MCP Server。