為什麼貼上 JSON 後，客戶端還是連不上？

MCP 客戶端的設定不是「把一個工具名稱貼進去」而已。它還需要知道要啟動哪個本地程序、連到哪個遠端網址，以及用哪種傳輸方式和伺服器交換訊息。只要其中一項不一致，畫面上可能只出現「未連線」，但問題其實還沒有指向工具本身。

這篇文章把設定縮小成一個可檢查的模型：客戶端先建立連線，再完成 MCP 初始化與能力探索，最後才會把工具交給模型使用。你會看到兩種最常見的連線方式，以及它們在 Roo Code 裡的設定邊界。

先分清楚：本地程序和遠端網址不是同一種連線

如果伺服器和客戶端在同一台電腦上，客戶端通常會啟動一個子程序，透過標準輸入與標準輸出交換訊息。這種方式叫做 stdio，適合本地 Python 或 Node.js 伺服器；設定的重點是 command、args 與工作目錄。

{
  "mcpServers": {
    "local-weather": {
      "type": "stdio",
      "command": "python",
      "args": ["server.py"],
      "cwd": "C:/projects/local-weather"
    }
  }
}

cwd 不是裝飾欄位。如果伺服器用相對路徑載入檔案，工作目錄錯了，程序可能立即結束；客戶端看到的就只是連線失敗。Windows 下若要透過 npx 或其他 shell 指令啟動程序，Roo Code 的官方範例會使用 cmd /c 包住命令，避免 shell 找不到可執行檔。

如果伺服器已經部署在網路上，客戶端不應該再啟動本地程序，而是連到一個 MCP HTTP endpoint。現在的新部署應優先使用 Streamable HTTP：它以單一網址承接 HTTP 請求，必要時仍可在回應中串流 Server-Sent Events（SSE）訊息。舊式 SSE transport 仍可能存在，但屬於相容性路徑；看到 /sse 不代表它就是新伺服器的正確入口。

{
  "mcpServers": {
    "gradio": {
      "type": "streamable-http",
      "url": "https://example.hf.space/gradio_api/mcp/"
    }
  }
}

上面的網址是假設 Gradio 應用已經提供 MCP endpoint；第 6 篇會建立它，第 7 篇再把它放到 Hugging Face Spaces。真正使用時，應從伺服器自己的文件或 Gradio 的 View API → MCP 面板複製網址，不要猜測 /mcp、/sse 或其他路徑。

Roo Code 的設定檔應該放在哪裡？

Roo Code 提供兩個設定層級。全域設定放在擴充套件的 mcp_settings.json，會套用到所有工作區；專案設定放在專案根目錄的 .roo/mcp.json，只對目前專案生效。若兩邊有同名伺服器，專案設定優先。

因此可以這樣選：個人常用的本地工具放全域設定；需要和專案一起審查、分享或隔離的連線放 .roo/mcp.json。無論放在哪裡，檔案都應是含有 mcpServers 物件的 JSON，而不是把設定貼在文章、Shell 歷史或任意的 VS Code 設定欄位中。

Roo Code 的 MCP 面板可以開啟這兩個檔案。儲存後先確認伺服器出現在清單中，再確認工具清單能被載入；只有綠色連線指示，還不足以證明工具呼叫的輸入 schema 正確。

認證要放在哪裡，才不會變成另一個問題？

公開的 MCP endpoint 可以不帶認證；私有服務則通常需要 HTTP header。設定形式看起來像這樣：

{
  "mcpServers": {
    "private-gradio": {
      "type": "streamable-http",
      "url": "https://owner-space.hf.space/gradio_api/mcp/",
      "headers": {
        "Authorization": "Bearer <HUGGING_FACE_TOKEN>"
      }
    }
  }
}

HUGGING_FACE_TOKEN 只是佔位符，不能提交到 Git，也不應貼到截圖或公開 Issue。Hugging Face 的 User Access Token 以權限範圍取代密碼；只讀用途使用 read 或更細粒度的 token，推送 Space 才需要 write 權限。若客戶端支援環境變數或秘密管理，優先使用它；否則應把私有設定限制在本機，並在 token 外洩時立即撤銷或輪替。

認證錯誤和 transport 錯誤要分開排查：401 表示服務器收到請求但拒絕認證；404 或連不到 endpoint 則先檢查網址和傳輸類型；本地程序一啟動就退出，則檢查 command、args、cwd 和依賴環境。

一次設定的最小檢查順序

1. 先確認伺服器本身能單獨啟動，並記下它實際印出的 MCP URL。
2. 將 URL 或 stdio 命令放進正確層級的 mcpServers 設定。
3. 重新載入 Roo Code 的 MCP 面板，確認伺服器連線與工具清單都出現。
4. 對遠端 Gradio 服務再檢查 /gradio_api/mcp/schema，確認工具名稱、描述和輸入欄位符合預期。
5. 最後才允許特定工具自動執行；MCP 工具可能有檔案寫入、網路請求或其他副作用，不能把「連得上」等同於「可以無條件信任」。

這個順序把問題切成三層：程序能否啟動、transport 能否連線、工具 schema 是否可用。少了其中一層，客戶端的錯誤訊息往往會把真正原因藏在一起。

本文的版本邊界

Roo Code 的設定檔名稱與欄位可能隨擴充套件版本調整；MCP transport 也正在從 legacy SSE 過渡到 Streamable HTTP。因此本文保留穩定的設定概念與官方目前使用的欄位，但不把某個版本的 UI 位置、第三方伺服器名稱或固定錯誤畫面當成永久契約。遇到連線問題時，先以客戶端與伺服器當前文件列出的 endpoint 和 transport 為準。

參考資料

• Roo Code：Using MCP in Roo Code
• Model Context Protocol：Transports
• Model Context Protocol：Authorization
• Hugging Face：User access tokens
• Gradio：Building an MCP Server with Gradio