排除 Azure Container Apps 上 MCP 伺服器的故障

本文將介紹您在 Azure 容器應用上部署及使用 MCP 伺服器時可能遇到的常見問題。問題依類別分類，除非另有說明，適用於獨立容器應用程式及平台管理的動態會話。

連接與進入

連線問題會阻止 MCP 用戶端存取你的伺服器。這些問題通常與入口設定、DNS 或網路政策有關。

MCP 用戶端無法連上伺服器

症狀：從 VS Code、GitHub Copilot 或其他 MCP 用戶端連接時，連線逾時或 DNS 解析失敗。

原因和解決方案：

原因	解決方法
輸入並未設定為`external`	執行 `az containerapp ingress show` 進行驗證。設定 `external: true` 為公開存取。
FQDN 是錯誤的	執行`az containerapp show --query properties.configuration.ingress.fqdn`以獲得正確的主機名稱。
TLS 憑證問題	容器應用程式提供受管理的 TLS。如果你使用自訂網域，請確認憑證綁定正確。
客戶端被防火牆保護	確保允許輸出 HTTPS (連接埠 443) 進行`*.azurecontainerapps.io`。

錯誤的終點路徑

症狀：404 Not Found連接 MCP 伺服器時。

正確的端點路徑取決於你的 MCP SDK 和路由設定。

Framework	共同終點路徑	註釋
.NET （`MapMcp`）	`/mcp`	路徑與`MapMcp("/mcp")`中的路由相符
Python（FastMCP 掛載於 FastAPI）	`/mcp`	在 FastAPI 上的`/`掛載 SDK 應用程式；SDK 會新增`/mcp`
Python（FastMCP 獨立版）	`/mcp`	當 FastMCP 直接執行且未掛載時
Node.js（Express）	`/mcp`	路線與快線路線相符
Java（Spring Boot SSE）	`/mcp`	SSE 傳輸; 在建構子中設定的 `WebMvcSseServerTransportProvider` 路徑
平台管理的會話	值來自 `mcpServerEndpoint`	完整網址由 Azure 資源管理器（ARM）API 提供;從 session pool 屬性中取得

Python 中 404 錯誤的常見原因是將 FastMCP 應用程式掛載在 FastAPI 路由器的 /mcp，而不是 /。由於 SDK 會新增自己的/mcp子路徑，在/mcp掛載會產生/mcp/mcp端點。掛載於 / ，因此最終路徑為 /mcp。

透過 curl 測試端點回應：

curl -X POST "https://<APP_NAME>.azurecontainerapps.io/mcp" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":"1","method":"initialize"}'

瀏覽器用戶端中的 CORS 錯誤

在瀏覽器控制台中的徵兆： Access to fetch has been blocked by CORS policy。

備註

GitHub Copilot 在 VS Code 桌面版不使用 CORS 瀏覽器。此問題僅影響瀏覽器 MCP 用戶端或 Web 的 VS Code。

解決方案：在容器應用程式中設定 CORS：

az containerapp ingress cors update \
    --name <APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --allowed-origins "https://your-trusted-domain.com" \
    --allowed-methods "GET" "POST" "OPTIONS" \
    --allowed-headers "Content-Type" "Authorization" "Mcp-Session-Id"

警告

為了排除故障，你可以暫時設定 --allowed-origins "*"。對於生產部署，允許的來源限制為特定的受信任網域。請參閱容器應用程式上的安全 MCP 伺服器以獲得指引。

協議與傳輸

協定錯誤發生於 MCP 用戶端與伺服器間的 JSON-RPC 訊息格式錯誤或使用不匹配的傳輸方式。

「找不到方法」回應

徵兆：具有 error.code: -32601 的JSON-RPC 回覆。

原因：

在initialize之前發送請求。永遠要先寄出 initialize 。
方法名稱拼錯了。使用 tools/list 和 tools/call（使用斜線，不是點號）。
使用 SSE 方法名稱搭配 HTTP 傳輸，或反之。

