對遠端 Azure DevOps MCP 伺服器進行疑難排解

Azure DevOps 服務

本文將協助你診斷並解決 remote Azure DevOps MCP Server 常見問題。關於本地 MCP 伺服器的問題，請參閱本地 MCP 伺服器的故障排除指南。

連線失敗

找不到伺服器或網址錯誤

症狀： 你的 AI 助理無法連接到遠端的 MCP 伺服器，或者你會看到與 URL 相關的錯誤。

解決方法：

請在你的 mcp.json 中確認伺服器 URL 格式：

{
  "servers": {
    "ado-remote-mcp": {
      "url": "https://mcp.dev.azure.com/{organization}",
      "type": "http"
    }
  }
}

確認下列項目：
- 請使用 https://mcp.dev.azure.com/{organization} ——以您的組織名稱替換 {organization} 。
- 只使用組織名稱（例如 contoso），不要使用完整的 Azure DevOps 網址。
- 必須 type 是 "http"，不是 "stdio"。
若 URL 中省略組織名稱https://mcp.dev.azure.com/（），則必須在每次工具呼叫中提供組織名稱作為上下文。

網路或防火牆封鎖

症狀： 連線會逾時或被拒絕，但網址是正確的。

解決方法：

確保你的網路允許 HTTPS 外站流量到 mcp.dev.azure.com。
如果你用的是企業代理或防火牆，請確認沒有 mcp.dev.azure.com 被封鎖。請聯絡你的網路管理員，將此端點列入允許名單。
VPN 設定可能會干擾連線。試著不用 VPN 連線來找出問題所在。

認證錯誤

遠端 MCP 伺服器使用 Microsoft Entra ID（OAuth）進行認證。遠端伺服器不支援個人存取權杖（PAT）。

症狀： OAuth 登入提示不會出現，或是在你登入前驗證失敗。

解決方法：

確認你的帳號是否連結到 Microsoft Entra ID。遠端 MCP 伺服器需要 Microsoft Entra 支援的身份。
檢查你的瀏覽器是否能開啟 OAuth 流程。如果你在遠端或無頭環境使用 VS Code，OAuth 的重定向可能無法正常運作。
清除快取憑證：
- 在 VS Code 中，打開指令面板（Ctrl+Shift+P），執行 「帳號：登出」。然後再試一次連線。
- 如果問題依舊，請重新載入 VS Code 視窗（開發者：重新載入視窗）。

症狀： 你成功登入，但在嘗試存取你的組織或專案時出現授權錯誤。

解決方法：

確認你在Azure DevOps組織中有正確的access level。
確認你是你想存取的專案成員。
請確認你的 Azure DevOps 權限是否包含你查詢的資源（例如工作項目、倉庫或管線）的存取權。

條件存取政策阻擋存取

Symptom： Microsoft Entra 條件式存取政策會阻擋你的登入。

解決方法：

條件存取政策會像 Azure DevOps 一樣，適用於遠端 MCP 伺服器。如果您的租戶執行如基於位置或裝置的限制政策：

請確保你是從合規的裝置和網路地點登入。
如果你的租戶使用基於位置的條件存取政策，Microsoft Entra ID管理員可能需要將遠端 MCP 伺服器的 IP 位址列入允許清單：20.125.155.22 和 40.74.28.81。
如需具體政策要求，請聯絡您的 Microsoft Entra ID 管理員。

訪客（B2B）存取失敗

Symptom： Microsoft Entra租戶中的訪客使用者無法存取遠端 MCP 伺服器。

解決方法：

要存取訪客工作權限，使用者必須符合：

新增為Microsoft Entra租戶，成為 guest user。
已透過適當權限加入 Azure DevOps 組織。
獲得他們所需的特定專案與資源存取權。
使用組織專屬的 URL（https://mcp.dev.azure.com/{organization}）。訪客用戶不能使用根網址（https://mcp.dev.azure.com/）——他們必須在網址中包含組織名稱。

若缺少上述任何步驟，存取即告失敗。把這個問題當作標準的 Azure DevOps 訪客存取問題來處理。

`AADSTS` 錯誤碼

症狀： 你會看到一個以 AADSTS （例如 AADSTS50076，） AADSTS700016開頭的錯誤代碼。

