Hinzufügen von MCP-Apps zu deklarativen Agents in Microsoft 365 Copilot

MCP-Apps sind interaktive UI-Widgets, die innerhalb von Microsoft 365 Copilot ausgeführt werden und von MCP-Servern (Model Context Protocol) unterstützt werden. Sie ermöglichen es deklarativen Agents, über Textantworten hinauszugehen und reichhaltige, umsetzbare Erfahrungen direkt im Copilot-Chat zu liefern. Sie können Ihren deklarativen Agents MCP-Apps hinzufügen, indem Sie ein serverbasiertes MCP-Plug-In hinzufügen, dessen Tools die interaktive Benutzeroberfläche zurückgeben. Microsoft 365 Copilot unterstützt UI-Widgets, die mit den folgenden Methoden erstellt wurden.

  • MCP-Apps – eine Erweiterung von MCP, die es MCP-Servern ermöglicht, Hosts interaktive Benutzeroberflächen bereitzustellen.
  • OpenAI Apps SDK – Tools zum Erstellen von ChatGPT-Apps basierend auf dem MCP Apps-Standard mit zusätzlicher ChatGPT-Funktionalität.

Beispiele für MCP-Server-Plug-Ins finden Sie unter MCP-basierte interaktive UI-Beispiele für Microsoft 365 Copilot auf GitHub.

Weitere Informationen dazu, welche MCP-Apps oder OpenAI Apps SDK-Funktionen unterstützt werden, finden Sie unter Unterstützte MCP-Apps-Funktionen in Copilot.

Screenshot einer MCP-App, die ein Inline-Sprintaufgaben-Widget in Microsoft 365 Copilot rendert

Screenshot einer MCP-App, die ein Sprintaufgaben-Widget im Vollbildmodus in Microsoft 365 Copilot rendert

Voraussetzungen für MCP-Apps

MCP-Serveranforderungen für MCP-Apps

  • Authentifizierung – Copilot unterstützt OAuth 2.1 und Microsoft Entra Single Sign-On (SSO). Für Entwicklungszwecke unterstützt Copilot die anonyme Authentifizierung mithilfe der Option "Keine" im Agents-Toolkit. Weitere Informationen zur Authentifizierung finden Sie unter Konfigurieren der Authentifizierung für API-Plug-Ins in Agents.
  • Zulässige URLs : Sowohl Ihr MCP-Server als auch Ihr Identitätsanbieter müssen die folgenden URLs zulassen.
    • Widgethost-URL für CORS – Copilot rendert die Widgetbenutzeroberfläche unter einem MCP-serverspezifischen Host mit der folgenden URL: {hashed-mcp-domain}.widget-renderer.usercontent.microsoft.com, wobei {hashed-mcp-domain} der SHA-256-Hash der Domäne Ihres MCP-Servers ist. Sie können den Widget-Host-URL-Generator verwenden, um die Host-URL basierend auf Ihrer MCP-Server-URL zu generieren.
    • OAuth 2.1-Umleitungs-URIs:
      • https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect for Copilot
      • https://vscode.dev/redirect Visual Studio Code zum Abrufen von Tools mithilfe des Agents-Toolkits
    • Umleitungs-URIs für Microsoft Entra SSO:
      • https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect for Copilot
      • Visual Studio Code unterstützt derzeit kein SSO zum Abrufen von Tools
  • UI-Widgets : Implementieren Sie UI-Widgets gemäß den Anforderungen des MCP Apps oder OpenAI Apps SDK.

Bewährte Methoden für MCP-Apps in Copilot

Gestaltung der Benutzererfahrung

Weitere Informationen zu bewährten Methoden für den UX-Entwurf finden Sie unter Richtlinien zur Benutzererfahrung für MCP-Apps in deklarativen Agents für Microsoft 365 Copilot.

API-Verfügbarkeit überprüfen

Nicht alle window.openai.* APIs sind auf jeder Plattform oder jedem Host verfügbar. Nicht unterstützte APIs sind undefined. Überprüfen Sie immer die API-Verfügbarkeit, und bieten Sie eine Ausweichaktion an, wenn die API nicht verfügbar ist.

Beispiele

Dieses einfache Muster vermeidet Laufzeitfehler, indem es vor dem Aufruf der API überprüft.

if (window.openai.callTool) {
  const result = await window.openai.callTool({ name: 'myTool', params: {} });
} else {
  // Handle unsupported case — show fallback UI, skip the feature, etc.
}

In diesem Beispiel wird eine Schaltfläche zum Aktivieren des Vollbildmodus nur gerendert, wenn der Host die requestDisplayMode API unterstützt.

