Configurer des serveurs MCP distants pour les plug-ins Microsoft 365 Copilot

Un plug-in Microsoft 365 Copilot connecte les expériences Microsoft prises en charge aux outils fournis par un serveur MCP (Model Context Protocol) distant. Le package de plug-in contient la configuration de connexion et le serveur s’exécute séparément.

Utilisez les outils de développement Work IQ (WIQD) pour créer, valider et empaqueter votre plug-in. Commencez par Créer un plug-in avec les outils de développement Work IQ.

Les sections suivantes expliquent la configuration sous-jacente pour les développeurs qui doivent modifier le manifeste manuellement. Enregistrez le serveur MCP distant de votre plug-in dans le agentConnectors tableau du manifeste de l’application Microsoft 365. Cet identificateur de schéma est conservé agentConnectors même si le package installable est appelé plug-in.

Important

Cette configuration utilise le manifeste de l’application Microsoft 365 et non le manifeste du plug-in MCP utilisé pour les actions d’agent déclaratif. Il est également distinct de l’itinéraire d’inscription de CLI d’Agent 365. Pour connaître ces alternatives, consultez Créer ou réutiliser des serveurs MCP. La prise en charge de MCP seule n’établit pas la prise en charge de ce modèle d’inscription.

Configuration requise

Avant de commencer, assurez-vous d’avoir les éléments suivants :

  • Un client de test et une expérience Microsoft cible qui prend en charge les plug-ins configurés via agentConnectors.
  • Un serveur MCP fonctionnel avec un point de terminaison HTTPS accessible publiquement, TLS 1.2 ou version ultérieure, et un transport pris en charge par l’expérience cible.
  • Package d’application Microsoft 365 avec une version de manifeste prise en charge par l’expérience cible et le type d’autorisation que vous avez choisi.
  • Une configuration d’autorisation inscrite pour votre serveur, telle qu’une configuration OAuth ou une configuration de clé API, sauf si le serveur autorise l’accès anonyme.

Pour connaître la configuration requise du serveur WIQD et l’exigence de description de l’outil Copilot Cowork, consultez Outils de développement Work IQ.

Ajouter le serveur MCP au manifeste de votre application

Déclarez votre serveur MCP dans le tableau agentConnectors au niveau racine de votre manifeste d’application.

  1. Ouvrez le manifeste de l’application dans votre package d’application Microsoft 365.
  2. Localisez ou créez le tableau de niveau agentConnectors racine.
  3. Ajoutez une entrée avec un unique id, a , a descriptiondisplayNameet a toolSource qui identifie votre serveur MCP distant.

Le JSON suivant est un fragment à fusionner dans votre manifeste d’application existant, pas un manifeste d’application complet :

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.30/MicrosoftTeams.schema.json",
  "manifestVersion": "1.30",
  "agentConnectors": [
    {
      "id": "my-mcp-server",
      "displayName": "My Automation Server",
      "description": "Provides workflow automation and task management tools.",
      "toolSource": {
        "remoteMcpServer": {
          "mcpServerUrl": "https://mcp.example.com/mcp",
          "authorization": {
            "type": "OAuthPluginVault",
            "referenceId": "my-oauth-config"
          },
          "mcpToolDescription": {
            "file": "toolDescription.json"
          }
        }
      }
    }
  ]
}

Remplacez la référence de point de terminaison et d’autorisation par les valeurs de votre serveur. Chaque entrée id doit être unique dans agentConnectors. Conservez les autres propriétés de manifeste d’application requises dans votre fichier existant.

Configurer le point de terminaison du serveur

Définissez toolSource.remoteMcpServer.mcpServerUrl à votre point de terminaison HTTPS. Vérifiez que le serveur est accessible à partir de l’expérience cible et qu’il répond à l’initialisation MCP et aux demandes de protocole ultérieures.

Configurer l’authentification

Défini authorization dans .agentConnectors[].toolSource.remoteMcpServer Le tableau suivant répertorie les types d’autorisation et leur configuration. Pour plus de détails sur le schéma, consultez le schéma d’autorisation.

