Problembehandlung für MCP-Apps in Microsoft 365 Copilot

Dieser Leitfaden enthält Hinweise zur Problembehandlung bei häufigen Problemen, die bei der Entwicklung einer MCP-App (Model Context Protocol) zur Integration mit einem deklarativen Agent in Microsoft 365 Copilot auftreten können.

Aktivieren des Entwicklermodus

Beim Aktivieren des Entwicklermodus werden Protokolle und Fehler in Agentantworten angezeigt. Diese Informationen sind für das Debuggen von entscheidender Bedeutung. Um den Entwicklermodus zu aktivieren, geben Sie den folgenden Befehl in Microsoft Copilot ein.

-developer on

MCP-Tools, die für Ihren Agent verfügbar sind, werden im Abschnitt Aktionen der Debuginformationen Karte angezeigt. Ausführliche Informationen zu den Debuginformationen Karte finden Sie unter Verwenden des Entwicklermodus in Microsoft 365 Copilot zum Testen und Debuggen von Agents.

Ermittlungs- und Eingabeprobleme

Keine Tools aufgeführt

Wenn der Abschnitt Aktionen der Debuginformationen Karte keine MCP-Tools auflistet, überprüfen Sie die folgenden Punkte.

  • 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 Ihr Plug-In-Manifest die erwarteten Tools in der functions -Eigenschaft enthält.
  • Überprüfen Sie, ob die MCP-Serverruntime in der runtimes -Eigenschaft in Ihrem Plug-In-Manifest angegeben ist:
    • Verweist auf die Tools in der mcp_tool_description -Eigenschaft wie folgt:
      • Verweisen auf eine JSON-Datei, die die Beschreibungen des Tools in der file Eigenschaft ODER enthält
      • Auflisten der Toolbeschreibungen inline in der tools -Eigenschaft
    • Schließt die Toolnamen in die run_for_functions -Eigenschaft ein.
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp",
      "mcp_tool_description": "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 erneut, um sicherzustellen, dass sie ausreichend Kontext bieten. Erwägen Sie, sie mit "Verwenden Sie diese Funktion/diesen Parameter, wenn..." umzuschreiben. Phrasierung.
  • Belassen Sie Beschreibungen unter 1.024 Zeichen. Text über 1.024 Zeichen wird ignoriert.
  • Stellen Sie sicher, dass die Toolsichtbarkeit ordnungsgemäß festgelegt ist.
    • Enthält für MCP-Apps _meta.ui.visibilitymodel.
    • Für OpenAI SDK-Apps meta["openai/visibility"] ist auf publicfestgelegt.

Das falsche Tool ist ausgewählt.

  • Vermeiden Sie Tools mit ähnlichen Namen oder überlappenden Beschreibungen.
  • Fügen Sie klare Unterscheidungsmerkmale in Beschreibungen hinzu, die erläutern, wann die einzelnen Tools verwendet werden sollten.

Widgetprobleme

Widget wird nicht gerendert

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

  • Für MCP-Apps umfasst _meta.ui.resourceUri die Tooldefinition, die auf eine registrierte HTML-Ressource mit dem MIME-Typ text/html;profile=mcp-appfestgelegt ist.
  • Für OpenAI SDK-Apps umfasst _meta["openai/outputTemplate"] die Tooldefinition, die auf eine registrierte HTML-Ressource mit dem MIME-Typ text/html+skybridgefestgelegt ist.

Widget kann nicht geladen werden

  • Öffnen Sie die Entwicklertools Ihres Browsers, und suchen Sie in der Konsole nach Verstößen gegen die Inhaltssicherheitsrichtlinie (Content Security Policy, CSP). Stellen Sie sicher, dass Anforderungen von der Host-URL des Widgets zugelassen 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 einzelne Datei ohne externe, nicht aufgelöste Ressourcen kompiliert.

Widget wird ohne Daten geladen

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

Widget verfügt über 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 in Ihren Containerstilen 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 .

Vollbild funktioniert in einigen Copilot-Hosts nicht

Die Vollbildansicht wird nicht auf allen Copilot-Hosts unterstützt. Als bewährte Methode sollten Sie immer nach Hostfunktionen suchen und UI-Elemente (z. B. eine Vollbildschaltfläche) bedingt anzeigen. Weitere Informationen finden Sie unter Überprüfen der API-Verfügbarkeit.

Antwortprobleme

Probleme beim Ablauf des Toolergebnisses