JSON-RPC 包裝遺失或格式錯誤

症狀： 400 Bad Request 或 Parse error (-32700)。

解決方案：確保每個請求都包含必要的 JSON-RPC 欄位：

{
    "jsonrpc": "2.0",
    "id": "unique-request-id",
    "method": "tools/call",
    "params": { ... }
}

必須是字串或數字id。 jsonrpc 欄位必須正好是 "2.0" 。

運輸不匹配

症狀：SSE 用戶端會出現 404 或 405 錯誤。 HTTP 用戶端收到意想不到的 text/event-stream 內容類型。

MCP 支援多重傳輸。確保你的客戶端和伺服器使用相同的傳輸方式。

伺服器傳輸	用戶端應使用
可串流 HTTP （`StreamableHTTPServerTransport`）	HTTP POST 到端點
SSE（`SSEServerTransport`）	SSE 連線加上 POST 來傳送訊息
平台管理（會話）	HTTP POST 搭配 `x-ms-apikey` 標頭

大多數現代 MCP SDK 預設使用 Streamable HTTP。如果你連接的是使用 SSE 的伺服器（舊款常見），請將客戶端切換到 SSE 模式。

備註

Java 教學使用 SSE 傳輸（WebMvcSseServerTransportProvider），因為 MCP Java SDK 尚未提供穩定的可串流 HTTP 傳輸。從 VS Code 連線時，選擇 SSE 並輸入 "type": "sse".vscode/mcp.json。

部署與擴展

部署問題會阻礙容器啟動或正確回應。這些問題通常與健康探針、埠配置或縮放設定有關。

容器未通過健康檢查

症狀：容器會反覆重啟。日誌顯示健康探針故障。

原因：預設的啟動與活絡探測會向容器的埠發送 HTTP GET 請求。 MCP 端點通常只接受 POST 請求。

解決方案：在您的應用程式中新增一個專用 GET /health 端點，回傳 200 OK。接著，將你的容器應用程式探測設定為使用這個端點。不要把健康探針指向 MCP 端點。

以下範例新增了一個指向 /health 路徑的啟動探針：

az containerapp update \
    --name <APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --yaml probe-config.yaml

其中 probe-config.yaml 包含探針配置：

properties:
  template:
    containers:
      - name: mcp-server
        probes:
          - type: startup
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          - type: liveness
            httpGet:
              path: /health
              port: 8080
            periodSeconds: 30

端口不匹配

徵兆：容器啟動，但輸入又傳回502 Bad Gateway。

原因：容器監聽的連接埠與容器應用程式輸入預期的不同。

解決方法：確認埠口設定：

# Check the target port
az containerapp ingress show \
    --name <APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --query targetPort

# Update if needed
az containerapp ingress update \
    --name <APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --target-port 8080

確保 PORT 你的應用程式中的環境變數與目標埠相符。

冷啟動延遲

症狀：在一段不活動後，第一次請求需等待10到30秒。

原因：容器應用程式預設會縮放到零。第一個要求觸發冷啟動。

解決方案：

將最小複本數設為 1： az containerapp update --name <APP_NAME> --resource-group <RESOURCE_GROUP> --min-replicas 1
增加健全狀態探查逾時以配合冷啟動時間。
對於會話 MCP，平台負責管理可用性。設定 coolDownPeriodInSeconds 的目的在於控制個別會話的壽命，而非影響池的可用性。

Authentication

認證問題通常是因為你使用錯誤的憑證類型來處理你的主機模型。下表總結了正確的認證方法。

裝載模型	正確的標頭	常見錯誤
獨立 + 內建認證	`Authorization: Bearer <TOKEN>`	使用 `x-ms-apikey`
動態會話 MCP	`x-ms-apikey: <KEY>`	使用 `Authorization: Bearer`

401 未經授權：獨立容器應用程式

症狀： 401 Unauthorized 連接啟用內建認證的 MCP 伺服器時的反應。