Type d’autorisation Configuration
None Aucune authentification requise. Utilisez uniquement lorsque le serveur autorise l’accès anonyme.
OAuthPluginVault Configuration OAuth stockée dans le coffre de Microsoft et référencée par ID.
ApiKeyPluginVault Configuration de clé API stockée dans un coffre et référencée par un ID.
DynamicClientRegistration Configuration d’inscription de client OAuth dynamique référencée par l’ID.
AzureKeyVault Configuration Azure Key Vault référencée par l’ID. Nécessite la prise en charge de l’hôte.
ConnectionVault (préversion pour les développeurs) Configuration de connexion référencée par l’ID.

Une valeur de schéma ne garantit pas la prise en charge dans l’expérience cible. Vérifiez ses exigences d’authentification avant de choisir une méthode.

Identifie referenceId une configuration acquise séparément du manifeste. Ne placez pas de clés API, de jetons d’accès, de clés secrètes client ou de valeurs secrètes dans ce champ ou ailleurs dans le manifeste de l’application.

Utiliser l’authentification OAuth

Pour les jetons OAuth 2.0 stockés dans le coffre-fort de Microsoft, utilisez l’objet suivant authorization :

{
  "type": "OAuthPluginVault",
  "referenceId": "my-oauth-config"
}

Enregistrez la configuration OAuth dans le portail Développeur et utilisez l’ID de configuration renvoyé en tant que referenceId. Pour plus d’informations, consultez Configurer OAuth dans le portail Développeur.

Ajoutez l’URL de rappel suivante aux URI de redirection autorisés dans l’inscription de votre fournisseur OAuth :

https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect

Utiliser l’authentification par clé API

Pour une clé API stockée dans un coffre, utilisez l’objet suivant authorization :

{
  "type": "ApiKeyPluginVault",
  "referenceId": "my-apikey"
}

Enregistrez la clé dans le portail Développeurs, puis remplacez-la my-apikey par l’ID d’enregistrement renvoyé. Pour plus d’informations, consultez Authentification par clé API.

Utiliser l’inscription de client dynamique

L’inscription de client dynamique permet à l’hôte de s’inscrire en tant que client OAuth auprès de votre serveur MCP à l’aide de RFC 7591. Les deux doivent prendre en charge le flux d’inscription. Microsoft Entra ID ne fournit pas de point de terminaison d’inscription RFC 7591 ; utiliser l’inscription OAuth statique pour un serveur protégé par Entra.

Utilisez l’objet suivant authorization :

{
  "type": "DynamicClientRegistration",
  "referenceId": "my-dcr-config"
}

Enregistrez la configuration dans le portail Développeur et remplacez-la my-dcr-config par son ID de référence. La configuration fournit les valeurs d’autorisation que l’hôte utilise lors de la négociation des informations d’identification du client.

Votre serveur doit :

  • Exposer un point de terminaison d’inscription client RFC 7591.
  • Renvoie les informations d’inscription client requises par le flux OAuth de l’hôte.
  • Actualisation des jetons de support si nécessaire pour les sessions de longue durée.

Utiliser l’authentification Azure Key Vault

AzureKeyVault est inclus dans les schémas de manifeste d’application 1.29 et 1.30. Utilisez-le uniquement lorsque l’expérience cible documente une intégration Azure Key Vault et un processus d’acquisition de la référence de configuration.

Utilisez l’objet suivant authorization :

{
  "type": "AzureKeyVault",
  "referenceId": "my-keyvault-config"
}

Suivez les exigences d’accès et de stockage des informations d’identification de cette intégration et remplacez-les my-keyvault-config par la référence renvoyée. La déclaration de manifeste seule n’accorde pas l’accès aux secrets.

Utiliser l’authentification par coffre des connexions

Remarque

L’authentification du coffre des connexions est disponible en préversion pour les développeurs. Utilisez le schéma de manifeste d’application d’aperçu développeur pour configurer ConnectionVault; il n’est pas disponible dans les schémas de manifeste d’application généralement disponibles.

Pour une intégration de coffre-connexion prise en charge, utilisez l’objet suivant authorization :

{
  "type": "ConnectionVault",
  "referenceId": "shared_example"
}

Remplacez shared_example par la référence de connexion fournie par l’intégration cible.

Ne pas utiliser d’authentification

Si votre serveur autorise l’accès anonyme, activez authorization.type ou désactivez authorization cette option None lorsque l’hôte l’autorise.