解決方法：

AADSTS 錯誤是Microsoft Entra ID認證錯誤，而非 MCP 本身的問題。常見的代碼包括：

錯誤代碼	意義	Action
`AADSTS50076`	需要多重驗證	完成MFA題目
`AADSTS700016`	租戶中找不到申請表	請確認您的租戶設定
`AADSTS65001`	使用者或管理員都沒有同意	要求系統管理員同意應用程式
`AADSTS50105`	未指派給應用程式的使用者	聯絡你的管理員以分配存取權限

完整錯誤代碼清單請參見 Microsoft Entra 認證與授權錯誤碼。

Entra 問題

在租戶中找不到 Azure DevOps MCP 企業應用程式

你在 Microsoft Entra IDEnterprise>中找不到 Azure DevOps MCP 企業應用程式，遠端 MCP 伺服器認證失敗。

解決方法：

以下程序會在你的租戶中建立缺少的 Azure DevOps MCP 服務主體。

Note

此程序僅建立 Azure DevOps MCP 服務主體。它不會啟用不支援的客戶端、暴露自訂 MCP 資源受眾，或新增租戶中無法使用的委派範圍。

誰需要執行這個：在你的租戶中擁有 應用程式管理員、 雲端應用程式管理員或 全域管理員 權限的使用者。
Prerequisite： Install Azure CLI.
應用程式編號： 2a72489c-aab2-4b65-b93a-a91edccf33b8。

一步一步地執行，並保留指令輸出。

步驟0 - 登入您的房客（替換 <yourTenantId>）：

az login --tenant <yourTenantId> --allow-no-subscriptions

az account show --query "{tenant:tenantId, user:user.name}" -o table

確認租戶價值是否與你的租戶編號相符。

步驟一 - 確認應用程式目前不見：
```
az rest --method get --url "https://graph.microsoft.com/v1.0/servicePrincipals(appId='2a72489c-aab2-4b65-b93a-a91edccf33b8')"
```
預期結果：404 與 Request_ResourceNotFound。這個結果證實了這個問題。

步驟 2 - 在您的租戶中建立應用程式：

az ad sp create --id 2a72489c-aab2-4b65-b93a-a91edccf33b8

步驟 3 - 確認該應用程式現在是否存在：
```
az rest --method get --url "https://graph.microsoft.com/v1.0/servicePrincipals(appId='2a72489c-aab2-4b65-b93a-a91edccf33b8')"
```
期望結果： 200 包含 "displayName": "Azure DevOps MCP" 和 "accountEnabled": true的反應。
步驟 4 - 在入口網站確認：

前往 portal.azure.com>Microsoft Entra ID>Enterprise 應用程式，將應用程式類型設為所有應用程式，並搜尋 Azure DevOps MCP 或 2a72489c-aab2-4b65-b93a-a91edccf33b8。

應用程式現在應該會出現，你可以管理它的權限。

伺服器設定問題

不正確的`mcp.json`設定

症狀： 遠端 MCP 伺服器連線，但工具無法載入，或出現意想不到的行為。

解決方法：

請確認你 mcp.json 使用的是遠端伺服器的正確格式：

遠端伺服器 使用 "type": "http" 和 "url"。
本地伺服器 使用 "type": "stdio"、 "command"、 "args"。

不要混用遠端和本地的設定格式。不要同時開兩台伺服器——選擇其中一台：

遠端伺服器 - 推薦用於支援的環境，包括 Visual Studio Code、Visual Studio、Microsoft Foundry、Microsoft Copilot Studio 及 GitHub Copilot。無需本地安裝。
Local server — 用於不支援Microsoft Entra認證的非Microsoft用戶端（Claude Desktop、Claude Code、Cursor、Codex）。

工具組或工具篩選無法運作

症狀： 你設定了 X-MCP-Toolsets 或 X-MCP-Tools 標頭，但工具清單不符合預期。

解決方法：

不要合併使用 X-MCP-Toolsets 和 X-MCP-Tools 標頭——兩者互斥。
請確認工具組名稱正確：repos，， witwiki， pipelinesworktestplan。
使用 X-MCP-Tools時，請指定精確的工具名稱，並以逗號分隔。
檢查標頭名稱是否有錯字——標頭是大小寫區分的。

