Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
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
RemoteMCPServerruntime est définirun_for_functionssur["*"]et le tableau de niveaufunctionssupérieur est vide. - La méthode du serveur renvoie des
tools/listoutils. 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
functionssupérieur. - Fait référence aux outils de la
mcp_tool_descriptionpropriété par :- Référencement d’un fichier JSON qui contient les descriptions des outils dans la
filepropriété OU - Listing des descriptions des outils en ligne dans la
toolspropriété
- Référencement d’un fichier JSON qui contient les descriptions des outils dans la
- Inclut les noms des outils dans la
run_for_functionsproprié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.visibilityinclut .model - Pour les applications du SDK OpenAI,
meta["openai/visibility"]est définie surpublic.
- Pour les applications MCP,
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.resourceUril’ensemble d’une ressource HTML inscrite avec le typetext/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 typetext/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.
-
contentDoit contenir uniquement les données (modèle). -
structuredContentdoit contenir à la fois les données et le widget. -
_metaDoit contenir uniquement le widget.
-
- Vérifier ou
structuredContent_metainclure 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 liens hypertexte dans le widget ne s’ouvrent pas
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
_metapour les données spécifiques aux widgets etcontentpour 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.