檢查清單：

確認持有人令牌的有效性： az account get-access-token --resource <APP_ID> --query accessToken
確認令牌是否已經在 Authorization 標頭中傳送。
請確認 Microsoft Entra 應用程式註冊是否與 audience 你申請的資源相符。
確認設定。--unauthenticated-client-action Return401 阻擋未驗證的請求; AllowAnonymous 讓他們通過。

認證錯誤：動態會話 MCP

症狀：呼叫平台管理的 MCP 端點時出現認證錯誤。錯誤可能以 HTTP 401 回應的形式出現，或在回應主體中以 JSON-RPC 錯誤訊息的形式出現。錯誤類型取決於故障發生在請求管線的哪個位置。

檢查清單：

確保 API 金鑰是透過 x-ms-apikey 標頭（而不是 Authorization）傳送。
確認金鑰來自 fetchMCPServerCredentials，而不是來自其他 API。
如果您最近重新產生金鑰，請等最多五分鐘讓舊金鑰快取過期。
請檢查mcpServerSettings.isMCPServerEnabled 是true在工作階段集區上。

欲了解更多資訊，請參閱認證指南。

動態工作階段

本節問題僅適用於動態會話中的平台管理 MCP 伺服器。關於獨立容器應用程式的問題，請參見前述章節。

找不到環境識別碼

徵兆：tools/call回覆包括有關環境或工作階段不存在的錯誤。

原因：

該工作階段已過期 (超過coolDownPeriodInSeconds)。
environmentId 沒有從 launchShell 回應中正確提取。
您使用的是來自不同工作階段集區的環境識別碼。

解決方案：再次通話 launchShell 以建立新環境。

MCP 未在會話池啟用

症狀：在會話池屬性中不存在mcpServerEndpoint。

解決方案：確認 MCP 是否啟用：

az rest --method GET \
    --uri "https://management.azure.com/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.App/sessionPools/<SESSION_POOL_NAME>" \
    --uri-parameters api-version=2025-02-02-preview \
    --query "properties.mcpServerSettings"

如果 isMCPServerEnabled 是 false 或欄位缺失，則重新部署會話池與 mcpServerSettings 區塊。

區域可用性

症狀：部署失敗，出現「此區域無法使用」錯誤。

原因：在預覽期間，部分 Azure 區域可使用動態 MCP 會話。

解決方法：請查看會議文件中目前支援區域的清單。

診斷與除錯

請在提出支援申請前，請使用以下技巧蒐集診斷資訊。

使用診斷並解決問題工具

Azure 入口網站為你的容器應用程式提供內建的診斷功能。

登入 Azure 入口網站。
打開你的容器應用程式。
在導覽列中，選取 [診斷並解決問題]。
選擇與你問題相關的故障排除類別。

檢視容器日誌

從你的容器應用程式串流日誌，查看應用程式輸出和錯誤：

az containerapp logs show \
    --name <APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --follow

在使用 MCP 用戶端之前先使用 curl 進行測試

在設定 GitHub Copilot 或其他 MCP 用戶端前，請使用 curl 來確認伺服器的回應是否正確：

# 1. Initialize
curl -sS -X POST "https://<APP_NAME>.azurecontainerapps.io/mcp" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":"1","method":"initialize"}'

# 2. List tools
curl -sS -X POST "https://<APP_NAME>.azurecontainerapps.io/mcp" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":"2","method":"tools/list"}'

如果兩個指令都回傳有效的 JSON-RPC 回應，代表伺服器正在運作，問題很可能出在用戶端設定。

在 VS Code 中檢查 MCP 日誌

如果你使用 GitHub Copilot 作為 MCP 客戶端，請查看內建的 MCP 日誌：

打開輸出面板（查看 > 輸出）。
從下拉選單選擇 GitHub Copilot Chat - MCP 。
檢查連線錯誤、認證失敗或工具調用問題。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-03-02