Aggiungere app MCP agli agenti dichiarativi in Microsoft 365 Copilot

Suggerimento

Consigliato: Inizia con Work IQ Dev Tools per scenari di agenti dichiarativi e plug-in pro-code supportati. Vedere la guida introduttiva di WIQD. Le istruzioni basate su toolkit rimangono disponibili per i progetti e i flussi di lavoro esistenti che le richiedono. Controlla il supporto per le funzionalità e l'esperienza di destinazione prima di scegliere uno strumento: WIQD non si rivolge agli agenti del motore personalizzato.

Le app MCP sono widget interattivi dell'interfaccia utente che vengono eseguiti all'interno di Microsoft 365 Copilot, basati su server Model Context Protocol (MCP). Consentono agli agenti dichiarativi di andare oltre le risposte di testo e di offrire esperienze avanzate e fruibili direttamente nella chat di Copilot. È possibile aggiungere app MCP agli agenti dichiarativi aggiungendo un plug-in basato su server MCP i cui strumenti restituiscono un'interfaccia utente interattiva. Microsoft 365 Copilot supporta i widget dell'interfaccia utente creati utilizzando i metodi seguenti.

  • App MCP : un'estensione di MCP che consente ai server MCP di fornire interfacce utente interattive agli host.
  • OpenAI Apps SDK : strumenti per creare app ChatGPT basate sullo standard MCP Apps con funzionalità ChatGPT aggiuntive.

Per esempi di plug-in per server MCP, vedere Esempi di interfaccia utente interattiva basati su MCP per Microsoft 365 Copilot su GitHub.

Per informazioni dettagliate sulle funzionalità di SDK per app MCP o OpenAI app supportate, vedere Funzionalità delle app MCP supportate in Copilot.

Screenshot di un'app MCP che esegue il rendering di un widget delle attività di sprint inline in Microsoft 365 Copilot

Screenshot di un'app MCP che esegue il rendering di un widget delle attività Sprint in modalità a schermo intero in Microsoft 365 Copilot

Prerequisiti per le app MCP

Requisiti del server MCP per le app MCP

  • Autenticazione - Copilot supporta OAuth 2.1 e Microsoft Entra Single Sign-On (SSO). A scopo di sviluppo, Copilot supporta l'autenticazione anonima utilizzando l'opzione Nessuno in Agents Toolkit. Per altre informazioni sull'autenticazione, vedere Configurazione dell'autenticazione per i plug-in API negli agenti.
  • URL consentiti : sia il server MCP che il provider di identità devono consentire gli URL seguenti.
    • URL host widget per CORS - Copilot esegue il rendering dell'interfaccia utente del widget in un host specifico del server MCP con l'URL seguente: {hashed-mcp-domain}.widget-renderer.usercontent.microsoft.com, dove {hashed-mcp-domain} si trova l'hash SHA-256 del dominio del server MCP. È possibile utilizzare il generatore di URL host widget per generare l'URL host in base all'URL del server MCP.
    • URI di reindirizzamento OAuth 2.1:
      • https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect per Copilot
      • https://vscode.dev/redirect per Visual Studio Code per recuperare strumenti utilizzando Agents Toolkit
    • URI di reindirizzamento SSO di Microsoft Entra:
      • https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect per Copilot
      • Visual Studio Code attualmente non supporta SSO per il recupero di strumenti
  • Widget dell'interfaccia utente : implementare i widget dell'interfaccia utente in base ai requisiti di MCP Apps o OpenAI Apps SDK.

Procedure consigliate per le app MCP in Copilot

Progettazione dell'esperienza utente

Per ulteriori informazioni sulle procedure consigliate per la progettazione dell'esperienza utente, vedere Linee guida per l'esperienza utente per le app MCP negli agenti dichiarativi per Microsoft 365 Copilot.

Verificare la disponibilità dell'API

Non tutte le API sono disponibili su tutte le window.openai.* piattaforme o gli host. Le API non supportate sono undefined. Controlla sempre la disponibilità dell'API e fornisci un fallback se l'API non è disponibile.

Esempi

Questo semplice modello evita gli errori di runtime controllando prima di chiamare l'API.

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 questo esempio, il rendering di un pulsante per entrare in modalità a schermo intero viene eseguito solo se l'host supporta l'API requestDisplayMode .

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>
  );
}

In alternativa, il widget può verificare la disponibilità di tutte le API utilizzate all'avvio e abilitare o disabilitare le funzionalità di conseguenza.

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
}

Creare e trasferire localmente l'agente

La creazione di un agente dichiarativo da un server MCP, la configurazione dell'autenticazione e il trasferimento locale sono gli stessi indipendentemente dal fatto che il server restituisca o meno widget dell'interfaccia utente. Per la procedura dettagliata, vedere Creare un plug-in per un agente dichiarativo da un server MCP.

