Problembehandlung für MCP-Apps in Microsoft 365 Copilot

Dieses Handbuch enthält Ratschläge zur Problembehandlung für häufige Probleme, die beim Entwickeln einer MCP-App (Model Context Protocol) zur Integration in einen deklarativen Agent in Microsoft 365 Copilot auftreten können.

Entwicklermodus aktivieren

Wenn Sie den Entwicklermodus aktivieren , werden Protokolle und Fehler in den Antworten des Agents angezeigt. Diese Informationen sind wichtig für das Debuggen. Geben Sie in Microsoft Copilot den folgenden Befehl ein, um den Entwicklermodus zu aktivieren.

-developer on

MCP-Tools, die Ihrem Agent zur Verfügung stehen, werden im Abschnitt "Aktionen" der Debug-Informations-Karte angezeigt. Ausführliche Informationen zur Debug-Information-Karte finden Sie unter Verwenden des Entwicklermodus in Microsoft 365 Copilot zum Testen und Debuggen von Agents.

Probleme bei der Ermittlung und Eingabe

Keine Tools aufgeführt

Wenn im Abschnitt "Aktionen" der Debug-Informations-Karte keine MCP-Tools aufgeführt sind, überprüfen Sie die folgenden Elemente:

  • Vergewissern Sie sich, dass Ihr MCP-Server ausgeführt wird und Sie eine Verbindung mit dem richtigen MCP-Endpunkt in Ihrem Plug-In-Manifest herstellen.
  • Vergewissern Sie sich, dass die Authentifizierung erfolgreich war. Viele MCP-Server geben keine Tools zurück, bis sich der Benutzer anmeldet, sodass eine fehlgeschlagene oder übersprungene Anmeldung zu einer leeren Toolliste führen kann.

Dynamische Toolermittlung

Wenn Ihr Agent die dynamische Toolermittlung verwendet (Standardeinstellung), werden die Tools zur Laufzeit vom Server aufgelöst. Stellen Sie Folgendes sicher:

  • Die RemoteMCPServer Laufzeit wird run_for_functions auf festgelegt, ["*"] und das Array der obersten Ebene functions ist leer.
  • Die Methode des tools/list Servers gibt Werkzeuge zurück. Sie können die Antwort mit einem Tool wie MCP Inspector überprüfen.
  • Ein neu entdecktes oder geändertes Tool wird nicht von der Laufzeitüberprüfung zurückgehalten. Überprüfen Sie die Debuginformationen auf Validierungsfehler.
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp"
    },
    "run_for_functions": [
      "*"
    ]
  }
]

Angeheftete Tools

Wenn Sie einen festen Satz von Tools angeheftet haben, stellen Sie sicher, dass die MCP-Serverruntime, die in der runtimes Eigenschaft Ihres Plug-In-Manifests angegeben ist:

  • Enthält die erwarteten Werkzeuge in der Eigenschaft der obersten Ebene functions .
  • Verweist auf die Tools in der mcp_tool_description Eigenschaft, indem er entweder:
    • Verweisen auf eine JSON-Datei, die die Werkzeugbeschreibungen in der file Eigenschaft ODER
    • Auflisten der Toolbeschreibungen in der tools Eigenschaft
  • Fügt die Werkzeugnamen in die run_for_functions Eigenschaft ein.
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp",
      "mcp_tool_description": {
        "file": "mcp-tools.json"
      }
    },
    "run_for_functions": [
      "get_widget",
      "create_widget"
    ]
  }
]

Tools, die nicht vom Copilot-Chat ausgelöst werden

  • Überprüfen Sie Ihre Tool- und Parameterbeschreibungen, um sicherzustellen, dass sie genügend Kontext bieten. Erwägen Sie, sie mit "Verwenden Sie diese Funktion/diesen Parameter, wenn..." Formulierung.
  • Halten Sie Beschreibungen unter 1.024 Zeichen. Text mit mehr als 1.024 Zeichen wird ignoriert.
  • Stelle sicher, dass die Sichtbarkeit des Tools richtig eingestellt ist.
    • Für MCP-Apps _meta.ui.visibility beinhaltet model.
    • Für OpenAI SDK-Apps meta["openai/visibility"] ist festgelegt auf public.

Das falsche Tool ist ausgewählt

  • Vermeiden Sie Tools mit ähnlichen Namen oder überlappenden Beschreibungen.
  • Fügen Sie klare Unterscheidungsmerkmale in Beschreibungen hinzu, die erklären, wann jedes Tool verwendet werden sollte.

