リモート Azure DevOps MCP サーバーのトラブルシューティング

Azure DevOps サービス

この記事は、リモート Azure DevOps MCP Server に関する一般的な問題を診断して解決するのに役立ちます。 ローカル MCP サーバーの問題については、 ローカル MCP サーバーのトラブルシューティング ガイドを参照してください。

接続の失敗

サーバーが見つからないか URL エラー

症状： AI アシスタントがリモート MCP サーバーに接続できないか、URL 関連のエラーが表示されます。

解決方法:

  1. mcp.jsonでサーバー URL 形式を確認します。

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

  2. 次の内容を確認します。

    • https://mcp.dev.azure.com/{organization}を使用する - {organization}を実際の組織名に置き換えます。
    • 完全なAzure DevOps URL ではなく、組織名 (contoso など) のみを使用します。
    • typeは"http"ではなく、"stdio"する必要があります。

  3. URL (https://mcp.dev.azure.com/) から組織名を省略した場合は、各ツール呼び出しでコンテキストとして組織名を指定する必要があります。

ネットワークブロックまたはファイアウォールブロック

症状： 接続がタイムアウトするか拒否されましたが、URL は正しいです。

解決方法:

  • ネットワークで、 mcp.dev.azure.comへの送信 HTTPS トラフィックが許可されていることを確認します。
  • 企業プロキシまたはファイアウォールの背後にいる場合は、 mcp.dev.azure.com がブロックされていないことを確認します。 このエンドポイントを許可リストするには、ネットワーク管理者に問い合わせてください。
  • VPN 構成が接続を妨げる可能性があります。 問題を特定するには、VPN なしで接続してみてください。

プレビューの可用性

症状： サービスが使用できないことを示すエラーが表示されます。

解決方法:

リモート MCP サーバーはパブリック プレビュー段階にあり、段階的にロールアウトされています。 接続できない場合:

  • 組織が Microsoft Entra ID に接続されていることを確認します。
  • プレビューが引き続き拡張されるため、後でもう一度確認してください。
  • ポリシーによってプレビュー機能がブロックされていないことを組織の管理者に確認します。

認証エラー

リモート MCP サーバーは、認証に Microsoft Entra ID (OAuth) を使用します。 リモート サーバーでは、個人用アクセス トークン (AT) はサポートされていません。

サインイン プロンプトが失敗するか、表示されない

症状： OAuth サインイン プロンプトが表示されないか、サインインする前に認証が失敗します。

解決方法:

  1. アカウントがMicrosoft Entra IDに接続されていることを確認します。 リモート MCP サーバーには、Microsoft Entraに基づく ID が必要です。
  2. ブラウザーで OAuth フローを開くことができることを確認します。 リモート環境またはヘッドレス環境で VS Code を使用すると、OAuth リダイレクトが正しく機能しない可能性があります。
  3. キャッシュされた資格情報をクリアします。
    • VS Code でコマンド パレット (Ctrl + Shift + P) を開き、[ アカウント: サインアウト] を実行します。次に、接続をもう一度試します。
    • 問題が解決しない場合は、VS Code ウィンドウを再度読み込みます (開発者: ウィンドウの再読み込み)。

サインイン後の承認エラー

症状： 正常にサインインしますが、組織またはプロジェクトにアクセスしようとすると承認エラーが発生します。

解決方法:

  • Azure DevOps組織に正しい access レベルがあることを確認します。
  • アクセスしようとしているプロジェクトのメンバーであるかどうかを確認します。
  • 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 サーバーにアクセスできません。

解決方法:

ゲスト アクセスを機能させるには、次のユーザーが必要です。

  1. Microsoft Entra テナントに ゲスト ユーザーとして追加されます。
  2. 適切なアクセス許可を持つAzure DevOps組織に追加されました。
  3. 必要な特定のプロジェクトとリソースへのアクセス権が付与されます。
  4. 組織固有の URL (https://mcp.dev.azure.com/{organization}) の使用。 ゲスト ユーザーはルート URL (https://mcp.dev.azure.com/) を使用できません。URL に組織名を含める必要があります。

これらの手順のいずれかが不足している場合、アクセスは失敗します。 この問題は、標準的なAzure DevOpsゲスト アクセスの問題と同じように扱います。

AADSTS エラー コード

症状：AADSTSで始まるエラー コードが表示されます (たとえば、AADSTS50076、AADSTS700016)。

解決方法:

AADSTS エラーは認証エラー Microsoft Entra IDであり、MCP 固有の問題ではありません。 一般的なコードには、次のようなものがあります。

エラー コード 意味 アクション
AADSTS50076 多要素認証が必要 MFA プロンプトを完了する
AADSTS700016 テナントにアプリケーションが見つかりません テナント構成を確認する
AADSTS65001 ユーザーまたは管理者が同意しなかった アプリケーションの管理者の同意を要求する
AADSTS50105 ユーザーがアプリケーションに割り当てられない 管理者に連絡してアクセス権を割り当てる

エラー コードの完全な一覧については、「Microsoft Entra認証と承認のエラー コードを参照してください。

サーバー構成の問題

正しくない mcp.json 構成

症状： リモート MCP サーバーは接続しますが、ツールが読み込まれないか、予期しない動作が発生します。

解決方法:

mcp.jsonでリモート サーバーの正しい形式が使用されていることを確認します。

  • リモート サーバー は、 "type": "http" と "url"を使用します。
  • ローカル サーバー では、 "type": "stdio"、 "command"、および "args"が使用されます。

リモート構成形式とローカル構成形式を混在させないでください。 両方のサーバーを同時に実行しないでください。次のいずれかを選択します。

  • Remote server — Visual Studio CodeおよびVisual Studioに使用します。 ローカル インストールは必要ありません。
  • ローカル サーバー — Microsoft Entra認証をサポートしていない非Microsoft クライアント (Claude Desktop、Claude Code、Cursor、Codex) に使用します。

ツールセットまたはツールのフィルター処理が機能しない

症状：X-MCP-ToolsetsまたはX-MCP-Toolsヘッダーを構成しますが、ツールの一覧が期待値と一致しません。

解決方法:

  • X-MCP-ToolsetsヘッダーとX-MCP-Toolsヘッダーを組み合わせないでください。これらは相互に排他的です。
  • ツールセット名が正しいことを確認します( repos、 wit、 wiki、 pipelines、 work、 testplan)。
  • 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ツールは表示されません。

解決方法:

  1. サーバーの状態が IDE で接続済みとして表示されたことを確認します。
    • VS Code では、 出力パネルで MCP サーバーの状態を確認します (View>Output> ドロップダウンから GitHub Copilot または MCP を選択します)。
  2. VS Code ウィンドウを再度読み込みます (Ctrl + Shift + P>Developer: Reload Window)。
  3. GitHub Copilotで agent モードを使用していることを確認します。MCP ツールは、チャット モードではなくエージェント モードでのみ表示されます。
  4. 128 ツールの制限を超えないようにします。 複数の MCP サーバーが構成されている場合、結合されたツール数がこの制限を超える可能性があります。

必須パラメーターがありませんエラー

症状： ツールの呼び出しは、通常はプロジェクト名の "必要なパラメーターがありません" エラーで失敗します。

解決方法:

このエラーは最も一般的に報告されるエラーであり、予期される動作です。 多くのツールには、プロジェクト名またはその他のコンテキストが必要です。

  • プロンプトに「 Contoso プロジェクトの作業項目を一覧表示する」というプロジェクト名を含めます。
  • URL から組織を省略した場合は、プロンプトにも組織を含めます。
  • 一部のツールでは、特定のパラメーターが必要です。 必要なパラメーターについては、 使用可能なツール のドキュメントを参照してください。

ツールの呼び出しがサーバー エラーで失敗する

症状： ツール呼び出しは、正しく呼び出された後にサーバー エラーを返します。

解決方法:

  • クエリを実行しているリソースが存在することを確認します (たとえば、作業項目 ID、リポジトリ名、パイプライン ID が正しい場合など)。
  • リソースにアクセスするためのアクセス許可があることを確認します。
  • エラーが解決しない場合は、 リモート MCP サーバーの問題テンプレートを使用して問題を作成します。

Copilot統合の問題

AI アシスタントが MCP ツールを使用しない

Symptom: GitHub Copilot は質問に応答しますが、Azure DevOps MCP ツールを使用してデータを取得することはありません。

解決方法:

  1. GitHub Copilotで agent モードを使用していることを確認します。 MCP ツールは、標準チャット モードでは使用できません。
  2. プロンプトで、必要なAzure DevOpsデータについて明示的に指定します。 たとえば、"スプリントの状態は何ですか" ではなく、"Azure DevOpsを使用して現在のスプリント作業項目を取得する" を試します。
  3. MCP サーバーが緑色のステータス インジケーターで接続済みとして表示されていることを確認します。

古いデータまたはキャッシュされたデータが返される

Symptom: AI アシスタントは古いAzure DevOps データを返します。

解決方法:

"以前にフェッチされたデータを使用しない" をプロンプトに追加して、新しいクエリを強制します。 AI アシスタントは、会話セッション内でツールの結果をキャッシュする場合があります。

ツール呼び出し前にエージェントが失敗する

症状： AI アシスタントは、MCP ツールを呼び出す前に失敗またはエラーが発生します。

解決方法:

この問題は、Azure DevOps MCP 境界の外側にあります。 このエラーは、AI アシスタントのオーケストレーション レイヤーで発生します。

  • GitHub Copilotの問題については、GitHub Copilotドキュメントを参照してください。
  • AI アシスタントを再起動して、もう一度やり直してください。
  • 問題が解決しない場合は、AI アシスタント プロバイダーに報告してください。

サポートされていないクライアント エラー

Microsoft以外のクライアントは認証できません

症状： Claude Desktop、Claude Code、Cursor、Codex などのクライアントは、リモート MCP サーバーで OAuth ハンドシェイクを完了できません。

解決方法:

Microsoft 以外のクライアントは、これらのクライアントに必要な動的クライアント登録を Microsoft Entra ID が現時点ではサポートしていないため、リモート MCP サーバーに対して認証できません。

現在サポートされているクライアント:

  • Visual Studio Code
  • Visual Studio (2022 以降)

Microsoft以外のクライアントの場合は、代わりに PAT 認証または Azure CLI 認証で local Azure DevOps MCP Server を使用します。 リモート サーバーとローカル サーバーの両方を同時に実行しないでください。クライアントに一致するものを選択してください。

診断のヒント

VS Code でデバッグ ログを有効にする

トラブルシューティングの際に詳細をキャプチャするには:

  1. VS Code (View>Output) で [出力] パネルを開きます。
  2. 出力チャネルのドロップダウンから GitHub Copilot または MCP を選択します。
  3. 接続の状態、認証フローの詳細、およびエラー メッセージを探します。

接続を確認する

セットアップ後、簡単なクエリでリモート MCP サーバーをテストします。

  • "Azure DevOps 組織内のプロジェクトを一覧表示します。"
  • "割り当てられた作業項目を表示する"
  • 自分のレビューが必要なプル リクエストはどれですか?

これらのクエリが正しいデータを返す場合、サーバーは正常に動作しています。

FAQs

個人用Microsoft アカウントでリモート MCP サーバーを使用できますか?

No. リモート MCP サーバーでは、Azure DevOps組織をMicrosoft Entra IDに接続する必要があります。 個人用Microsoft アカウント (MSA) はサポートされていません。

リモートまたはローカルの MCP サーバーを使用する必要がありますか?

クライアントでサポートされている場合は、リモート サーバーを使用します (Visual Studio CodeまたはVisual Studio)。 ローカル サーバーは、Claude Desktop、Claude Code、Cursor、Codex などのMicrosoft以外のクライアントを使用している場合にのみ使用します。 両方のサーバーを同時に実行しないでください。

リモート サーバーとローカル サーバーで異なるツールが表示されるのはなぜですか?

リモート サーバーとローカル サーバーのバージョンが異なる場合があります。 リモート サーバーは、ローカル npm パッケージとは別に更新されます。 X-MCP-Insiders ヘッダーを使用して、最新のリモート ツールにアクセスします。 ローカル サーバーの場合は、npm パッケージを最新バージョンに更新します。

MCP サーバーは Azure DevOps Server (オンプレミス) で動作しますか?

No. リモートとローカルの MCP サーバーはどちらも、Azure DevOps Server (オンプレミス) をサポートしません。 どちらのサーバーにも、Azure DevOps サービス (クラウド) が必要です。

リモート MCP サーバーはどのデータにアクセスしますか?

リモート サーバーは、ユーザーのアクセス許可の範囲内で、REST API と同じ Azure DevOps のデータにアクセスします。 Microsoft Entra ID が表示する権限を超えてデータにアクセスすることはありません。

リモート MCP サーバーに関する問題を報告するにはどうすればよいですか?

Azure DevOps MCP Server GitHub リポジトリの Remote MCP Server 問題テンプレートを使用して問題を作成します。

関連するコンテンツ

  • Last updated on