Konfigurieren von MCP-Remoteservern für Microsoft 365 Copilot-Plug-Ins

Ein Microsoft Microsoft 365 Copilot-Plug-In verbindet unterstützte Microsoft-Erfahrungen mit Tools, die von einem MCP-Remoteserver (Model Context Protocol) bereitgestellt werden. Das Plug-In-Paket enthält die Verbindungskonfiguration, und der Server wird separat ausgeführt.

Verwenden Sie Work IQ Dev Tools (WIQD), um Ihr Plug-In zu erstellen, zu validieren und zu verpacken. Beginnen Sie mit Erstellen eines Plug-Ins mit Work IQ Dev Tools.

In den folgenden Abschnitten wird die zugrunde liegende Konfiguration für Entwickler erläutert, die das Manifest manuell bearbeiten müssen. Registrieren Sie den Remote-MCP-Server Ihres Plug-Ins im agentConnectors Array des Microsoft 365-App-Manifests. Dieser Schemabezeichner bleibt erhalten agentConnectors , auch wenn das installierbare Paket als Plug-in bezeichnet wird.

Voraussetzungen

Stellen Sie zunächst sicher, dass Sie über Folgendes verfügen:

• Einen Testmandanten und eine Microsoft-Zieloberfläche, die Plug-Ins unterstützt, die über konfiguriert wurden agentConnectors.
• Einen funktionierenden MCP-Server mit einem öffentlich zugänglichen HTTPS-Endpunkt, TLS 1.2 oder höher und einem Transport, der von der Zielerfahrung unterstützt wird.
• Ein Microsoft 365-App-Paket mit einer Manifestversion, die von der Zieloberfläche und dem von Ihnen ausgewählten Autorisierungstyp unterstützt wird.
• Eine für Ihren Server registrierte Autorisierungskonfiguration, z. B. eine OAuth-Konfiguration oder eine API-Schlüsselkonfiguration, es sei denn, der Server lässt anonymen Zugriff zu.

Informationen zu den Anforderungen an WIQD-Server und die Anforderung zur Beschreibung des Copilot Cowork-Tools finden Sie unter Work IQ Dev Tools.

Hinzufügen des MCP-Servers zu Ihrem App-Manifest

Deklarieren Sie Ihren MCP-Server im agentConnectors-Array auf der Stammebene Ihres App-Manifests.

1. Öffnen Sie das App-Manifest in Ihrem Microsoft 365-App-Paket.
2. Suchen oder erstellen Sie das Array auf Stammebene agentConnectors .
3. Fügen Sie einen Eintrag mit den eindeutigen idWerten , a displayName, a descriptionund a toolSource hinzu, der Ihren Remote-MCP-Server identifiziert.

Der folgende JSON-Code ist ein Fragment, das in Ihr vorhandenes App-Manifest eingefügt werden muss, kein vollständiges App-Manifest:

{
  "$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"
          }
        }
      }
    }
  ]
}

Ersetzen Sie den Endpunkt und die Autorisierungsreferenz durch die Werte Ihres Servers. Die Einträge id müssen innerhalb agentConnectorsvon eindeutig sein. Behalten Sie die anderen erforderlichen App-Manifesteigenschaften in Ihrer vorhandenen Datei bei.

Konfigurieren des Serverendpunkts

Legen Sie toolSource.remoteMcpServer.mcpServerUrl auf Ihren HTTPS-Endpunkt fest. Vergewissern Sie sich, dass der Server von der Zielumgebung aus erreichbar ist und auf die MCP-Initialisierung und nachfolgende Protokollanforderungen reagiert.

Konfigurieren einer Authentifizierung

Innerhalb authorization von agentConnectors[].toolSource.remoteMcpServer. In der folgenden Tabelle sind die Autorisierungstypen und ihre Konfiguration aufgeführt. Details zum Schema finden Sie im Autorisierungsschema.