function FullScreenButton() {
  // Don't render the button if the host doesn't support it
  if (!window.openai.requestDisplayMode) {
    return null;
  }

  return (
    <button onClick={() => window.openai.requestDisplayMode({ mode: 'fullscreen' })}>
      Enter Fullscreen
    </button>
  );
}

Alternativ kann Ihr Widget beim Start die Verfügbarkeit aller APIs überprüfen, die es verwendet, und Funktionen entsprechend aktivieren oder deaktivieren.

interface PlatformCapabilities {
  canCallTools: boolean;
  canChangeDisplayMode: boolean;
  canSendMessages: boolean;
}

function detectCapabilities(): PlatformCapabilities {
  return {
    canCallTools: !!window.openai.callTool,
    canChangeDisplayMode: !!window.openai.requestDisplayMode,
    canSendMessages: !!window.openai.sendMessage,
  };
}

// Use at widget startup
const capabilities = detectCapabilities();

if (!capabilities.canCallTools) {
  // Show a reduced-functionality experience
}

Erstellen und Querladen des Agents

Das Erstellen eines deklarativen Agenten von einem MCP-Server, das Konfigurieren der Authentifizierung und das Querladen sind identisch, unabhängig davon, ob der Server UI-Widgets zurückgibt oder nicht. Die vollständige exemplarische Vorgehensweise finden Sie unter Erstellen eines Plug-Ins für einen deklarativen Agent von einem MCP-Server.

Berücksichtigen Sie beim Befolgen dieser exemplarischen Vorgehensweise die folgenden Überlegungen zu MCP-Apps:

  • Ihr MCP-Server muss UI-Widgets gemäß den MCP Apps- oder OpenAI Apps SDK-Anforderungen zurückgeben. Weitere Informationen finden Sie unter MCP-Serveranforderungen für MCP-Apps.
  • Standardmäßig verwendet der Agent die dynamische Toolermittlung und löst die Tools Ihres Servers – einschließlich Tools, die UI-Widgets zurückgeben – zur Laufzeit auf, sodass Sie Tools nicht manuell hinzufügen müssen. Wenn Sie stattdessen einen festen Satz von Tools anheften, stellen Sie sicher, dass Sie mindestens ein Tool einschließen, das ein UI-Widget zurückgibt.
  • Wenn sich Ihr MCP-Server noch in der Entwicklung befindet und keine Authentifizierung implementiert, wählen Sie Keine als Authentifizierungstyp aus. Fügen Sie vor der Bereitstellung in der Produktion eine Authentifizierung hinzu.

Testen des Agents

  1. Öffnen Sie Ihren Browser, und navigieren Sie zu https://m365.cloud.microsoft/chat.
  2. Wählen Sie in der linken Randleiste Ihren Agent aus. Wenn Ihr Agent nicht angezeigt wird, wählen Sie Alle Agents aus.
  3. Bitten Sie den Agent, etwas zu tun, das Ihren MCP-Server aufruft.
  4. Erlauben Sie dem Agenten, eine Verbindung mit dem MCP-Server herzustellen, wenn Sie dazu aufgefordert werden.
  5. Vergewissern Sie sich, dass der Agent das UI-Widget rendert.

Wenn das Widget nicht angezeigt wird oder sich nicht wie erwartet verhält, finden Sie weitere Informationen unter Problembehandlung für MCP-Apps in Microsoft 365 Copilot.

Unterstützte MCP Apps-Funktionen in Copilot

Microsoft 365 Copilot unterstützt die folgenden Funktionen.

Komponentenbrücke

OpenAI Apps SDK MCP Apps-Äquivalent Unterstützt?
window.openai.toolInput app.ontoolinput ✅
window.openai.toolOutput app.ontoolresult ✅
window.openai.toolResponseMetadata app.ontoolresult → params._meta ✅
window.openai.widgetState — ✅
window.openai.setWidgetState(state) Nicht direkt verfügbar. Verwenden Sie alternative Mechanismen, einschließlich app.updateModelContext() ✅
window.openai.callTool(name, args) app.callServerTool({ name, arguments }) ✅
window.openai.sendFollowUpMessage({ prompt }) app.sendMessage({ ... }) ✅
window.openai.uploadFile(file) — ❌
window.openai.getFileDownloadUrl({ fileId }) — ❌
window.openai.requestDisplayMode(...) app.requestDisplayMode({ mode }) ✅ (nur Vollbild)
window.openai.requestModal(...) — ❌
window.openai.notifyIntrinsicHeight(...) app.sendSizeChanged({ width, height }) ✅
window.openai.openExternal({ href }) app.openLink({ url }) ✅
window.openai.setOpenInAppUrl({ href }) — ✅
window.openai.theme app.getHostContext()?.theme ✅
window.openai.displayMode app.getHostContext()?.displayMode ✅
window.openai.maxHeight app.getHostContext()?.viewport?.maxHeight ✅
window.openai.safeArea app.getHostContext()?.safeAreaInsets ✅
window.openai.view — ✅
window.openai.userAgent app.getHostContext()?.userAgent ✅
window.openai.locale app.getHostContext()?.locale ✅
— app.ontoolinputpartial ❌
— app.ontoolcancelled ❌
— app.getHostContext()?.availableDisplayModes ❌
— app.getHostContext()?.toolInfo ❌
— app.onhostcontextchanged ❌
— app.onteardown ❌
— app.sendLog({ level, data }) ❌
— app.getHostVersion() ❌
— app.getHostCapabilities() ✅

