Problemen met de externe Azure DevOps MCP-server oplossen

Azure DevOps Services

Dit artikel helpt u bij het vaststellen en oplossen van veelvoorkomende problemen met de remote Azure DevOps MCP Server. Zie de handleiding voor probleemoplossing voor de lokale MCP-server.

Verbindingsfouten

Server niet gevonden of URL-fouten

Symptoom: Uw AI-assistent kan geen verbinding maken met de externe MCP-server of u ziet URL-gerelateerde fouten.

Resolutie:

1. Controleer de URL-indeling van de server in uw mcp.json:

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

2. Bevestig het volgende:

   • Gebruik https://mcp.dev.azure.com/{organization} : vervang deze door {organization} de naam van uw werkelijke organisatie.
   • Gebruik alleen de naam van de organisatie (bijvoorbeeld contoso), niet de volledige Azure DevOps URL.
   • Het type moet zijn "http", niet "stdio".

3. Als u de naam van de organisatie weglaat uit de URL (https://mcp.dev.azure.com/), moet u de naam van de organisatie opgeven als context in elke aanroep van het hulpprogramma.

Netwerk- of firewallblokkeringen

Symptoom: Er treedt een time-out op voor de verbinding of wordt geweigerd, maar de URL is juist.

Resolutie:

• Zorg ervoor dat uw netwerk uitgaand HTTPS-verkeer toestaat.mcp.dev.azure.com
• Als u achter een bedrijfsproxy of firewall zit, controleer dan of mcp.dev.azure.com niet wordt geblokkeerd. Neem contact op met uw netwerkbeheerder om dit eindpunt op de toelatingslijst te laten plaatsen.
• VPN-configuraties kunnen de connectiviteit verstoren. Probeer verbinding te maken zonder VPN om het probleem te isoleren.

Beschikbaarheid van de preview

Symptoom: Er wordt een foutbericht weergegeven waarin wordt aangegeven dat de service niet beschikbaar is.

Resolutie:

De externe MCP-server is in de openbare previewfase en wordt geleidelijk uitgerold. Als u geen verbinding kunt maken:

• Controleer of uw organisatie is verbonden met Microsoft Entra ID.
• Kom later terug, terwijl de preview verder wordt uitgebreid.
• Bevestig bij de beheerder van uw organisatie dat preview-functies niet worden geblokkeerd door beleidsregels.

Authenticatiefouten

De externe MCP-server gebruikt Microsoft Entra ID (OAuth) voor verificatie. Persoonlijke toegangstokens (PAT's) worden niet ondersteund voor de externe server.

Aanmeldingsprompt mislukt of wordt niet weergegeven

Symptoom: De OAuth-aanmeldingsprompt wordt niet weergegeven of de verificatie mislukt voordat u zich kunt aanmelden.

Resolutie:

1. Controleer of uw account is verbonden met Microsoft Entra ID. Voor de externe MCP-server is een door Microsoft Entra ondersteunde identiteit vereist.
2. Controleer of uw browser kan worden geopend voor de OAuth-stroom. Als u VS Code gebruikt in een externe of headless omgeving, werkt de OAuth-omleiding mogelijk niet correct.
3. Cachereferenties wissen:
   • Open in VS Code het opdrachtenpalet (Ctrl+Shift+P) en voer accounts uit: Afmelden. Probeer de verbinding vervolgens opnieuw.
   • Als het probleem zich blijft voordoen, laadt u het VS Code-venster opnieuw (Developer: Reload Window).

Autorisatiefout na aanmelding

Symptoom: U meldt zich aan, maar krijgt een autorisatiefout wanneer u toegang probeert te krijgen tot uw organisatie of project.

Resolutie:

• Controleer of u het juiste access-niveau in de Azure DevOps organisatie hebt.
• Controleer of u lid bent van het project dat u probeert te openen.
• Controleer of uw Azure DevOps machtigingen toegang hebben tot de resources waarop u query's uitvoert (bijvoorbeeld werkitems, opslagplaatsen of pijplijnen).

Beleid voor voorwaardelijke toegang blokkeert de toegang

Symptom: Een Microsoft Entra Voorwaardelijke toegang-beleid blokkeert uw aanmelding.

Resolutie:

Beleid voor voorwaardelijke toegang is van toepassing op de externe MCP-server op dezelfde manier als op Azure DevOps. Als uw tenant beleidsregels afdwingt, zoals beperkingen op basis van locatie of apparaat:

• Zorg ervoor dat u zich aanmeldt vanaf een compatibel apparaat en netwerklocatie.
• Als uw tenant gebruikmaakt van beleid voor voorwaardelijke toegang op basis van locatie, moet uw Microsoft Entra ID beheerder mogelijk de externe IP-adressen van de MCP-server toestaan: 20.125.155.22 en 40.74.28.81.
• Neem contact op met uw Microsoft Entra ID-beheerder voor specifieke beleidsvereisten.

Gasttoegang (B2B) mislukt

Symptom: Een gastgebruiker in de Microsoft Entra-tenant heeft geen toegang tot de externe MCP-server.

Resolutie:

Als gasttoegang werkt, moet de gebruiker het volgende zijn:

1. Toegevoegd aan de Microsoft Entra-tenant als gastgebruiker.
2. Toegevoegd aan de Azure DevOps organisatie met de juiste machtigingen.
3. Toegang verleend tot de specifieke projecten en resources die ze nodig hebben.
4. Gebruik de organisatiespecifieke URL (https://mcp.dev.azure.com/{organization}). Gastgebruikers kunnen de hoofd-URL (https://mcp.dev.azure.com/) niet gebruiken. Ze moeten de naam van de organisatie opnemen in de URL.

Als een van deze stappen ontbreekt, mislukt de toegang. Behandel dit probleem hetzelfde als een standaardprobleem met Azure DevOps gasttoegang.

AADSTS foutcodes

Symptoom: U ziet een foutcode die begint met AADSTS (bijvoorbeeld AADSTS50076, AADSTS700016).

Resolutie:

AADSTS fouten zijn Microsoft Entra ID verificatiefouten, niet MCP-specifieke problemen. Veelvoorkomende codes zijn onder andere:

Zie Microsoft Entra foutcodes voor verificatie en autorisatie voor een volledige lijst met foutcodes.

Problemen met serverconfiguratie

Onjuiste mcp.json configuratie

Symptoom: De externe MCP-server maakt verbinding, maar hulpprogramma's worden niet geladen of u krijgt onverwacht gedrag.

Resolutie:

Controleer of u mcp.json de juiste indeling gebruikt voor de externe server:

• Externe server gebruikt "type": "http" en "url".
• Lokale server maakt gebruik van "type": "stdio", "command"en "args".

Meng geen indelingen voor externe en lokale configuraties. Voer beide servers niet tegelijkertijd uit: kies er een:

• Remote-server — Gebruiken voor Visual Studio Code en Visual Studio. Er is geen lokale installatie vereist.
• Local-server — Gebruiken voor niet-Microsoft clients (Claude Desktop, Claude Code, Cursor, Codex) die geen ondersteuning bieden voor Microsoft Entra verificatie.

Toolset of filteren op hulpprogramma's werkt niet

Symptoom: U configureert X-MCP-Toolsets of X-MCP-Tools headers, maar de lijst met hulpprogramma's komt niet overeen met de verwachtingen.

Resolutie:

• Combineer X-MCP-Toolsets- en X-MCP-Tools-koppen niet — deze sluiten elkaar uit.
• Controleer of de namen van de toolset juist zijn: repos, wit, wiki, pipelines, work, . testplan
• Geef bij het gebruik X-MCP-Toolsexacte namen van hulpprogramma's op, gescheiden door komma's.
• Controleer op typfouten in kopnamen: headers zijn hoofdlettergevoelig.

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

Zie Beschikbare hulpprogramma's voor de volledige lijst van beschikbare hulpprogrammasets en hulpprogramma's.

Alleen-lezenmodus beperkt schrijven niet

Symptoom: U stelt X-MCP-Readonly in, maar schrijfbewerkingen zijn nog steeds beschikbaar.

Resolutie:

Controleer of de headerwaarde de tekenreeks "true"is:

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

Fouten bij het oplossen van hulpprogramma's

Hulpmiddelen worden niet weergegeven in de AI-assistent

Symptom: Nadat u de externe MCP-server hebt verbonden, worden er geen Azure DevOps-hulpprogramma's weergegeven in uw AI-assistent.

Resolutie:

1. Controleer of de serverstatus wordt weergegeven als verbonden in uw IDE.
   • In VS Code, controleer de MCP-serverstatus in het deelvenster Uitvoer (View>Output> selecteer GitHub Copilot of MCP in de vervolgkeuzelijst).
2. Laad het VS Code-venster opnieuw (Ctrl+Shift+P>Developer: Venster opnieuw laden).
3. Controleer of u zich in agentmodus in GitHub Copilot bevindt. MCP-hulpprogramma's worden alleen weergegeven in de agentmodus, niet in de chatmodus.
4. Controleer of u de limiet van 128 hulpprogramma's niet overschrijdt. Als u meerdere MCP-servers hebt geconfigureerd, kan het gecombineerde aantal hulpprogramma's deze limiet overschrijden.

Fouten vanwege ontbrekende vereiste parameters

Symptoom: Aanroepen van hulpprogramma's mislukken met 'ontbrekende vereiste parameter'-fouten, meestal voor de projectnaam.

Resolutie:

Deze fout is de meest gerapporteerde fout en is verwacht gedrag. Voor veel hulpprogramma's is een projectnaam of andere context vereist:

• Neem de projectnaam op in uw prompt: 'Werkitems weergeven in het Contoso-project '.
• Als u de organisatie uit uw URL weglaat, neemt u de organisatie ook op in uw prompt.
• Voor sommige hulpprogramma's zijn specifieke parameters vereist. Raadpleeg de documentatie over beschikbare hulpprogramma's voor vereiste parameters.

Aanroepen van hulpprogramma mislukt met serverfout

Symptoom: Een aanroep van een hulpprogramma retourneert een serverfout nadat deze correct is aangeroepen.

Resolutie:

• Controleer of de resource die u wilt opvragen bestaat (bijvoorbeeld de id van het werkitem, de naam van de opslagplaats of de pijplijn-id is juist).
• Bevestig dat u gemachtigd bent om toegang te krijgen tot de resource.
• Als de fout zich blijft voordoen, maakt u een probleem met behulp van de sjabloon voor het probleem met de externe MCP-server.

Copilot integratieproblemen

AI-assistent maakt geen gebruik van MCP-hulpprogramma's

Symptom: GitHub Copilot reageert op uw vraag, maar gebruikt geen Azure DevOps MCP-hulpprogramma's om gegevens op te halen.

Resolutie:

1. Zorg ervoor dat u de modus agent gebruikt in GitHub Copilot. MCP-hulpprogramma's zijn niet beschikbaar in de standaardchatmodus.
2. Wees expliciet in uw prompt over welke Azure DevOps gegevens u nodig hebt. Probeer in plaats van 'Wat is mijn sprintstatus?' bijvoorbeeld 'Gebruik Azure DevOps om mijn huidige sprintwerkitems op te halen'.
3. Controleer of de MCP-server wordt weergegeven als verbonden met een groene statusindicator.

Verouderde of uit de cache afkomstige gegevens geretourneerd

Symptom: De AI-assistent retourneert verouderde Azure DevOps gegevens.

Resolutie:

Voeg 'Niet eerder opgehaalde gegevens gebruiken' toe aan uw prompt om een nieuwe query af te dwingen. AI-assistenten kunnen de resultaten van hulpprogramma's in de cache opslaan in een gesprekssessie.

Agent faalt vóór het aanroepen van het hulpprogramma

Symptoom: De AI-assistent mislukt of geeft een fout voordat deze een MCP-tool aanroept.

Resolutie:

Dit probleem valt buiten de Azure DevOps MCP-grens. De fout treedt op in de orchestratielaag van de AI-assistent:

• Zie GitHub Copilot documentatie voor GitHub Copilot problemen.
• Start de AI-assistent opnieuw en probeer het opnieuw.
• Als het probleem zich blijft voordoen, meldt u dit aan uw AI-assistentprovider.

Fouten bij niet-ondersteunde clients

Niet-Microsoft-clients kunnen niet verifiëren

Symptoom: Clients zoals Claude Desktop, Claude Code, Cursor of Codex kunnen de OAuth-handshake niet voltooien met de externe MCP-server.

Resolutie:

Niet-Microsoft-clients kunnen niet worden geverifieerd met de externe MCP-server omdat Microsoft Entra ID momenteel geen ondersteuning biedt voor dynamische clientregistratie, die deze clients nodig hebben.

Momenteel ondersteunde clients:

• Visual Studio code
• Visual Studio (2022 en hoger)

Gebruik voor niet-Microsoft clients de local Azure DevOps MCP Server met PAT- of Azure CLI-verificatie. Voer niet tegelijkertijd de externe en lokale servers uit. Kies de server die overeenkomt met uw client.

Diagnostische tips

Logboekregistratie voor foutopsporing inSCHAKELEN in VS Code

Ga als volgt te werk om meer details vast te leggen wanneer u problemen wilt oplossen:

1. Open het deelvenster Uitvoer in VS Code (Uitvoer weergeven>).
2. Selecteer GitHub Copilot of MCP in de vervolgkeuzelijst van het uitvoerkanaal.
3. Zoek naar verbindingsstatus, details van verificatiestroom en foutberichten.

De verbinding verifiëren

Test na de installatie de externe MCP-server met een eenvoudige query:

• 'Geef de projecten in mijn Azure DevOps-organisatie weer.'
• 'Mijn toegewezen werkitems weergeven'.
• "Welke pull-aanvragen hebben mijn beoordeling nodig?"

Als deze query's de juiste gegevens retourneren, werkt de server goed.

Veelgestelde vragen

Kan ik de externe MCP-server gebruiken met een persoonlijke Microsoft-account?

Nee. De externe MCP-server vereist dat uw Azure DevOps organisatie is verbonden met Microsoft Entra ID. Persoonlijke Microsoft-accounts (MSA) worden niet ondersteund.

Moet ik de externe of lokale MCP-server gebruiken?

Gebruik de externe server als uw client deze ondersteunt (Visual Studio Code of Visual Studio). Gebruik de lokale server alleen als u een niet-Microsoft-client gebruikt, zoals Claude Desktop, Claude Code, Cursor of Codex. Voer beide servers niet tegelijkertijd uit.

Waarom zie ik verschillende hulpprogramma's met de externe versus lokale server?

De externe en lokale servers kunnen zich in verschillende versies bevinden. De externe server wordt onafhankelijk van het lokale npm-pakket bijgewerkt. Gebruik de X-MCP-Insiders header voor toegang tot de nieuwste externe hulpprogramma's. Werk voor de lokale server het npm-pakket bij naar de nieuwste versie.

Werkt de MCP-server met Azure DevOps Server (on-premises)?

Nee. Noch de externe noch de lokale MCP-server ondersteunt Azure DevOps Server (on-premises). Voor beide servers is Azure DevOps Services (cloud) vereist.

Welke gegevens heeft de externe MCP-server toegang?

De externe server heeft toegang tot dezelfde Azure DevOps gegevens als de REST API, die is afgestemd op uw machtigingen. Het heeft geen toegang tot gegevens buiten wat uw Microsoft Entra identiteit mag zien.

Hoe kan ik een probleem melden met de externe MCP-server?

Maak een probleem met behulp van de probleemsjabloon Remote MCP Server in de Azure DevOps MCP Server GitHub opslagplaats.

Verwante inhoud

• De externe MCP-server voor Azure DevOps instellen (preview)
• Overzicht van Azure DevOps MCP Server
• GitHub-opslagplaats voor Azure DevOps MCP Server