1. 從 stdio 到 Streamable HTTP一個 MCP 服務到底怎么跑起來MCPModel Context Protocol說白了就是給 AI 客戶端裝外設的協(xié)議。你寫一個 Server把本地能力查數(shù)據(jù)庫、讀文件、調內部 API暴露成 ToolCursor、Cline、Claude Desktop 這些 Host 就能通過統(tǒng)一的 JSON-RPC 調它。它解決的問題很具體以前每接一個 AI 客戶端就要寫一套適配現(xiàn)在寫一次 Server多個客戶端復用。這篇面向想讓本地工具被 AI 客戶端調用的開發(fā)者目標很明確——用官方 SDK 從零搭一個 MCP 服務先跑通 stdio再切到 Streamable HTTP最后用 Cline MCP 這類客戶端連上并成功調用工具。全程給可復制的代碼和配置不空談概念。先分清三個角色不然后面配置容易懵。Host 是用戶面對的應用持有模型和授權 UI比如 Cursor、Claude DesktopClient 是 Host 內部跟某一個 Server 的 1:1 連接Server 就是你要開發(fā)的那一端。模型不會直接打你的 API流程是模型想用工具 → Host 調 Client → Client 用 JSON-RPC 問 Server → 結果回給模型。Server 能提供的能力有 Tools、Resources、Prompts、Sampling、Roots多數(shù) Server 只實現(xiàn)一部分就夠。對 Agent 來說Tool 的 description 幾乎決定它會不會被正確調用所以寫清楚做什么、不做什么、何時用、參數(shù)含義比代碼本身還重要。傳輸方式選型也簡單stdio 適合本地開發(fā)和桌面/CLI標準輸入輸出最快上手日志只能打 stderrStreamable HTTP 適合遠程、多人、生產是當前推薦的遠程方案老的 HTTP SSE 已棄用新項目別用。建議路徑是先做 stdio 跑通用 Inspector 測工具再切 HTTP 上線。2. 前置準備SDK 選型、環(huán)境與 TaoToken 接入動手前先把 SDK 和環(huán)境定下來。TypeScript 用modelcontextprotocol/sdk生態(tài)最全Python 用mcp加 FastMCP對數(shù)據(jù)腳本和內部工具友好。我這邊用 Python 演示因為類型注解和 docstring 能自動變成 tool schema少寫一堆樣板。環(huán)境初始化用 uv干凈利落uv init weather cd weather uv venv source .venv/bin/activate uv add mcp[cli] httpx如果你打算讓 Server 內部去調大模型比如做 Sampling 或者自己封裝一個智能工具這里就涉及模型接入。我用 TaoToken 做統(tǒng)一入口它的 API 地址是https://taotoken.net/api兼容常見調用方式Key 在控制臺生成。模型對話入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 接入文檔在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。長期跑編碼類 Agent 的話Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。先把 Key 放進環(huán)境變量別硬編碼export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api定義工具表面這一步別跳過。先列清楚要暴露哪些 tool、名字和參數(shù)是什么、哪些只讀哪些會改數(shù)據(jù)、錯誤時返回什么讓模型能自己修正。設計完再寫代碼返工少一半。3. 可復制配置stdio 與 Streamable HTTP 兩套寫法先寫最小 Server。FastMCP 的寫法很直觀類型注解和 docstring 直接變成 schemafrom mcp.server.fastmcp import FastMCP mcp FastMCP(weather) mcp.tool() async def get_alerts(state: str) - str: Get weather alerts for a US state. Args: state: Two-letter US state code (e.g. CA, NY) return fAlerts for {state}: ... if __name__ __main__: mcp.run() # 默認 stdiostdio 模式下客戶端配置就是寫啟動命令。以 Cline MCP 或 Cursor 為例配置片段長這樣{ mcpServers: { weather: { command: uv, args: [--directory, /絕對路徑/weather, run, weather.py] } } }切到 Streamable HTTP 時Server 端改成監(jiān)聽端口if __name__ __main__: mcp.run(transportstreamable-http, host0.0.0.0, port8000)客戶端配置隨之變成 URL 形式單端點如/mcp{ mcpServers: { weather-http: { url: http://127.0.0.1:8000/mcp } } }如果你用 Codex 的auth.json或 Cline MCP 這類需要顯式聲明模型的地方三件套要寫全Base URL 填https://taotoken.net/apiKey 填你的TAOTOKEN_API_KEYModel ID 按你選的模型填。缺一個都會在連接階段報錯。stdio 有個硬規(guī)矩絕不能污染 stdout。print()默認寫 stdout會毀掉 JSON-RPCServer 會「莫名掛掉」。日志一律走 stderr 或 logging。這個坑我踩過排查了半天才發(fā)現(xiàn)是一行調試 print。4. 驗證請求Inspector 自測與客戶端調用成功結果別一上來就接 Agent先用 Inspector 自測。它能列出所有 tool、展示 schema、逐個調用比在對話里猜失敗原因快得多npx modelcontextprotocol/inspector python weather.py # 或 npx modelcontextprotocol/inspector node ./dist/server.js打開 UI 后你應該能看到get_alerts這個 tool參數(shù)state是 string 類型description 就是 docstring 的內容。手動傳CA調用返回Alerts for CA: ...說明 Server 本身沒問題。stdio 驗證通過后重啟客戶端Cline、Cursor 等在對話里讓它調用這個 tool。成功的標志是客戶端能識別到 Server 的 tools模型在需要時主動發(fā)起調用結果正確回填到對話里。如果模型不調八成是 description 太虛回去改文案。Streamable HTTP 的驗證類似先確認端口通了curl -i http://127.0.0.1:8000/mcp再在客戶端里用 URL 配置連接重復上面的調用流程。遠程部署時記得加鑒權公開端點無鑒權等于把內部能力暴露到公網推薦 OAuth 2.1 PKCE內網可以用 Bearer 或 mTLS。5. 本篇常見錯排查401、local proxy failed、reading choices、OAuth排錯時先看報錯落在哪一層協(xié)議層和業(yè)務層要分開。401 Unauthorized多半是 Key 沒傳對或沒帶上。檢查環(huán)境變量是否生效客戶端配置里 Base URL 和 Key 是否寫全。用 TaoToken 的話確認TAOTOKEN_BASE_URL是https://taotoken.net/apiKey 從 API Keys 頁面重新生成一次排除復制錯誤。local proxy failed通常是本地端口沒起來或地址寫錯。stdio 模式檢查啟動命令路徑是否為絕對路徑HTTP 模式確認host和port跟客戶端 URL 一致防火墻別擋。reading choices類報錯一般是返回結構不符合預期常見于 Server 內部調模型時響應格式沒對齊。檢查你解析響應的字段路徑確認模型返回的是標準結構。OAuth相關失敗遠程端點開了鑒權但客戶端沒配 token或者回調地址不匹配。先在內網用 Bearer 跑通再上 OAuth 2.1 PKCE別一步到位。還有一個高頻坑一個 Server 塞幾十個弱相關 tool導致模型選型混亂。拆成多個聚焦 Server 更好。tool 名是公開 API可增不可亂改名重命名等于破壞性變更。6. 從玩具到生產上線前的收尾與接入入口本地跑通只是第一步。上生產要補幾件事單獨開/healthz做健康檢查TLS 在反向代理終止打 latency 和錯誤率日志但慎打入參可能含敏感信息。默認做成無狀態(tài) HTTP 更易水平擴展只有需要服務端推送或斷線續(xù)傳時再上有狀態(tài) session。如果你要把這個 Server 接到編碼類 Agent 長期跑Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。需要生成和管理 Key 去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 完整接入步驟看 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 想先驗證模型效果可以直接在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 對話測試。Claude Code 相關接入參考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。最后提醒一句Skill 和 MCP 容易混。Skill 是 Markdown 說明書教 Agent「怎么做」MCP 是獨立進程或遠程服務給 Agent「能調用的真工具」。復雜場景兩者一起用Skill 規(guī)定何時調用哪些 MCP tools。先把 stdio 跑通再用 Inspector 驗證最后切 Streamable HTTP 上線這條路徑最穩(wěn)。