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 fait apparaître 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 les informations de débogage carte, consultez Utiliser le mode développeur dans Microsoft 365 Copilot pour tester et déboguer des agents.

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

Aucun outil répertorié

Si la section Actions du 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 approprié dans le manifeste de votre plug-in.
  • Vérifiez que votre manifeste de plug-in inclut les outils attendus dans la functions propriété .
  • Vérifiez que le runtime du serveur MCP spécifié dans la propriété dans le runtimes manifeste de votre plug-in :
    • 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é OR
      • Liste des descriptions de l’outil inline 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": "mcp-tools.json"
    },
    "run_for_functions": [
      "get_widget",
      "create_widget"
    ]
  }
]

Les outils ne se déclenchent pas à partir d’une conversation Copilot

  • Réexaminez les descriptions de vos outils et paramètres pour vous assurer qu’elles fournissent un contexte suffisant. Envisagez de les réécrire à l’aide de « Utiliser cette fonction/ce paramètre quand... » Phrasé.
  • Conservez les descriptions sous 1 024 caractères. Le texte au-delà de 1 024 caractères est ignoré.
  • Vérifiez que la visibilité de l’outil est correctement définie.
    • Pour les applications MCP, _meta.ui.visibility inclut model.
    • Pour les applications du Kit de développement logiciel (SDK) OpenAI, meta["openai/visibility"] est défini sur public.

L’outil incorrect est sélectionné

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

Problèmes liés aux widgets

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 retourne probablement uniquement du contenu structuré sans composant d’interface utilisateur. Vérifiez que la liaison d’interface utilisateur est correctement configurée.

  • Pour les applications MCP, la définition de l’outil inclut _meta.ui.resourceUri défini sur une ressource HTML inscrite avec le type text/html;profile=mcp-appMIME .
  • Pour les applications du Kit de développement logiciel (SDK) OpenAI, la définition de l’outil inclut _meta["openai/outputTemplate"] définie sur 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 case activée pour les violations de stratégie de sécurité de contenu (CSP) dans la console. Vérifiez que les demandes provenant de l’URL hôte du widget sont répertoriées 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.

Chargements de widgets 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érifiez ou _meta incluez structuredContent les données requises.

Le widget a une barre de défilement double

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

Les balises d’ancre <a> 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 Kit de développement logiciel (SDK) OpenAI, utilisez window.openai.openExternal.

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

L’affichage 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 de l’hôte et d’afficher de manière conditionnelle des é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

Vérifiez que les réponses de l’outil envoyées via content ou structuredContent ne sont pas trop volumineuses. Si votre widget nécessite des métadonnées enrichies 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 complètes dans _meta 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 multiturm efficace.

Dupliquer des données dans le résumé du widget et du texte

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

  • Optimiser la séparation des données : utilisez pour les _meta données spécifiques au widget et content pour les résumés visibles par modèle.
  • Diriger la mise en forme : utilisez les instructions du manifeste de l’agent déclaratif pour guider la façon dont les réponses sont structurées et présentées.

Problèmes d’authentification

Incompatibilité de l’ID d’application entre la configuration d’authentification et le plug-in

Si vous voyez des erreurs dans vos informations de débogage carte similaires à :

OAuth authentication failed: The App ID used in the request does not match the App ID in the authentication configuration. (HTTP 404)

Accédez au portail des développeurs Teams. Recherchez votre client OAuth ou l’inscription du client de l’authentification unique (SSO) et vérifiez que l’ID d’application dans votre plug-in correspond à l’ID d’application inscrit.

L’URL de base dans la configuration d’authentification ne correspond pas au plug-in

Si vous voyez des erreurs dans vos informations de débogage carte similaires à :

OAuth authentication failed: The base URL in your authentication configuration does not match the server URL. (HTTP 401)

Accédez au portail des développeurs Teams. Recherchez votre client OAuth ou votre inscription de client SSO et vérifiez que l’URL du serveur MCP dans votre plug-in correspond à l’URL de base inscrite.

L’ID de référence dans le manifeste du plug-in est incorrect ou manquant

Si vous voyez des erreurs dans vos informations de débogage carte similaires à :

OAuth authentication failed: No matching configuration found for referenceID in 'runtime.auth' section of the action manifest

Accédez au portail des développeurs Teams. Recherchez l’inscription de votre client OAuth ou de votre client SSO et vérifiez que l’ID du runtime auth.reference_id de votre serveur MCP correspond à l’ID de l’inscription dans le portail des développeurs.

La stratégie d’organisation restreint l’accès

Si vous voyez des erreurs dans vos informations de débogage carte similaires à :

OAuth authentication failed: Access is restricted by your organization's policy. (HTTP 404)

Contactez les administrateurs de votre organization pour examiner et activer l’accès à votre application.

Le bouton De connexion est inactif ou affiche une erreur générale

Si votre bouton de connexion est inactif ou désactivé, ou si vous le sélectionnez, vous obtenez une erreur générale « La demande ne peut pas être traitée », cette condition peut indiquer des problèmes temporaires d’authentification ou de session. Réessayez la requête. Si le problème persiste, réinstallez l’application ou contactez les administrateurs de votre organization.

Échec de l’ouverture de la fenêtre contextuelle de connexion

Activez les fenêtres contextuelles pour le site dans les paramètres de votre navigateur, puis réessayez.

Erreur d’informations d’identification incorrectes

Si vous voyez une erreur « Informations d’identification incorrectes » dans la fenêtre contextuelle de connexion ou la réponse de conversation, vérifiez que vous entrez les informations d’identification correctes. Si l’erreur persiste, vérifiez que l’utilisateur dispose des autorisations requises.

URL de connexion introuvable

Désinstallez et réinstallez l’application, puis réessayez de vous connecter.

Erreur interne du serveur pendant l’authentification

Vérifiez les détails dans la fenêtre contextuelle d’authentification et contactez les administrateurs de votre organization pour les problèmes d’autorisations.

Si une boîte de dialogue de consentement s’affiche pour demander des autorisations ou une justification métier, passez en revue les autorisations demandées et fournissez une justification métier si nécessaire. Si vous n’êtes pas sûr ou si la boîte de dialogue de consentement demande des autorisations qui nécessitent le consentement de l’administrateur, contactez les administrateurs de votre organization.

Contenu connexe

  • Last updated on