Felder _meta Tooldeskriptor

OpenAI Apps SDK MCP Apps-Äquivalent Unterstützt?
_meta["openai/outputTemplate"] _meta.ui.resourceUri ✅
_meta["openai/widgetAccessible"] _meta.ui.visibility (Zeichenfolge[]) ❌
_meta["openai/visibility"] _meta.ui.visibility (Zeichenfolge[]) ✅
_meta["openai/toolInvocation/invoking"] — ❌
_meta["openai/toolInvocation/invoked"] — ❌
_meta["openai/fileParams"] — ❌
_meta["securitySchemes"] — ❌

Anmerkungen zum Tooldeskriptor

OpenAI Apps SDK MCP Apps-Äquivalent Unterstützt?
readOnlyHint readOnlyHint ✅
destructiveHint destructiveHint ❌
openWorldHint openWorldHint ❌
idempotentHint idempotentHint ❌

Komponentenressource _meta -felder

OpenAI Apps SDK MCP Apps-Äquivalent Unterstützt?
_meta["openai/widgetDescription"] — ❌
_meta["openai/widgetPrefersBorder"] _meta.ui.prefersBorder ❌
_meta["openai/widgetCSP"] _meta.ui.csp ✅
_meta["openai/widgetDomain"] _meta.ui.domain ❌
— _meta.ui.permissions ❌

Eigenschaften im CSP-Objekt

OpenAI Apps SDK MCP Apps-Äquivalent Unterstützt?
connect_domains connectDomains ✅
resource_domains resourceDomains ✅
frame_domains frameDomains ❌
redirect_domains — ❌
— baseUriDomains ❌

Vom Host bereitgestelltes Toolergebnis _meta Felder

OpenAI Apps SDK MCP Apps-Äquivalent Unterstützt?
_meta["openai/widgetSessionId"] — ❌

Vom Client bereitgestellte _meta Felder

OpenAI Apps SDK MCP Apps-Äquivalent Unterstützt?
_meta["openai/locale"] _meta["openai/locale"] ✅
_meta["openai/userAgent"] _meta["openai/userAgent"] ✅
_meta["openai/userLocation"] _meta["openai/userLocation"] ✅
_meta["openai/subject"] — ❌

Häufig gestellte Fragen zu MCP-Apps in Copilot

Was sind MCP-Apps?

MCP-Apps sind interaktive UI-Widgets, die von MCP-Servern bereitgestellt und direkt in Microsoft 365 Copilot gerendert werden. Sie erweitern deklarative Agenten über reine Textantworten hinaus und ermöglichen umfangreiche Funktionen wie Datenvisualisierungen, Formulare und Aufgabenverwaltungsoberflächen.

Was ist der Unterschied zwischen MCP Apps und OpenAI Apps SDK?

MCP-Apps ist eine offene Erweiterung des MCP-Standards, die es MCP-Servern ermöglicht, interaktive Benutzeroberflächen für jeden kompatiblen Host bereitzustellen. Das OpenAI Apps SDK baut auf dem MCP Apps-Standard auf und fügt zusätzliche Funktionen hinzu, die für ChatGPT spezifisch sind. Microsoft 365 Copilot unterstützt beides, obwohl nicht alle Funktionen verfügbar sind. Weitere Informationen finden Sie unter Unterstützte MCP-Apps-Funktionen in Copilot .

Kann ich MCP-Apps während der Entwicklung ohne Authentifizierung verwenden?

Ja. Die anonyme Authentifizierung wird zu Entwicklungszwecken unterstützt. Sie müssen jedoch eine Authentifizierung hinzufügen, bevor Sie es in der Produktion bereitstellen. OAuth 2.1 und Microsoft Entra Single Sign-On (SSO) sind die unterstützten Authentifizierungsmethoden. Weitere Informationen finden Sie unter Konfigurieren der Authentifizierung für API-Plug-Ins in Agents.

Verwandte Inhalte

  • Last updated on