Stellen Sie sicher, dass Toolantworten, die über content oder structuredContent gesendet werden, nicht übermäßig umfangreich sind. Wenn Ihr Widget umfangreiche Metadaten benötigt, die für das Modell nicht nützlich sind, z. B. Avatar-URLs oder benutzeroberflächenspezifische Details, schließen Sie die vollständigen Daten in _meta ein, und geben Sie eine kurze Zusammenfassung in contentan. Dieser Ansatz stellt sicher, dass das Modell wichtige Informationen beibehält und gleichzeitig eine effektive Multiturmerfahrung unterstützt.

Duplizieren von Daten in Widget und Textzusammenfassung

Beheben Sie dieses Problem mit einer der folgenden Optionen:

  • Optimieren der Datentrennung: Verwenden Sie für _meta Widget-spezifische Daten und content für modell sichtbare Zusammenfassungen.
  • Steuern der Formatierung: Verwenden Sie die Anweisungen im Manifest des deklarativen Agents, um zu steuern, wie Antworten strukturiert und dargestellt werden.

Authentifizierungsprobleme

App-ID-Konflikt zwischen Authentifizierungskonfiguration und Plug-In

Wenn in Ihren Debuginformationen Fehler angezeigt werden, Karte ähnlich wie:

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

Wechseln Sie zum Teams-Entwicklerportal. Suchen Sie nach Ihrer OAuth-Client- oder SSO-Clientregistrierung (Single Sign-On, SSO), und überprüfen Sie, ob die App-ID in Ihrem Plug-In mit der registrierten App-ID übereinstimmt.

Die Basis-URL in der Authentifizierungskonfiguration stimmt nicht mit dem Plug-In überein.

Wenn in Ihren Debuginformationen Fehler angezeigt werden, Karte ähnlich wie:

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

Wechseln Sie zum Teams-Entwicklerportal. Suchen Sie ihre OAuth-Client- oder SSO-Clientregistrierung, und überprüfen Sie, ob die MCP-Server-URL in Ihrem Plug-In mit der registrierten Basis-URL übereinstimmt.

Die Verweis-ID im Plug-In-Manifest ist falsch oder fehlt.

Wenn in Ihren Debuginformationen Fehler angezeigt werden, Karte ähnlich wie:

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

Wechseln Sie zum Teams-Entwicklerportal. Suchen Sie nach ihrer OAuth-Client- oder SSO-Clientregistrierung, und überprüfen Sie, ob die ID in der Laufzeit auth.reference_id Ihres MCP-Servers mit der ID der Registrierung im Entwicklerportal übereinstimmt.

Organisationsrichtlinie schränkt den Zugriff ein

Wenn in Ihren Debuginformationen Fehler angezeigt werden, Karte ähnlich wie:

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

Wenden Sie sich an die Administratoren Ihrer organization, um den Zugriff für Ihre App zu überprüfen und zu aktivieren.

Die Schaltfläche "Anmelden" ist inaktiv oder zeigt einen allgemeinen Fehler an.

Wenn Ihre Anmeldeschaltfläche inaktiv oder deaktiviert ist oder wenn sie den allgemeinen Fehler "Anforderung kann nicht verarbeitet werden" angezeigt wird, kann diese Bedingung auf vorübergehende Authentifizierungs- oder Sitzungsprobleme hinweisen. Wiederholen Sie die Abfrage. Wenn das Problem weiterhin besteht, installieren Sie die App neu, oder wenden Sie sich an die Administratoren Ihres organization.

Anmeldepopup kann nicht geöffnet werden

Aktivieren Sie Popups für die Website in den Einstellungen Ihres Browsers, und versuchen Sie es erneut.

Fehler aufgrund falscher Anmeldeinformationen

Wenn im Anmeldepopup oder in der Chatantwort der Fehler "Falsche Anmeldeinformationen" angezeigt wird, stellen Sie sicher, dass Sie die richtigen Anmeldeinformationen eingeben. Wenn der Fehler weiterhin auftritt, stellen Sie sicher, dass der Benutzer über die erforderlichen Berechtigungen verfügt.

Anmelde-URL nicht gefunden

Deinstallieren Sie die App, installieren Sie sie erneut, und versuchen Sie dann erneut, sich anzumelden.

Interner Serverfehler während der Authentifizierung

Überprüfen Sie die Details im Authentifizierungs-Popup, und wenden Sie sich bei Berechtigungsproblemen an die Administratoren Ihres organization.

Wenn ein Zustimmungsdialogfeld angezeigt wird, in dem Berechtigungen oder geschäftliche Begründungen angefordert werden, überprüfen Sie die angeforderten Berechtigungen, und geben Sie ggf. eine geschäftliche Begründung an. Wenn Sie unsicher sind oder das Zustimmungsdialogfeld Berechtigungen anfordert, die die Administratoreinwilligung erfordern, wenden Sie sich an die Administratoren Ihres organization.

Verwandte Inhalte

  • Last updated on