Probleme mit Widget

Widget wird nicht gerendert

Wenn das richtige MCP-Tool aufgerufen wird, Ihr UI-Widget jedoch nicht in der Antwort gerendert wird, gibt Ihr MCP-Server wahrscheinlich nur strukturierte Inhalte ohne UI-Komponente zurück. Stellen Sie sicher, dass die Benutzeroberflächenbindung korrekt konfiguriert ist.

  • Für MCP-Apps enthält _meta.ui.resourceUri die Tooldefinition eine auf eine registrierte HTML-Ressource mit dem MIME-Typ text/html;profile=mcp-appfestgelegte .
  • Für OpenAI SDK-Apps enthält _meta["openai/outputTemplate"] die Tooldefinition das Festlegen auf eine registrierte HTML-Ressource mit dem MIME-Typ text/html+skybridge.

Widget kann nicht geladen werden

  • Öffnen Sie die Entwicklertools Ihres Browsers, und überprüfen Sie die Konsole auf Verstöße gegen die Inhaltssicherheitsrichtlinie (Content Security Policy, CSP). Stellen Sie sicher, dass Anforderungen von der Host-URL des Widgets auf die Zulassungsliste gesetzt sind. Weitere Informationen finden Sie unter MCP-Serveranforderungen für MCP-Apps.
  • Stellen Sie sicher, dass Ihr Widget alle HTML- und JavaScript-Abhängigkeiten in eine einzige Datei ohne externe unaufgelöste Ressourcen kompiliert.

Widget wird ohne Daten geladen

  • Überprüfen Sie die Antwortstruktur des Tools.
    • content darf nur die Daten (das Modell) enthalten.
    • structuredContent sollte sowohl die Daten als auch das Widget enthalten.
    • _meta sollte nur das Widget enthalten.
  • Stellen Sie structuredContent sicher, dass die erforderlichen Daten vorhanden sind, oder _meta schließen Sie sie ein.

Widget hat eine doppelte Bildlaufleiste

Der Copilot-Hostcontainer verfügt bereits über einen Bildlauf mit maximaler Höhe. Deaktivieren Sie den inneren Bildlauf in Ihrem Widget, indem Sie Container-Stile festlegen overflow: hidden .

Ankertags <a> funktionieren nicht für externe Links in Copilot. Verwenden Sie stattdessen die entsprechenden Plattform-APIs.

  • Verwenden Sie app.openLinkfür MCP-Apps .
  • Verwenden Sie window.openai.openExternalfür OpenAI SDK-Apps .

Vollbildmodus funktioniert in einigen Copilot-Hosts nicht

Die Vollbildansicht wird nicht auf allen Copilot-Hosts unterstützt. Überprüfen Sie als bewährte Methode immer die Hostfunktionen und zeigen Sie bedingt UI-Elemente (z. B. eine Schaltfläche im Vollbildmodus) an. Weitere Informationen finden Sie unter Überprüfen der API-Verfügbarkeit.

Probleme mit der Antwort

Probleme mit Ablauf des Toolergebnisses

Stellen Sie sicher, dass die Toolantworten gesendet werden content oder structuredContent nicht übermäßig groß sind. Wenn Ihr Widget umfangreiche Metadaten benötigt, die für das Modell nicht nützlich sind, wie z. B. Avatar-URLs oder UI-spezifische Details, fügen Sie die vollständigen Daten ein _meta und geben Sie eine präzise Zusammenfassung in content. Dieser Ansatz stellt sicher, dass das Modell wichtige Informationen beibehält und gleichzeitig ein effektives Multiturn-Erlebnis unterstützt.

Duplizieren von Daten in Widget und Textzusammenfassung

Verwenden Sie eine der folgenden Optionen, um das Problem zu beheben:

  • Optimieren Sie die Datentrennung: Verwenden Sie diese Option _meta für Widget-spezifische Daten und content für modellsichtbare Zusammenfassungen.
  • Steuerung der Formatierung: Verwenden Sie Anweisungen im manifesten deklarativen Agent, um zu steuern, wie Antworten strukturiert und präsentiert werden.

Authentifizierungsprobleme

Bei Authentifizierungsproblemen wie Anmeldefehlern, Tokenfehlern, Zustimmungsaufforderungen und nicht übereinstimmender Authentifizierungskonfiguration finden Sie weitere Informationen unter Problembehandlung bei der MCP- und API-Plug-In-Authentifizierung.