Rozwiązywanie problemów z zdalnym serwerem Azure DevOps MCP

usługi Azure DevOps

Ten artykuł ułatwia diagnozowanie i rozwiązywanie typowych problemów z remote Azure DevOps MCP Server. Aby uzyskać informacje o lokalnych problemach z serwerem MCP, zobacz przewodnik rozwiązywania problemów z lokalnym serwerem MCP.

Awarie połączenia

Nie znaleziono serwera lub wystąpiły błędy adresu URL

Objawem: Asystent sztucznej inteligencji nie może nawiązać połączenia z zdalnym serwerem MCP lub widzisz błędy związane z adresem URL.

Rozwiązanie:

1. Sprawdź format adresu URL serwera w pliku mcp.json:

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

2. Upewnij się, że:

   • Użyj https://mcp.dev.azure.com/{organization} — zastąp {organization} rzeczywistą nazwą swojej organizacji.
   • Użyj tylko nazwy organizacji (na przykład contoso), a nie pełnego adresu URL Azure DevOps.
   • Musi type mieć wartość "http", a nie "stdio".

3. Jeśli pominięto nazwę organizacji z adresu URL (https://mcp.dev.azure.com/), musisz podać nazwę organizacji jako kontekst w każdym wywołaniu narzędzia.

Bloki sieci lub zapory

Objawem: Przekroczono limit czasu lub odrzucono połączenie, ale adres URL jest poprawny.

Rozwiązanie:

• Upewnij się, że Twoja sieć zezwala na wychodzący ruch HTTPS do mcp.dev.azure.com.
• Jeśli znajdujesz się za firmowym serwerem proxy lub zaporą, sprawdź, czy mcp.dev.azure.com nie jest on zablokowany. Skontaktuj się z administratorem sieci, aby dodać ten punkt końcowy do listy dozwolonych.
• Konfiguracje sieci VPN mogą zakłócać łączność. Spróbuj nawiązać połączenie bez sieci VPN, aby wyizolować problem.

Błędy uwierzytelniania

Zdalny serwer MCP używa Microsoft Entra ID (OAuth) do uwierzytelniania. Osobiste tokeny dostępu (PATs) nie są obsługiwane dla serwera zdalnego.

Monit logowania kończy się niepowodzeniem lub nie jest wyświetlany

Objawem: Monit logowania OAuth nie jest wyświetlany lub uwierzytelnianie nie powiedzie się, zanim będzie można się zalogować.

Rozwiązanie:

1. Sprawdź, czy twoje konto jest połączone z Microsoft Entra ID. Zdalny serwer MCP wymaga tożsamości opartej na usłudze Microsoft Entra.
2. Sprawdź, czy można otworzyć przeglądarkę na potrzeby przepływu OAuth. Jeśli używasz programu VS Code w środowisku zdalnym lub bezgłowym, przekierowanie OAuth może nie działać poprawnie.
3. Wyczyść buforowane poświadczenia:
   • W programie VS Code otwórz paletę poleceń (Ctrl+Shift+P) i uruchom konta: wyloguj się. Następnie spróbuj ponownie nawiązać połączenie.
   • Jeśli problem będzie się powtarzać, załaduj ponownie okno programu VS Code (deweloper: okno ponownego ładowania).

Niepowodzenie autoryzacji po zalogowaniu

Objawem: Logowanie powiodło się, ale podczas próby uzyskania dostępu do organizacji lub projektu wystąpił błąd autoryzacji.

Rozwiązanie:

• Upewnij się, że masz prawidłowy poziom access w organizacji Azure DevOps.
• Sprawdź, czy jesteś członkiem projektu, do którego próbujesz uzyskać dostęp.
• Sprawdź, czy Twoje uprawnienia w Azure DevOps obejmują dostęp do zasobów, o które wysyłasz zapytania (na przykład elementów roboczych, repozytoriów lub potoków).

Zasady dostępu warunkowego blokują dostęp

Symptom: zasady Dostęp warunkowy usługi Microsoft Entra blokują logowanie.

Rozwiązanie:

Zasady dostępu warunkowego mają zastosowanie do zdalnego serwera MCP w taki sam sposób, jak mają zastosowanie do Azure DevOps. Jeśli dzierżawa wymusza zasady, takie jak ograniczenia oparte na lokalizacji lub oparte na urządzeniach:

• Upewnij się, że logujesz się ze zgodnego urządzenia i lokalizacji sieciowej.
• Jeśli dzierżawca stosuje zasady dostępu warunkowego oparte na lokalizacji, administrator Microsoft Entra ID może potrzebować dodać zdalne adresy IP serwera MCP do listy dozwolonych: 20.125.155.22 i 40.74.28.81.
• Skontaktuj się z administratorem Microsoft Entra ID, aby uzyskać szczegółowe wymagania dotyczące zasad.

Dostęp gościa (B2B) nie działa

Symptom: Użytkownik-gość w dzierżawie Microsoft Entra nie może uzyskać dostępu do zdalnego serwera MCP.

Rozwiązanie:

Aby dostęp gościa działał, użytkownik musi mieć następujące uprawnienia:

1. Dodano jako użytkownika-gościa do dzierżawy Microsoft Entra.
2. Dodano do organizacji Azure DevOps z odpowiednimi uprawnieniami.
3. Udzielono dostępu do określonych potrzebnych projektów i zasobów.
4. Przy użyciu adresu URL specyficznego dla organizacji (https://mcp.dev.azure.com/{organization}). Użytkownicy-goście nie mogą używać głównego adresu URL (https://mcp.dev.azure.com/) — muszą uwzględnić nazwę organizacji w adresie URL.

Jeśli brakuje któregokolwiek z tych kroków, dostęp zakończy się niepowodzeniem. Traktuj ten problem tak samo jak standardowy problem z dostępem gościa Azure DevOps.

Kody błędu AADSTS

Objawem: Zobaczysz kod błędu rozpoczynający się od AADSTS (na przykład AADSTS50076, AADSTS700016).

Rozwiązanie:

AADSTS błędy to błędy uwierzytelniania Microsoft Entra ID, a nie problemy specyficzne dla umowy MCP. Typowe kody:

Aby uzyskać pełną listę kodów błędów, zobacz Microsoft Entra kody błędów uwierzytelniania i autoryzacji.

Problemy z Entra

Nie można odnaleźć aplikacji Azure DevOps MCP dla przedsiębiorstw w dzierżawie

Nie można odnaleźć aplikacji Azure DevOps MCP dla przedsiębiorstw w aplikacji Microsoft Entra ID>Enterprise, a zdalne uwierzytelnianie serwera MCP kończy się niepowodzeniem.

Rozwiązanie:

Poniższa procedura tworzy brakujący podmiot usługi dla Azure DevOps MCP w Twojej dzierżawie.

• Kto musi to uruchomić: użytkownik z uprawnieniami administratora aplikacji, administratora aplikacji w chmurze lub administratora globalnego w dzierżawie.
• Wymaganie wstępne: Zainstaluj Azure CLI.
• Identyfikator aplikacji: 2a72489c-aab2-4b65-b93a-a91edccf33b8.

Wykonuj każdy krok po kolei i zachowaj dane wyjściowe polecenia.

1. Krok 0 — Zaloguj się do dzierżawcy (zastąp <yourTenantId>):

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

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

   Upewnij się, że wartość dzierżawy jest zgodna z identyfikatorem dzierżawy.

2. Krok 1. Potwierdzenie, że aplikacja jest obecnie brakująca:

   az rest --method get --url "https://graph.microsoft.com/v1.0/servicePrincipals(appId='2a72489c-aab2-4b65-b93a-a91edccf33b8')"
   

   Oczekiwany wynik: 404 z Request_ResourceNotFound. Ten wynik potwierdza problem.

3. Krok 2 — Utwórz aplikację w dzierżawie:

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

4. Krok 3. Sprawdź, czy aplikacja istnieje teraz:

   az rest --method get --url "https://graph.microsoft.com/v1.0/servicePrincipals(appId='2a72489c-aab2-4b65-b93a-a91edccf33b8')"
   

   Oczekiwany wynik: 200 odpowiedź zawierająca "displayName": "Azure DevOps MCP" i "accountEnabled": true.

5. Krok 4. Potwierdzenie w portalu:

   Przejdź do portal.azure.com>Microsoft Entra ID>Aplikacje dla przedsiębiorstw, ustaw pozycję Typ aplikacji na Wszystkie aplikacje i wyszukaj Azure DevOps MCP lub 2a72489c-aab2-4b65-b93a-a91edccf33b8.

Aplikacja powinna być teraz wyświetlana i możesz zarządzać jej uprawnieniami.

Problemy z konfiguracją serwera

Nieprawidłowa mcp.json konfiguracja

Objaw: Zdalny serwer MCP nawiązuje połączenie, ale narzędzia się nie ładują lub występuje nieoczekiwane działanie.

Rozwiązanie:

Sprawdź, czy używasz mcp.json poprawnego formatu dla serwera zdalnego:

• Serwer zdalny używa "type": "http" i "url".
• Serwer lokalny używa systemów "type": "stdio", "command"i "args".

Nie mieszaj formatów konfiguracji zdalnych i lokalnych. Nie uruchamiaj obu serwerów jednocześnie — wybierz jeden:

• Serwer zdalny — zalecane w przypadku obsługiwanych środowisk, w tym Visual Studio Code, Visual Studio, Microsoft Foundry, Microsoft Copilot Studio i GitHub Copilot. Nie jest wymagana instalacja lokalna.
• Lokalny serwer — służy do obsługi klientów innych niż Microsoft (Claude Desktop, Claude Code, Cursor, Codex), które nie obsługują uwierzytelniania Microsoft Entra.

Zestaw narzędzi lub filtrowanie narzędzi nie działa

Objaw: Konfigurujesz nagłówki X-MCP-Toolsets lub X-MCP-Tools, ale lista narzędzi nie jest zgodna z oczekiwaniami.

Rozwiązanie:

• Nie łącz X-MCP-Toolsets i X-MCP-Tools nagłówków — wzajemnie się wykluczają.
• Sprawdź, czy nazwy zestawów narzędzi są poprawne: repos, , wit, wikipipelines, work, . testplan
• W przypadku korzystania z programu X-MCP-Toolsokreśl dokładne nazwy narzędzi rozdzielone przecinkami.
• Sprawdź, czy w nazwach nagłówków nie ma literówek — w nazwach nagłówków rozróżniana jest wielkość liter.

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

Aby uzyskać pełną listę dostępnych zestawów narzędzi i narzędzi, zobacz Dostępne narzędzia.

Tryb tylko do odczytu nie ogranicza zapisów

Objaw: Ustawiono X-MCP-Readonly, ale operacje zapisu są nadal dostępne.

Rozwiązanie:

Sprawdź, czy wartość nagłówka to ciąg "true":

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

Błędy rozwiązywania narzędzi

Narzędzia nie są wyświetlane w asystencie sztucznej inteligencji

Symptom: Po nawiązaniu połączenia zdalnego serwera MCP żadne narzędzia Azure DevOps nie są wyświetlane w asystencie sztucznej inteligencji.

Rozwiązanie:

1. Upewnij się, że stan serwera jest wyświetlany jako połączony w środowisku IDE.
   • W programie VS Code sprawdź stan serwera MCP w panelu Dane wyjściowe (View>Output> wybierz GitHub Copilot lub MCP z listy rozwijanej).
2. Załaduj ponownie okno programu VS Code (Ctrl+Shift+P>Developer: Okno ponownego ładowania).
3. Sprawdź, czy jesteś w trybie agent w GitHub Copilot — narzędzia MCP są wyświetlane tylko w trybie agenta, a nie w trybie czatu.
4. Sprawdź, czy nie przekraczasz limitu 128 narzędzi. Jeśli skonfigurowano wiele serwerów MCP, łączna liczba narzędzi może przekroczyć ten limit.

Brak wymaganych błędów parametrów

Objaw: Wywołania narzędzi kończą się błędem „brak wymaganego parametru”, zazwyczaj dotyczącym nazwy projektu.

Rozwiązanie:

Ten błąd jest najczęściej zgłaszany błąd i jest oczekiwanym zachowaniem. Wiele narzędzi wymaga nazwy projektu lub innego kontekstu:

• Uwzględnij nazwę projektu w monicie: „Wyświetl elementy robocze w projekcie Contoso.”
• Jeśli pominąłeś organizację w adresie URL, uwzględnij ją również w monicie.
• Niektóre narzędzia wymagają określonych parametrów. Zapoznaj się z dokumentacją Dostępnych narzędzi , aby uzyskać wymagane parametry.

Wywołanie narzędzia kończy się niepowodzeniem z powodu błędu serwera

Objaw: Wywołanie narzędzia zwraca błąd serwera mimo prawidłowego wywołania.

Rozwiązanie:

• Sprawdź, czy zasób, o który wysyłasz zapytanie, istnieje (na przykład czy identyfikator elementu roboczego, nazwa repozytorium lub identyfikator potoku są poprawne).
• Upewnij się, że masz uprawnienia dostępu do zasobu.
• Jeśli błąd będzie się powtarzać, utwórz problem przy użyciu szablonu problemu z zdalnym serwerem MCP.

Problemy z integracją z Copilot

Asystent sztucznej inteligencji nie korzysta z narzędzi MCP

Symptom: GitHub Copilot odpowiada na pytanie, ale nie używa narzędzi Azure DevOps MCP do pobierania danych.

Rozwiązanie:

1. Upewnij się, że używasz trybu agent w GitHub Copilot. Narzędzia MCP nie są dostępne w standardowym trybie czatu.
2. Jasno określ w poleceniu, jakich danych usługi Azure DevOps potrzebujesz. Na przykład zamiast „Jaki jest status mojego sprintu?” spróbuj: „Użyj Azure DevOps, aby uzyskać bieżące elementy robocze mojego sprintu.”
3. Sprawdź, czy serwer MCP jest wyświetlany jako połączony z zielonym wskaźnikiem stanu.

Zwracane nieaktualne lub buforowane dane

Symptom: Asystent sztucznej inteligencji zwraca nieaktualne dane Azure DevOps.

Rozwiązanie:

Dodaj „Nie używaj wcześniej pobranych danych” do promptu, aby wymusić nowe zapytanie. Asystenci AI mogą buforować wyniki narzędzia w trakcie sesji konwersacji.

Agent ulega awarii przed wywołaniem narzędzia

Objaw: Asystent AI ulega awarii lub zgłasza błąd przed wywołaniem jakiegokolwiek narzędzia MCP.

Rozwiązanie:

Ten problem znajduje się poza granicą Azure DevOps MCP. Błąd występuje w warstwie aranżacji asystenta sztucznej inteligencji:

• W przypadku problemów z GitHub Copilot zobacz dokumentację GitHub Copilot.
• Uruchom ponownie asystenta sztucznej inteligencji i spróbuj ponownie.
• Jeśli problem będzie się powtarzać, zgłoś go do dostawcy asystenta sztucznej inteligencji.

Nieobsługiwane błędy klienta

Klienci niebędący Microsoft nie mogą się uwierzytelniać

Objaw: Klienci tacy jak Claude Desktop, Claude Code, Cursor lub Codex nie mogą ukończyć uzgodnienia OAuth ze zdalnym serwerem MCP.

Rozwiązanie:

Klienci niebędący Microsoft nie mogą uwierzytelniać się za pomocą zdalnego serwera MCP, ponieważ Microsoft Entra ID nie obsługuje obecnie dynamicznej rejestracji klienta, czego wymagają ci klienci.

Obecnie obsługiwani klienci:

• Visual Studio Code
• Visual Studio (2022 i nowsze)
• Microsoft Foundry
• Microsoft Copilot Studio
• GitHub Copilot
• interfejs wiersza polecenia GitHub Copilot
• Aplikacja GitHub Copilot

W przypadku klientów spoza firmy Microsoft należy zamiast tego użyć lokalnego serwera Azure DevOps MCP z uwierzytelnianiem za pomocą PAT lub interfejsu wiersza polecenia Azure CLI. Nie uruchamiaj jednocześnie serwerów zdalnych i lokalnych — wybierz ten, który jest zgodny z klientem.

Porady diagnostyczne

Włączanie rejestrowania debugowania w programie VS Code

Aby przechwycić więcej szczegółów podczas rozwiązywania problemów:

1. Otwórz panel Dane wyjściowe w programie VS Code (Wyświetl>dane wyjściowe).
2. Wybierz GitHub Copilot lub MCP z listy rozwijanej kanału wyjściowego.
3. Poszukaj stanu połączenia, szczegółów przepływu uwierzytelniania i komunikatów o błędach.

Weryfikowanie połączenia

Po skonfigurowaniu przetestuj zdalny serwer MCP za pomocą prostego zapytania:

• "Wyświetl listę projektów w mojej organizacji Azure DevOps".
• Pokaż moje przypisane zadania.
• Które pull requesty wymagają mojej recenzji?

Jeśli te zapytania zwracają poprawne dane, serwer działa prawidłowo.

Często zadawane pytania

Czy mogę używać zdalnego serwera MCP z osobistym kontem Microsoft?

No. Zdalny serwer MCP wymaga połączenia organizacji Azure DevOps z Microsoft Entra ID. Osobiste konta Microsoft (MSA) nie są obsługiwane.

Czy należy używać zdalnego lub lokalnego serwera MCP?

Użyj serwera zdalnego, jeśli środowisko go obsługuje. Serwer zdalny jest zalecany, ponieważ nie wymaga instalacji lokalnej i Azure DevOps zarządza jego aktualizacjami. Użyj serwera lokalnego tylko wtedy, gdy używasz klienta, takiego jak Claude Desktop, Claude Code, Kursor lub Codex, który nie może uwierzytelnić się na serwerze zdalnym. Nie uruchamiaj jednocześnie obu serwerów.

Dlaczego widzę różne narzędzia z serwerem zdalnym a lokalnym?

Serwery zdalne i lokalne mogą znajdować się w różnych wersjach. Serwer zdalny jest aktualizowany niezależnie od lokalnego pakietu npm. Użyj nagłówka X-MCP-Insiders, aby uzyskać dostęp do najnowszych narzędzi zdalnych. W przypadku serwera lokalnego zaktualizuj pakiet npm do najnowszej wersji.

Czy serwer MCP działa z Azure DevOps Server (lokalnie)?

No. Ani zdalny, ani lokalny serwer MCP nie obsługuje Azure DevOps Server (lokalnie). Oba serwery wymagają usług Azure DevOps (w chmurze).

Jakie dane uzyskuje zdalny dostęp do serwera MCP?

Serwer zdalny uzyskuje dostęp do tych samych danych usługi Azure DevOps co interfejs API REST, w zakresie wynikającym z Twoich uprawnień. Nie uzyskuje dostępu do danych wykraczających poza zakres danych, do których tożsamość Microsoft Entra ma uprawnienia dostępu.

Jak zgłosić problem ze zdalnym serwerem MCP?

Utwórz zgłoszenie za pomocą szablonu zgłoszenia Remote MCP Server w repozytorium GitHub serwera Azure DevOps MCP.

Treści powiązane

• Konfigurowanie zdalnego serwera Azure DevOps MCP
• Omówienie serwera MCP usługi Azure DevOps
• Repozytorium GitHub serwera Usługi Azure DevOps MCP