Ein Schemawert garantiert keine Unterstützung in der Zielumgebung. Überprüfen Sie die Authentifizierungsanforderungen, bevor Sie eine Methode auswählen.

Das referenceId identifiziert eine vom Manifest separat erworbene Konfiguration. Geben Sie API-Schlüssel, Zugriffstoken, geheime Clientschlüssel oder geheime Werte weder in diesem Feld noch an einer anderen Stelle im App-Manifest ein.

Verwenden der OAuth-Authentifizierung

Verwenden Sie für OAuth 2.0-Token, die im Microsoft-Tresor gespeichert sind, das folgende authorization Objekt:

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

Registrieren Sie die OAuth-Konfiguration im Entwicklerportal und verwenden Sie die zurückgegebene Konfigurations-ID als referenceId. Weitere Informationen finden Sie unter Konfigurieren von OAuth im Entwicklerportal.

Fügen Sie die folgende Rückruf-URL zu den zulässigen Umleitungs-URIs in Ihrer OAuth-Anbieterregistrierung hinzu:

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

Verwenden der API-Schlüsselauthentifizierung

Verwenden Sie für einen API-Schlüssel, der in einem Tresor gespeichert ist, das folgende authorization Objekt:

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

Registrieren Sie den Schlüssel im Entwicklerportal, und ersetzen Sie my-apikey ihn dann durch die zurückgegebene Registrierungs-ID. Weitere Informationen finden Sie unter API-Schlüsselauthentifizierung.

Verwenden der dynamischen Clientregistrierung

Die dynamische Clientregistrierung ermöglicht es dem Host, sich mithilfe von RFC 7591 als OAuth-Client bei Ihrem MCP-Server zu registrieren. Beide müssen den Registrierungsfluss unterstützen. Microsoft Entra ID stellt keinen RFC 7591-Registrierungsendpunkt bereit. Verwenden Sie eine statische OAuth-Registrierung für einen Entra-geschützten Server.

Verwenden Sie das folgende authorization Objekt:

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

Registrieren Sie die Konfiguration im Entwicklerportal und ersetzen Sie my-dcr-config sie durch ihre Referenz-ID. Die Konfiguration stellt die Autorisierungswerte bereit, die der Host beim Aushandeln von Clientanmeldeinformationen verwendet.

Ihr Server muss:

• Machen Sie einen RFC 7591-Clientregistrierungsendpunkt verfügbar.
• Geben Sie die Clientregistrierungsinformationen zurück, die für den OAuth-Fluss des Hosts erforderlich sind.
• Unterstützung der Tokenaktualisierung, falls erforderlich für langlebige Sitzungen.

Verwenden Azure Key Vault Authentifizierung

AzureKeyVault ist in den App-Manifestschemas 1.29 und 1.30 enthalten. Verwenden Sie es nur, wenn die Zielerfahrung eine Azure Key Vault Integration und einen Prozess zum Abrufen der Konfigurationsreferenz dokumentiert.

Verwenden Sie das folgende authorization Objekt:

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

Befolgen Sie die Anforderungen für die Speicherung von Anmeldeinformationen und den Zugriff dieser Integration, und ersetzen Sie my-keyvault-config sie durch die zurückgegebene Referenz. Die Manifestdeklaration allein gewährt keinen Zugriff auf Geheimnisse.

Verwenden der Connection Vault-Authentifizierung

Verwenden Sie für eine unterstützte Verbindungstresorintegration das folgende authorization Objekt:

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

Ersetzen Sie den Verbindungsverweis shared_example , der von der Zielintegration bereitgestellt wird.

Keine Authentifizierung verwenden

Wenn Ihr Server anonymen Zugriff zulässt, setzen Sie authorization.type diese Option None oder lassen Sie sie weg authorization , wenn der Host dies zulässt.

Bevorzugen Sie authentifizierten Zugriff für Produktions- und Unternehmensszenarien und OAuth gegenüber API-Schlüsseln, sofern unterstützt.

