Résoudre les problèmes liés au serveur MCP Azure DevOps distant

Azure DevOps Services

Cet article vous aide à diagnostiquer et résoudre les problèmes courants liés aux remote Azure DevOps MCP Server. Pour connaître les problèmes de serveur MCP local, consultez le guide de résolution des problèmes du serveur MCP local.

Échecs de connexion

Serveur introuvable ou erreurs d’URL

Symptôme: Votre assistant IA ne peut pas se connecter au serveur MCP distant, ou vous voyez des erreurs liées à l’URL.

Résolution :

1. Vérifiez le format d’URL du serveur dans votre mcp.json:

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

2. Vérifiez les points suivants :

   • Utiliser https://mcp.dev.azure.com/{organization} : remplacez {organization} par le nom de votre organisation réelle.
   • Utilisez uniquement le nom de l’organisation (par exemple, contoso), et non l’URL de Azure DevOps complète.
   • Le type doit être "http", pas "stdio".

3. Si vous omettez le nom de l’organisation à partir de l’URL (https://mcp.dev.azure.com/), vous devez fournir le nom de l’organisation comme contexte dans chaque appel d’outil.

Blocs de réseau ou de pare-feu

Symptôme: La connexion expire ou est refusée, mais l’URL est correcte.

Résolution :

• Vérifiez que votre réseau autorise le trafic HTTPS sortant vers mcp.dev.azure.com.
• Si vous êtes derrière un proxy d’entreprise ou un pare-feu, vérifiez que mcp.dev.azure.com n’est pas bloqué. Contactez votre administrateur du réseau pour ajouter ce point de terminaison à la liste d’autorisation.
• Les configurations VPN peuvent interférer avec la connectivité. Essayez de vous connecter sans VPN pour isoler le problème.

Aperçu de la disponibilité

Symptôme: Vous obtenez une erreur indiquant que le service n’est pas disponible.

Résolution :

Le serveur MCP distant est en préversion publique et est progressivement déployé. Si vous ne pouvez pas vous connecter :

• Vérifiez que votre organisation est connectée à Microsoft Entra ID.
• Revenez plus tard, à mesure que la version préliminaire continue de s’enrichir.
• Vérifiez auprès de l’administrateur de votre organisation qu’aucune stratégie ne bloque les fonctionnalités en préversion.

Erreurs d’authentification

Le serveur MCP distant utilise Microsoft Entra ID (OAuth) pour l’authentification. Les jetons d’accès personnels (PAT) ne sont pas pris en charge pour le serveur distant.

L’invite de connexion échoue ou n’apparaît pas

Symptôme: L’invite de connexion OAuth n’apparaît pas ou l’authentification échoue avant de pouvoir vous connecter.

Résolution :

1. Vérifiez que votre compte est connecté à Microsoft Entra ID. Le serveur MCP distant nécessite une identité adossée à Microsoft Entra.
2. Vérifiez que votre navigateur peut s’ouvrir pour le flux OAuth. Si vous utilisez VS Code dans un environnement distant ou sans interface graphique, la redirection OAuth risque de ne pas fonctionner correctement.
3. Effacer les informations d’identification mises en cache :
   • Dans VS Code, ouvrez la palette de commandes (Ctrl+Maj+P) et exécutez les comptes : déconnexion. Ensuite, réessayez la connexion.
   • Si le problème persiste, rechargez la fenêtre VS Code (Développeur : Recharger la fenêtre).

Échec d’autorisation après la connexion

Symptôme: Vous vous connectez correctement, mais obtenez une erreur d’autorisation lors de la tentative d’accès à votre organisation ou projet.

Résolution :

• Vérifiez que vous disposez du niveau access approprié dans l’organisation Azure DevOps.
• Vérifiez que vous êtes membre du projet auquel vous essayez d’accéder.
• Vérifiez que vos autorisations Azure DevOps incluent l'accès aux ressources que vous interrogez (par exemple, les éléments de travail, les dépôts ou les pipelines).

Les stratégies d’accès conditionnel bloquent l’accès

Symptôme : Une stratégie d’accès conditionnel Microsoft Entra bloque votre connexion.

Résolution :

Les stratégies d’accès conditionnel s’appliquent au serveur MCP distant de la même façon qu’elles s’appliquent à Azure DevOps. Si votre locataire applique des stratégies telles que des restrictions basées sur l’emplacement ou basées sur des appareils :

• Vérifiez que vous vous connectez à partir d’un appareil conforme et d’un emplacement réseau.
• Si votre locataire utilise des stratégies d’accès conditionnel basées sur l’emplacement, votre administrateur de Microsoft Entra ID devra peut-être ajouter les adresses IP du serveur MCP distant à la liste d’autorisation : 20.125.155.22 et 40.74.28.81.
• Contactez votre administrateur Microsoft Entra ID pour connaître les exigences de stratégie spécifiques.

Échec de l’accès invité (B2B)

Symptom : Un utilisateur invité dans le locataire Microsoft Entra ne peut pas accéder au serveur MCP distant.

Résolution :

Pour que l’accès invité fonctionne, l’utilisateur doit être :

1. Ajouté au locataire Microsoft Entra en tant qu’utilisateur invité.
2. Ajouté à l’organisation Azure DevOps avec les autorisations appropriées.
3. Accès aux projets et ressources spécifiques dont ils ont besoin.
4. Utilisation de l’URL spécifique à l’organisation (https://mcp.dev.azure.com/{organization}). Les utilisateurs invités ne peuvent pas utiliser l’URL racine (https://mcp.dev.azure.com/) : ils doivent inclure le nom de l’organisation dans l’URL.

Si l’une de ces étapes est manquante, l’accès échoue. Traitez ce problème de la même façon qu’un problème d’accès invité standard Azure DevOps.

AADSTS codes d'erreur

Symptôme: Vous voyez un code d’erreur commençant AADSTS par (par exemple, AADSTS50076, AADSTS700016).

Résolution :

Les erreurs AADSTS sont des erreurs d’authentification Microsoft Entra ID, pas des problèmes spécifiques à MCP. Les codes courants incluent :

Pour obtenir la liste complète des codes d’erreur, consultez Microsoft Entra codes d’erreur d’authentification et d’autorisation.

Problèmes de configuration du serveur

Configuration incorrecte mcp.json

Symptôme: Le serveur MCP distant se connecte, mais les outils ne se chargent pas, ou vous obtenez un comportement inattendu.

Résolution :

Vérifiez que vous mcp.json utilisez le format approprié pour le serveur distant :

• Le serveur distant utilise "type": "http" et "url".
• Le serveur local utilise "type": "stdio", "command"et "args".

Ne mélangez pas les formats de configuration distants et locaux. N’exécutez pas les deux serveurs en même temps : choisissez-en un :

• Serveur distant — À utiliser pour Visual Studio Code et Visual Studio. Aucune installation locale n’est requise.
• serveur Local : utilisez-le pour les clients non Microsoft (Claude Desktop, Claude Code, Cursor, Codex) qui ne prennent pas en charge l'authentification Microsoft Entra.

Ensemble d’outils ou filtrage des outils qui ne fonctionnent pas

Symptôme: Vous configurez X-MCP-Toolsets ou X-MCP-Tools des en-têtes, mais la liste des outils ne correspond pas aux attentes.

Résolution :

• Ne combinez pas les en-têtes X-MCP-Toolsets et X-MCP-Tools — ils sont mutuellement exclusifs.
• Vérifiez que les noms de l’ensemble d’outils sont corrects : repos, , witwiki, pipelines, work, testplan.
• Lorsque vous utilisez X-MCP-Tools, spécifiez des noms d’outils exacts séparés par des virgules.
• Vérifiez qu’il n’y a pas de fautes de frappe dans les noms des en-têtes : les en-têtes sont sensibles à la casse.

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

Pour obtenir la liste complète des ensembles d’outils et outils disponibles, consultez Outils disponibles.

Mode lecture seule ne limitant pas les écritures

Symptôme: Vous définissez X-MCP-Readonly , mais les opérations d’écriture sont toujours disponibles.

Résolution :

Vérifiez que la valeur d’en-tête est la chaîne "true":

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

Erreurs de résolution des outils

Les outils ne s’affichent pas dans l’Assistant IA

Symptôme : Après avoir connecté le serveur MCP distant, aucun outil Azure DevOps n’apparaît dans votre assistant IA.

Résolution :

1. Vérifiez que l’état du serveur s’affiche comme connecté dans votre IDE.
   • Dans VS Code, vérifiez l’état du serveur MCP dans le panneau Sortie (ViewOutput< /> sélectionnez GitHub Copilot ou MCP dans la liste déroulante).
2. Rechargez la fenêtre VS Code (Ctrl+Maj+P>Développeur : Recharger la fenêtre).
3. Vérifiez que vous êtes en mode agent dans GitHub Copilot : les outils MCP s'affichent uniquement en mode agent, et non en mode conversation.
4. Vérifiez que vous ne dépassez pas la limite de 128 outils. Si plusieurs serveurs MCP sont configurés, le nombre d’outils combinés peut dépasser cette limite.

Erreurs dues à l’absence de paramètres obligatoires

Symptôme: Les appels d’outils échouent avec des erreurs « paramètre requis manquants », généralement pour le nom du projet.

Résolution :

Cette erreur est l’erreur la plus couramment signalée et est le comportement attendu. De nombreux outils nécessitent un nom de projet ou un autre contexte :

• Incluez le nom du projet dans votre invite : « Répertorier les éléments de travail dans le projet Contoso ».
• Si vous avez omis l’organisation dans votre URL, incluez aussi l’organisation dans votre requête.
• Certains outils nécessitent des paramètres spécifiques. Consultez la documentation des outils disponibles pour connaître les paramètres requis.

Échec de l’appel d’outil avec une erreur de serveur

Symptôme: Un appel d’outil retourne une erreur de serveur après avoir été appelé correctement.

Résolution :

• Vérifiez que la ressource que vous interrogez existe (par exemple, l’ID de l’élément de travail, le nom du référentiel ou l’ID de pipeline est correct).
• Vérifiez que vous disposez des autorisations nécessaires pour accéder à la ressource.
• Si l’erreur persiste, créez un problème à l’aide du modèle de problème du serveur MCP distant.

problèmes d’intégration de Copilot

L’assistant IA n’utilise pas les outils MCP

Symptom : GitHub Copilot répond à votre question, mais n'utilise pas Azure DevOps outils MCP pour récupérer des données.

Résolution :

1. Vérifiez que vous utilisez le mode agent dans GitHub Copilot. Les outils MCP ne sont pas disponibles en mode de conversation standard.
2. Soyez explicite dans votre requête concernant les données Azure DevOps dont vous avez besoin. Par exemple, au lieu de « Quel est mon état de sprint ? », essayez « Utiliser Azure DevOps pour obtenir mes éléments de travail sprint actuels ».
3. Vérifiez que le serveur MCP s’affiche comme connecté à un indicateur d’état vert.

Données obsolètes ou mises en cache retournées

Symptom : L’assistant IA retourne des données obsolètes Azure DevOps.

Résolution :

Ajoutez « N’utilisez pas les données extraites précédemment » à votre invite pour forcer une nouvelle requête. Les assistants IA peuvent mettre en cache les résultats de l’outil au sein d’une session de conversation.

L’agent échoue avant l’appel de l’outil

Symptôme: L’Assistant IA échoue ou génère des erreurs avant d’appeler n’importe quel outil MCP.

Résolution :

Ce problème se trouve en dehors de la limite Azure DevOps MCP. L’échec se produit dans la couche d’orchestration de l’assistant IA :

• Pour GitHub Copilot problèmes, consultez la documentation GitHub Copilot.
• Redémarrez l’Assistant IA et réessayez.
• Si le problème persiste, signalez-le à votre fournisseur d’assistant IA.

Erreurs client non prises en charge

Les clients non Microsoft ne peuvent pas s'authentifier

Symptôme: Les clients tels que Claude Desktop, Claude Code, Cursor ou Codex ne peuvent pas terminer l’établissement d’une liaison OAuth avec le serveur MCP distant.

Résolution :

Les clients non Microsoft ne peuvent pas s'authentifier auprès du serveur MCP distant, car Microsoft Entra ID ne prend actuellement pas en charge l'inscription dynamique des clients, dont ces clients ont besoin.

Clients actuellement pris en charge :

• Visual Studio Code
• Visual Studio (2022 et versions ultérieures)

Pour les clients non Microsoft, utilisez plutôt le serveur MCP local Azure DevOps MCP avec l’authentification PAT ou Azure CLI. N’exécutez pas les serveurs distants et locaux en même temps : choisissez celui qui correspond à votre client.

Conseils de diagnostic

Activer la journalisation du débogage dans VS Code

Pour obtenir plus de détails lors du dépannage :

1. Ouvrez le panneau Sortie dans VS Code (Afficher>la sortie).
2. Sélectionnez GitHub Copilot ou MCP dans la liste déroulante du canal de sortie.
3. Recherchez l’état de la connexion, les détails du flux d’authentification et les messages d’erreur.

Vérifier la connexion

Après l’installation, testez le serveur MCP distant avec une requête simple :

• « Répertorier les projets dans mon organisation Azure DevOps ».
• « Afficher mes tâches assignées. »
• « Quelles demandes de tirage ont besoin de mon examen ? »

Si ces requêtes retournent des données correctes, le serveur fonctionne correctement.

Questions fréquentes (FAQ)

Puis-je utiliser le serveur MCP distant avec un compte Microsoft personnel ?

Non. Le serveur MCP distant nécessite que votre organisation Azure DevOps soit connectée à Microsoft Entra ID. Les comptes d'Microsoft personnels (MSA) ne sont pas pris en charge.

Dois-je utiliser le serveur MCP distant ou local ?

Utilisez le serveur distant si votre client le prend en charge (Visual Studio Code ou Visual Studio). Utilisez le serveur local uniquement si vous utilisez un client non-Microsoft comme Claude Desktop, Claude Code, Cursor ou Codex. N’exécutez pas les deux serveurs en même temps.

Pourquoi puis-je voir différents outils avec le serveur distant et le serveur local ?

Les serveurs distants et locaux peuvent se trouver à différentes versions. Le serveur distant est mis à jour indépendamment du package npm local. Utilisez l’en-tête X-MCP-Insiders pour accéder aux outils distants les plus récents. Pour le serveur local, mettez à jour le package npm vers la dernière version.

Le serveur MCP fonctionne-t-il avec Azure DevOps Server (local) ?

Non. Ni le serveur MCP distant ni le serveur MCP local ne prend en charge Azure DevOps Server (local). Les deux serveurs nécessitent Azure DevOps Services (cloud).

À quelles données le serveur MCP distant a-t-il accès ?

Le serveur distant accède aux mêmes données Azure DevOps que l’API REST, étendue à vos autorisations. Il n'accède pas aux données au-delà de ce que votre identité Microsoft Entra est autorisée à voir.

Comment signaler un problème avec le serveur MCP distant ?

Créez un problème à l’aide du modèle de problème Remote MCP Server dans le référentiel GitHub du serveur MCP Azure DevOps.

Contenu connexe

• Configurer le serveur MCP Azure DevOps distant (préversion)
• Vue d’ensemble du serveur MCP Azure DevOps
• Référentiel GitHub du serveur MCP Azure DevOps