Résoudre les problèmes liés aux applications MCP dans Microsoft 365 Copilot

Ce guide fournit des conseils de dépannage pour les problèmes courants que vous pouvez rencontrer lors du développement d’une application MCP (Model Context Protocol) à intégrer à un agent déclaratif dans Microsoft 365 Copilot.

Activer le mode développeur

L’activation du mode développeur affiche les journaux et les erreurs dans les réponses de l’agent. Ces informations sont essentielles pour le débogage. Pour activer le mode développeur, tapez la commande suivante dans Microsoft Copilot.

-developer on

Les outils MCP disponibles pour votre agent s’affichent dans la section Actions de la carte d’informations de débogage. Pour plus d’informations sur la carte d’informations de débogage, consultez Utiliser le mode développeur dans Microsoft 365 Copilot pour tester et déboguer les agents.

Problèmes de détection et d’entrée

Aucun outil répertorié

Si la section Actions de la carte d’informations de débogage ne répertorie aucun outil MCP, case activée les éléments suivants :

  • Vérifiez que votre serveur MCP est en cours d’exécution et que vous vous connectez au point de terminaison MCP correct dans votre manifeste de plug-in.
  • Vérifiez que l’authentification réussit. De nombreux serveurs MCP ne renvoient aucun outil tant que l’utilisateur ne se connecte pas. Par conséquent, une connexion qui a échoué ou qui est ignorée peut entraîner une liste d’outils vide.

Découverte d’outils dynamique

Si votre agent utilise la découverte d’outils dynamique (valeur par défaut), les outils sont résolus à partir du serveur au moment de l’exécution. Vérifiez que :

  • Le RemoteMCPServer runtime est défini run_for_functions sur ["*"] et le tableau de niveau functions supérieur est vide.
  • La méthode du serveur renvoie des tools/list outils. Vous pouvez inspecter la réponse à l’aide d’un outil tel que l’inspecteur MCP.
  • Un outil récemment découvert ou modifié n’est pas refusé par la validation de l’exécution. Vérifiez les informations de débogage pour vérifier la présence d’erreurs de validation.
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp"
    },
    "run_for_functions": [
      "*"
    ]
  }
]

Outils épinglés

Si vous avez épinglé un ensemble fixe d’outils, vérifiez que le runtime du serveur MCP spécifié dans la runtimes propriété dans votre manifeste de plug-in :

  • Inclut les outils attendus dans la propriété de niveau functions supérieur.
  • Fait référence aux outils de la mcp_tool_description propriété par :
    • Référencement d’un fichier JSON qui contient les descriptions des outils dans la file propriété OU
    • Listing des descriptions des outils en ligne dans la tools propriété
  • Inclut les noms des outils dans la run_for_functions propriété.
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp",
      "mcp_tool_description": {
        "file": "mcp-tools.json"
      }
    },
    "run_for_functions": [
      "get_widget",
      "create_widget"
    ]
  }
]

Les outils ne se déclenchent pas à partir de la conversation Copilot

  • Revoyez les descriptions de vos outils et paramètres pour vous assurer qu’elles fournissent suffisamment de contexte. Envisagez de les réécrire en utilisant « Utiliser cette fonction/paramètre quand... » phrasé.
  • Ne dépassez pas les descriptions de 1 024 caractères. Le texte au-delà de 1 024 caractères est ignoré.
  • Assurez-vous que la visibilité de l’outil est correctement définie.
    • Pour les applications MCP, _meta.ui.visibility inclut .model
    • Pour les applications du SDK OpenAI, meta["openai/visibility"] est définie sur public.

Le mauvais outil est sélectionné

  • Évitez les outils dont les noms sont similaires ou dont les descriptions se chevauchent.
  • Ajoutez des différenciateurs clairs dans les descriptions expliquant quand chaque outil doit être utilisé.

Problèmes de widget

Le widget ne s’affiche pas

Si l’outil MCP correct est appelé, mais que votre widget d’interface utilisateur ne s’affiche pas dans la réponse, votre serveur MCP renvoie probablement uniquement du contenu structuré sans composant d’interface utilisateur. Assurez-vous que la liaison de l’interface utilisateur est configurée correctement.

  • Pour les applications MCP, la définition d’outil inclut _meta.ui.resourceUri l’ensemble d’une ressource HTML inscrite avec le type text/html;profile=mcp-appMIME .
  • Pour les applications du SDK OpenAI, la définition de l’outil inclut _meta["openai/outputTemplate"] l’ensemble d’une ressource HTML inscrite avec le type text/html+skybridgeMIME .

Échec du chargement du widget

  • Ouvrez les outils de développement de votre navigateur et recherchez les violations de stratégie de sécurité du contenu (CSP) dans la console, à la dernière case activée. Assurez-vous que les requêtes provenant de l’URL hôte du widget sont dans la liste verte. Pour plus d’informations, consultez Configuration requise du serveur MCP pour les applications MCP.
  • Vérifiez que votre widget compile toutes les dépendances HTML et JavaScript dans un seul fichier sans ressources externes non résolues.

Le widget se charge sans données

  • Vérifiez la structure de réponse de l’outil.
    • content Doit contenir uniquement les données (modèle).
    • structuredContent doit contenir à la fois les données et le widget.
    • _meta Doit contenir uniquement le widget.
  • Vérifier ou structuredContent_meta inclure les données requises.

Le widget dispose d’une double barre de défilement

Le conteneur hôte Copilot dispose déjà d’un défilement avec une hauteur maximale. Désactivez le défilement interne dans votre widget en définissant overflow: hidden vos styles de conteneur.

Les balises <a> d’ancrage ne fonctionnent pas pour les liens externes dans Copilot. Utilisez plutôt les API de plateforme appropriées.

  • Pour les applications MCP, utilisez app.openLink.
  • Pour les applications du SDK OpenAI, utilisez window.openai.openExternal.

Le plein écran ne fonctionne pas chez certains hôtes Copilot

L’affichage en plein écran n’est pas pris en charge sur tous les hôtes Copilot. Il est recommandé de toujours case activée pour les fonctionnalités hôte et d’afficher de manière conditionnelle les éléments d’interface utilisateur (par exemple, un bouton plein écran). Pour plus d’informations, consultez Vérifier la disponibilité de l’API.

Problèmes de réponse

Problèmes d’expiration des résultats de l’outil

Assurez-vous que les réponses de l’outil sont envoyées content ou structuredContent ne sont pas excessivement volumineuses. Si votre widget nécessite des métadonnées riches qui ne sont pas utiles pour le modèle, telles que des URL d’avatar ou des détails spécifiques à l’interface utilisateur, incluez les données _meta complètes et fournissez un résumé concis dans content. Cette approche garantit que le modèle conserve les informations clés tout en prenant en charge une expérience multitour efficace.

Données dupliquées dans le widget et résumé de texte

Résolvez ce problème à l’aide de l’une des options suivantes :

  • Optimiser la séparation des données : à utiliser _meta pour les données spécifiques aux widgets et content pour les résumés visibles par le modèle.
  • Gestion de la mise en forme : utilisez les instructions du manifeste de l’agent déclaratif pour guider la structure et la présentation des réponses.

Problèmes d’authentification

Pour les problèmes d’authentification, tels que les échecs de connexion, les erreurs de jeton, les invites de consentement et les incompatibilités de configuration d’authentification, consultez Résoudre les problèmes de MCP et de l’authentification des plug-ins d’API.