Privilégier l’accès authentifié pour les scénarios de production et d’entreprise, et OAuth aux clés API là où cela est pris en charge.

Définir la découverte d’outils

Utilisez des définitions d’outil empaqueté lorsque l’ensemble d’outils est fixe, ou la découverte dynamique lorsque la version du manifeste de l’application et l’hôte cible le prennent en charge.

Utiliser des définitions d’outils statiques

Incluez un fichier de description d’outil dans votre package d’application et référencez-le dans .remoteMcpServer Le chemin d’accès est relatif au package de l’application. Utilisez les définitions des outils des résultats de tools/list votre serveur, y compris le nom, la description et le schéma d’entrée de chaque outil. Par exemple, un fichier minimal toolDescription.json peut contenir :

{
  "mcpToolDescription": {
    "file": "toolDescription.json"
  }
}
{
  "tools": [
    {
      "name": "get_task",
      "description": "Gets a task by its identifier.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "taskId": {
            "type": "string",
            "description": "The identifier of the task."
          }
        },
        "required": [
          "taskId"
        ]
      }
    }
  ]
}

Maintenez les définitions empaquetées cohérentes avec le serveur.

Utiliser la découverte d’outils dynamiques

La découverte dynamique permet à un hôte d’extraire la liste d’outils au moment de l’exécution au tools/list lieu de s’appuyer sur des définitions empaquetées.

La version 1.29 ou ultérieure du manifeste d’application vous permet d’omettre mcpToolDescription. Les versions antérieures nécessitent le fichier. Copilot Cowork nécessite toujours un fichier de description d’outil, même avec la version 1.29 ou ultérieure. Avec WIQD, fournissez-le via --tool-description; voir Outils de développement Work IQ.

Pour une expérience cible qui prend en charge la découverte dynamique, omettez mcpToolDescription afin qu’elle puisse récupérer les définitions via tools/list. Renvoyer les noms d’outils, les descriptions et les schémas d’entrée et tester la manière dont les modifications apportées au jeu d’outils sont actualisées.

Valider et tester votre plug-in

Validez le package avant de le déployer, puis testez-le dans l’expérience cible :

  1. Validez le manifeste d’application complet par rapport à son schéma déclaré et utilisez la validation de package d’application dans le portail de développement.
  2. Vérifiez que le point de terminaison répond à l’initialisation MCP et que le fichier empaqueté ou tools/list fournit des définitions d’outil valides.
  3. Déployez le package sur votre locataire test via le processus pris en charge de l’expérience cible. Effectuez toute configuration d’accès ou approbation de l’administrateur requise. Le déploiement ne remplace pas la connexion de l’utilisateur, le consentement ou les autorisations du service source.
  4. Invites de test pour les opérations que votre serveur expose, telles que « Rechercher les problèmes ouverts qui m’ont été attribués » ou, pour un serveur doté d’outils d’écriture, « Mettre à jour l’état du ticket numéro 123 ».
  5. Vérifiez que les outils prévus sont disponibles, que des invites de consentement s’affichent si nécessaire et que les appels d’outils renvoient les résultats attendus. Testez l’actualisation du jeton OAuth, le cas échéant.
  6. Vérifiez les échecs pour les entrées non valides, les services indisponibles, les erreurs d’autorisation et les délais d’expiration, y compris le comportement des nouvelles tentatives.
  7. Testez plusieurs locataires si votre scénario nécessite une prise en charge multilocataire.

Résoudre les problèmes courants

Symptôme Chèque
Impossible de se connecter au serveur Accessibilité des points de terminaison, HTTPS, prise en charge du transport, paramètres de pare-feu et initialisation MCP.
Les outils n’apparaissent pas Chemin d’accès aux fichiers empaquetés et définitions valides, ou prise en charge de la découverte dynamique avec mcpToolDescription omis et un fichier de travail tools/list.
Échecs d’authentification Inscrits referenceId, validité des informations d’identification, autorisations, consentement et en-têtes d’autorisation sortante.
Échec ou expiration des appels d’outil Journaux du serveur, validation des entrées, format de réponse MCP, concurrence, délais d’expiration et tentatives.

Étapes suivantes

Lorsque l’intégration est prête, empaquetez votre plug-in et suivez une méthode de publication ou de partage prise en charge.