{
  "servers": {
    "ado-remote-mcp": {
      "url": "https://mcp.dev.azure.com/{organization}",
      "type": "http",
      "headers": {
        "X-MCP-Toolsets": "repos,wit"
      }
    }
  }
}

欲了解完整的可用工具組與工具清單，請參閱可用工具。

唯讀模式，不限制寫入

症狀： 您設定了 X-MCP-Readonly，但仍可進行寫入作業。

解決方法：

驗證標頭值為字串 "true"：

"headers": {
  "X-MCP-Readonly": "true"
}

工具解析錯誤

工具未出現在 AI 助理中

Symptom： 連接遠端 MCP 伺服器後，AI 助理中不會顯示任何Azure DevOps工具。

解決方法：

確認你的 IDE 伺服器狀態是否顯示為已連線。
- 在 VS Code 中，於 [輸出] 面板中查看 MCP 伺服器狀態（View>Output>，然後從下拉式選單選擇 GitHub Copilot 或 MCP）。
重新載入 VS Code 視窗（Ctrl+Shift+P>開發者：重新載入視窗）。
請確認你在GitHub Copilot中處於agent mode——MCP 工具只會出現在 Agent 模式，聊天模式不會。
請確認不要超過 128 個工具的上限。如果你設定了多個 MCP 伺服器，工具數量的總數可能會超過這個限制。

缺少必要參數的錯誤

症狀： 工具呼叫失敗時會出現「缺少所需參數」錯誤，通常是專案名稱。

解決方法：

此錯誤是最常見的錯誤，且是預期行為。許多工具需要專案名稱或其他上下文：

在提示詞中包含專案名稱：「列出 Contoso 專案中的工作項目。」
如果你在網址中省略了組織，請也在提示中包含該組織名稱。
有些工具需要特定的參數。請參考可用工具文件中的所需參數。

工具呼叫因伺服器錯誤而失敗

症狀： 工具在正確叫用後會傳回伺服器錯誤。

解決方法：

確認你查詢的資源是否存在（例如工作項目 ID、儲存庫名稱或管線 ID 是否正確）。
確認你有權限存取該資源。
如果錯誤依舊，請使用 Remote MCP Server 問題範本建立一個問題。

Copilot 整合問題

AI 助理不使用 MCP 工具

Symptom： GitHub Copilot 會回應你的問題，但不會使用 Azure DevOps MCP 工具來擷取資料。

解決方法：

確保你在GitHub Copilot中使用的是agent mode。 MCP 工具在標準聊天模式中無法使用。
在提示中明確說明你需要哪些 Azure DevOps 資料。例如，不要問「我的衝刺狀態如何？」改為「使用 Azure DevOps 取得我目前的衝刺工作項目」。
請確認 MCP 伺服器顯示已連接，並顯示綠色狀態指示。

回傳過時或快取的資料

Symptom： AI 助理回傳過時的Azure DevOps資料。

解決方法：

在提示中加入「不要使用先前取得的資料」以強制執行新查詢。 AI 助理可能會在對話中快取工具結果。

代理在工具呼叫前失敗

症狀： AI 助理在呼叫任何 MCP 工具前就會失敗或出錯。

解決方法：

這個問題超出 Azure DevOps MCP 的範圍。故障發生在 AI 助理的編排層：

關於GitHub Copilot問題，請參見 GitHub Copilot documentation。
重新啟動 AI 助理再試一次。
如果問題持續，請向你的 AI 助理服務提供者回報。

不支援的用戶端錯誤

非 Microsoft 用戶端無法驗證

症狀： 像 Claude Desktop、Claude Code、Cursor 或 Codex 這類用戶端無法與遠端 MCP 伺服器完成 OAuth 握手。

解決方法：

非 Microsoft 用戶端無法與遠端 MCP 伺服器進行驗證，因為 Microsoft Entra ID 目前不支援動態用戶端註冊，而這些用戶端需要這點。

目前支援的客戶端：

Visual Studio Code
Visual Studio（2022 及以後版本）
Microsoft Foundry
Microsoft Copilot Studio
GitHub Copilot
GitHub Copilot 命令列界面 (CLI)
GitHub Copilot 應用程式