Definieren der Toolermittlung

Verwenden Sie gepackte Tooldefinitionen, wenn das Toolset fest ist, oder dynamische Ermittlung, wenn sowohl die App-Manifestversion als auch der Zielhost dies unterstützen.

Statische Tooldefinitionen verwenden

Fügen Sie eine Toolbeschreibungsdatei in Ihr App-Paket ein, und verweisen Sie darin darauf remoteMcpServer. Der Pfad ist relativ zum App-Paket. Verwenden Sie die Tooldefinitionen tools/list aus dem Ergebnis Ihres Servers, einschließlich des Namens, der Beschreibung und des Eingabeschemas der einzelnen Tools. Eine minimale toolDescription.json Datei kann z. B. Folgendes enthalten:

{
  "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"
        ]
      }
    }
  ]
}

Sorgen Sie dafür, dass die gepackten Definitionen für den Server konsistent sind.

Verwenden der dynamischen Toolermittlung

Die dynamische Ermittlung ermöglicht es einem Host, die Toolliste zur Laufzeit abzurufen tools/list , anstatt sich auf paketierte Definitionen zu verlassen.

App-Manifestversion 1.29 oder höher erlaubt es Ihnen, mcpToolDescription wegzulassen. Frühere Versionen benötigen die Datei. Copilot Cowork benötigt auch mit Version 1.29 oder höher weiterhin eine Toolbeschreibungsdatei. Mit WIQD geben Sie es über --tool-description; siehe Work IQ Dev Tools.

Für eine Zielerfahrung, die die dynamische Ermittlung unterstützt, lassen Sie die Option mcpToolDescription aus, damit Definitionen über tools/listabgerufen werden können. Geben Sie Toolnamen, Beschreibungen und Eingabeschemata zurück und testen Sie, wie Änderungen am Toolset aktualisiert werden.

Validieren und testen Sie Ihr Plug-In

Überprüfen Sie das Paket vor der Bereitstellung, und testen Sie es dann in der Zielumgebung:

1. Überprüfen Sie das vollständige App-Manifest anhand des deklarierten Schemas, und verwenden Sie die App-Paketvalidierung im Entwicklerportal.
2. Stellen Sie sicher, dass der Endpunkt auf die MCP-Initialisierung reagiert und ob die gepackte Datei oder tools/list die Bereitstellung gültiger Tooldefinitionen erfolgt.
3. Stellen Sie das Paket über den unterstützten Prozess der Zielerfahrung für Ihren Testmandanten bereit. Schließen Sie alle erforderlichen Administratorgenehmigungen oder Zugriffskonfigurationen ab. Die Bereitstellung ersetzt weder die Benutzeranmeldung, Zustimmung noch die Berechtigungen des Quelldiensts.
4. Testen Sie Eingabeaufforderungen für die Vorgänge, die Ihr Server verfügbar macht, z. B. "Suche nach offenen Problemen, die mir zugewiesen wurden" oder bei einem Server mit Schreibtools "Aktualisieren Sie den Status von Ticket Nummer 123".
5. Stellen Sie sicher, dass die vorgesehenen Tools verfügbar sind, Zustimmungsaufforderungen angezeigt werden, wenn erforderlich, und Toolaufrufe geben die erwarteten Ergebnisse zurück. Testen Sie ggf. die OAuth-Tokenaktualisierung.
6. Überprüfen Sie Fehler auf ungültige Eingaben, nicht verfügbare Dienste, Autorisierungsfehler und Timeouts, einschließlich Wiederholungsverhalten.
7. Testen Sie mandantenübergreifend, wenn Ihr Szenario mehrinstanzenfähige Unterstützung erfordert.

Problembehandlung häufiger Probleme

Nächste Schritte

Wenn die Integration fertig ist, verpacken Sie Ihr Plug-In und befolgen Sie eine unterstützte Veröffentlichungs- oder Freigabemethode.