本地能跑，為什麼部署後還是不能用？

本地的 python app.py 成功，只能證明目前電腦有一個可啟動的 Gradio 程序。部署到 Hugging Face Spaces 之後，還多了三個邊界：Space 會以 Git repository 接收檔案、建置環境會重新安裝依賴、遠端 MCP client 必須連到公開或受保護的 HTTP endpoint。

因此部署問題最好拆成兩條線：Git 是否有權限把程式送進 Space，以及 Space 啟動後 MCP endpoint 是否真的存在。這也解釋了為什麼「推送成功」和「工具可用」不是同一個驗收條件。

Space 其實是一個會自動重建的 Git repository

建立 Space 時要選擇 owner、名稱、可見度和 SDK。對本文的 Gradio 範例，SDK 選 Gradio；Space 的程式碼會存放在 Hub 的 Git repository，每次新的 commit 推送後，Space 會自動 rebuild 並 restart。

Space 有 public、protected、private 三種可見度。public 會公開原始碼與執行中的應用；protected 可讓應用透過 embed URL 對外提供，但原始碼只給擁有者與協作者；private 則連應用也只對有權限的人開放。這個選擇會直接影響 MCP client 是否需要認證，不能等部署完成後才補想。

先把最小檔案放進 Space

第 6 篇的範例至少需要兩個檔案：app.py 和 requirements.txt。

app.py
requirements.txt

requirements.txt 讓 Space 的建置環境安裝 Gradio 的 MCP 依賴：

gradio[mcp]

不要把本地 Anaconda 的啟動命令當成 Space 的部署設定；Space 的建置會依照 repository 裡的依賴檔案工作。如果你的工具另有 TextBlob、資料庫 client 或模型套件，就把它們逐項寫入同一個檔案，並在本地用接近部署環境的乾淨環境測試。

建立 Space 後，可以先 clone 它，再提交檔案：

git clone https://huggingface.co/spaces/<owner>/<space-name>
cd <space-name>
# 將 app.py 與 requirements.txt 放進這個目錄
git add app.py requirements.txt
git commit -m "Deploy Gradio MCP server"
git push

這些指令只描述 Git 流程，不會替你建立 Space，也不會把任何真實 token 寫進 remote URL。

遇到 password authentication 失敗時，問題不是 Git commit

Hugging Face Hub 不把帳號密碼當成 Git 推送憑證。User Access Token 才是用於 Hub 存取的認證方式；write token 才能推送你有權限修改的 repository，read token 不能拿來部署更新。

可以使用官方 CLI 登入本機：

hf auth login

登入時貼上從 Hugging Face 設定頁建立的 token，讓 credential helper 保存它，再重新執行 git push。不要把 token 寫成下面這種會進入 Shell history 或 Git remote 設定的 URL：

https://<username>:<token>@huggingface.co/spaces/<owner>/<space-name>

如果 token 曾經出現在公開檔案、終端輸出或遠端 URL，先撤銷或輪替它，再重新建立最小權限的 token。這不是「再試一次 push」可以解決的普通連線錯誤。

推送成功後，怎麼確認 MCP 真的上線？

Space rebuild 完成後，先開啟它的網頁介面，再檢查 Gradio 的 MCP endpoint。對一個名為 [space-name]、位於 [owner] 底下的 Space，Gradio 文件使用的 URL 形狀是：

https://<owner>-<space-name>.hf.space/gradio_api/mcp/
https://<owner>-<space-name>.hf.space/gradio_api/mcp/schema

第一個是給 MCP client 的連線入口，第二個用來檢查工具 schema。client 設定可寫成：

{
  "mcpServers": {
    "remote-gradio": {
      "type": "streamable-http",
      "url": "https://<owner>-<space-name>.hf.space/gradio_api/mcp/"
    }
  }
}

如果 Space 是 private，或你的 Gradio server 需要保護工具，client 還必須帶上符合權限的 Authorization: Bearer … header。若是 public Space，先不要額外加入 token；把無關的認證變因排除後，才能知道 endpoint 是否本身可用。

四種常見失敗，要看哪一層？

Git 推送被拒絕。 先看 token 是否存在、是否有 write 權限、是否有推送到正確的 Space repository；不要修改 app.py 來處理 credential 問題。

建置失敗。 看 Space 的 build log，核對 requirements.txt 的套件名稱與 Python 相容性。若本地依賴只安裝在 Conda 環境、卻沒有寫進依賴檔，遠端建置不會知道它。

網頁能開，但 MCP URL 404。 先確認程式有 demo.launch(mcp_server=True)，再確認你使用的是目前 Gradio 文件列出的 /gradio_api/mcp/，而不是舊文章中的 /gradio_api/mcp/sse。這是 endpoint 或版本問題，不是 Hugging Face Git 認證問題。

MCP client 收到 401 或工具呼叫失敗。 先確認 Space 的可見度與 server 的認證策略，再檢查 client 是否送出正確的 Bearer token。token 應放在秘密管理或本機受限設定中，不能寫進 app.py 或提交到 Space。

最後還有一個容易被忽略的生命週期限制：免費或低成本的硬體可能在一段時間沒有使用後進入睡眠，第一次請求可能需要等待重新啟動。這不是 MCP schema 錯誤；部署驗證應分別記錄 build、啟動、endpoint 與第一次呼叫的結果。

這篇指南證明到哪裡？

它建立的是一條可重複檢查的部署路徑，不宣稱任何未實際部署的 Space 已經在生產環境可用。真正的完成條件是：Git push 有明確的認證結果、Space build log 成功、網頁可開、MCP schema 可讀、client 能以正確 transport 完成一次工具呼叫。少了最後兩項，看到「Space Running」仍不足以說明 MCP 已經可用。

參考資料

• Hugging Face：Spaces Overview
• Hugging Face：User access tokens
• Hugging Face Hub：Authentication / hf auth login
• Gradio：Building an MCP Server with Gradio
• Model Context Protocol：Transports