對於非Microsoft用戶端，請使用 local Azure DevOps MCP Server搭配 PAT 或 Azure CLI 認證。不要同時同時運行遠端和本地伺服器——選擇與你客戶端相符的那個。

診斷技巧

啟用 VS Code 中的除錯日誌

為了在排除故障時記錄更多細節：

在 VS Code 中開啟輸出面板（查看>輸出）。
從輸出通道下拉選單選擇GitHub Copilot或MCP。
查看連線狀態、認證流程細節及錯誤訊息。

驗證連接

設定完成後，請用簡單的查詢測試遠端 MCP 伺服器：

「列出我 Azure DevOps 組織裡的專案。」
「展示我分配的工作項目。」
哪些提取要求需要我審查？

如果這些查詢回傳正確的資料，代表伺服器運作正常。

常見問題集

我可以用個人 Microsoft 帳戶使用遠端 MCP 伺服器嗎？

否。遠端 MCP 伺服器需要你的 Azure DevOps 組織連接到 Microsoft Entra ID。個人 Microsoft 帳號（MSA）不被支援。

我應該使用遠端伺服器還是本地的 MCP 伺服器？

如果你的環境支援，就用遠端伺服器。推薦使用遠端伺服器，因為它不需要本地安裝，且 Azure DevOps 負責管理更新。只有當你使用像 Claude Desktop、Claude Code、Cursor 或 Codex 這類無法與遠端伺服器認證的客戶端時，才使用本地伺服器。不要同時開兩台伺服器。

為什麼我看到遠端伺服器和本地伺服器的工具會不一樣？

遠端伺服器和本地伺服器的版本可能不同。遠端伺服器的更新獨立於本地 npm 套件。使用 X-MCP-Insiders 標頭存取最新的遠端工具。對於本地伺服器，請將 npm 套件更新到最新版本。

MCP 伺服器能與 Azure DevOps Server（本地）相容嗎？

否。遠端和本地 MCP 伺服器都不支援 Azure DevOps Server（本地端）。兩台伺服器都需要 Azure DevOps 服務（雲端）。

遠端 MCP 伺服器存取哪些資料？

遠端伺服器存取的 Azure DevOps 資料與 REST API 相同，且範圍是根據你的權限。它不會存取超出你 Microsoft Entra 身份授權看到的資料。

我該如何回報遠端 MCP 伺服器的問題？

請使用Azure DevOps MCP Server GitHub 倉庫中的 Remote MCP Server issue 模板來建立問題。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-07-31

對遠端 Azure DevOps MCP 伺服器進行疑難排解

連線失敗

找不到伺服器或網址錯誤

網路或防火牆封鎖

認證錯誤

登入提示失敗或未出現

登入後授權失敗

條件存取政策阻擋存取

訪客（B2B）存取失敗

AADSTS 錯誤碼

Entra 問題

在租戶中找不到 Azure DevOps MCP 企業應用程式

伺服器設定問題

不正確的mcp.json設定

工具組或工具篩選無法運作

唯讀模式，不限制寫入

工具解析錯誤

工具未出現在 AI 助理中

缺少必要參數的錯誤

工具呼叫因伺服器錯誤而失敗

Copilot 整合問題

AI 助理不使用 MCP 工具

回傳過時或快取的資料

代理在工具呼叫前失敗

不支援的用戶端錯誤

非 Microsoft 用戶端無法驗證

診斷技巧

啟用 VS Code 中的除錯日誌

驗證連接

常見問題集

我可以用個人 Microsoft 帳戶 使用遠端 MCP 伺服器嗎？

我應該使用遠端伺服器還是本地的 MCP 伺服器？

為什麼我看到遠端伺服器和本地伺服器的工具會不一樣？

MCP 伺服器能與 Azure DevOps Server（本地）相容嗎？

遠端 MCP 伺服器存取哪些資料？

我該如何回報遠端 MCP 伺服器的問題？

相關內容

意見反應

其他資源

`AADSTS` 錯誤碼

不正確的`mcp.json`設定

我可以用個人 Microsoft 帳戶使用遠端 MCP 伺服器嗎？