Tenere presenti le considerazioni sulle app MCP seguenti mentre si esegue la procedura dettagliata:

  • Il server MCP deve restituire i widget dell'interfaccia utente in base ai requisiti dell'SDK per le app MCP o per le app OpenAI. Vedere Requisiti server MCP per le app MCP.
  • Per impostazione predefinita, l'agente utilizza l'individuazione dinamica degli strumenti e risolve gli strumenti del server, inclusi gli strumenti che restituiscono i widget dell'interfaccia utente, in fase di esecuzione, in modo che non sia necessario aggiungere strumenti manualmente. Se invece aggiungi un set fisso di strumenti, assicurati di includere almeno uno strumento che restituisca un widget dell'interfaccia utente.
  • Se il server MCP è ancora in fase di sviluppo e non implementa l'autenticazione, selezionare Nessuno come tipo di autenticazione. Aggiungere l'autenticazione prima della distribuzione in produzione.

Testare l'agente

  1. Apri il browser e vai a https://m365.cloud.microsoft/chat.
  2. Seleziona il tuo agente nella barra laterale sinistra. Se non vedi il tuo agente, seleziona Tutti gli agenti.
  3. Chiedere all'agente di eseguire un'operazione che richiami il server MCP.
  4. Consentire all'agente di connettersi al server MCP quando richiesto.
  5. Verifica che l'agente esegua il rendering del widget dell'interfaccia utente.

Se il widget non viene visualizzato o non si comporta come previsto, vedi Risolvere i problemi relativi alle app MCP in Microsoft 365 Copilot.

Funzionalità delle app MCP supportate in Copilot

Microsoft 365 Copilot supporta le funzionalità seguenti.

Ponte di componenti

OpenAI Apps SDK Equivalente delle app MCP Supportato?
window.openai.toolInput app.ontoolinput ✅
window.openai.toolOutput app.ontoolresult ✅
window.openai.toolResponseMetadata app.ontoolresult → params._meta ✅
window.openai.widgetState — ✅
window.openai.setWidgetState(state) Non direttamente disponibile. Utilizzare meccanismi alternativi, tra cui 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 }) ✅ (Solo schermo intero)
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() ✅

Campi descrittori _meta strumento

OpenAI Apps SDK Equivalente delle app MCP Supportato?
_meta["openai/outputTemplate"] _meta.ui.resourceUri ✅
_meta["openai/widgetAccessible"] _meta.ui.visibility (stringa[]) ❌
_meta["openai/visibility"] _meta.ui.visibility (stringa[]) ✅
_meta["openai/toolInvocation/invoking"] — ❌
_meta["openai/toolInvocation/invoked"] — ❌
_meta["openai/fileParams"] — ❌
_meta["securitySchemes"] — ❌

Annotazioni dei descrittori dello strumento

OpenAI Apps SDK Equivalente delle app MCP Supportato?
readOnlyHint readOnlyHint ✅
destructiveHint destructiveHint ❌
openWorldHint openWorldHint ❌
idempotentHint idempotentHint ❌

Campi _meta risorse componente

OpenAI Apps SDK Equivalente delle app MCP Supportato?
_meta["openai/widgetDescription"] — ❌
_meta["openai/widgetPrefersBorder"] _meta.ui.prefersBorder ❌
_meta["openai/widgetCSP"] _meta.ui.csp ✅
_meta["openai/widgetDomain"] _meta.ui.domain ❌
— _meta.ui.permissions ❌

Proprietà nell'oggetto CSP

OpenAI Apps SDK Equivalente delle app MCP Supportato?
connect_domains connectDomains ✅
resource_domains resourceDomains ✅
frame_domains frameDomains ❌
redirect_domains — ❌
— baseUriDomains ❌

Campi _meta dei risultati dello strumento fornito dall'host

OpenAI Apps SDK Equivalente delle app MCP Supportato?
_meta["openai/widgetSessionId"] — ❌

Campi _meta forniti dal client

OpenAI Apps SDK Equivalente delle app MCP Supportato?
_meta["openai/locale"] _meta["openai/locale"] ✅
_meta["openai/userAgent"] _meta["openai/userAgent"] ✅
_meta["openai/userLocation"] _meta["openai/userLocation"] ✅
_meta["openai/subject"] — ❌

Domande frequenti sulle app MCP in Copilot

Cosa sono le app MCP?

Le app MCP sono widget interattivi dell'interfaccia utente forniti da server MCP che eseguono il rendering direttamente all'interno di Microsoft 365 Copilot. Estendono gli agenti dichiarativi oltre le risposte di solo testo, consentendo esperienze avanzate come visualizzazioni dei dati, moduli e interfacce di gestione delle attività.

Qual è la differenza tra MCP Apps e OpenAI Apps SDK?

MCP Apps è un'estensione aperta dello standard MCP che consente ai server MCP di fornire interfacce utente interattive a qualsiasi host compatibile. L'SDK di OpenAI Apps si basa sullo standard MCP Apps e aggiunge funzionalità extra specifiche di ChatGPT. Microsoft 365 Copilot supporta entrambi, anche se non tutte le funzionalità sono disponibili. Per informazioni dettagliate, vedere Funzionalità delle app MCP supportate in Copilot .

È possibile usare app MCP senza autenticazione durante lo sviluppo?

Sì. L'autenticazione anonima è supportata per finalità di sviluppo. Tuttavia, è necessario aggiungere l'autenticazione prima della distribuzione in produzione. OAuth 2.1 e Microsoft Entra Single Sign-On (SSO) sono i metodi di autenticazione supportati. Per informazioni dettagliate, vedi Configurazione dell'autenticazione per i plug-in API negli agenti.