Risolvere i problemi relativi alle app MCP in Microsoft 365 Copilot

Questa guida fornisce consigli per la risoluzione dei problemi comuni che potrebbero verificarsi durante lo sviluppo di un'app Model Context Protocol (MCP) da integrare con un agente dichiarativo all'interno di Microsoft 365 Copilot.

Abilitare la modalità sviluppatore

L'abilitazione della modalità sviluppatore mostra i log e gli errori nelle risposte degli agenti. Queste informazioni sono essenziali per il debug. Per abilitare la modalità sviluppatore, digita il comando seguente in Microsoft Copilot.

-developer on

Gli strumenti MCP disponibili per l'agente vengono visualizzati nella sezione Azioni della scheda informazioni di debug. Per informazioni dettagliate sulla scheda informazioni di debug, vedere Usare la modalità sviluppatore in Microsoft 365 Copilot per testare ed eseguire il debug degli agenti.

Problemi di individuazione e ingresso

Nessun utensile elencato

Se la sezione Azioni della scheda informazioni di debug non elenca alcuno strumento MCP, controllare quanto segue:

  • Verifica che il server MCP sia in esecuzione e che ti connetti all'endpoint MCP corretto nel manifesto del plug-in.
  • Verificare che l'autenticazione abbia esito positivo. Molti server MCP non restituiscono strumenti finché l'utente non accede, quindi un accesso non riuscito o ignorato può comportare un elenco di strumenti vuoto.

Individuazione dinamica degli utensili

Se l'agente utilizza l'individuazione dinamica degli strumenti (impostazione predefinita), gli strumenti vengono risolti dal server in fase di esecuzione. Verificare che:

  • Il RemoteMCPServer runtime viene impostato run_for_functions su ["*"] e la matrice di primo livello functions è vuota.
  • Il metodo del tools/list server restituisce gli strumenti. È possibile esaminare la risposta usando uno strumento come MCP Inspector.
  • Uno strumento appena individuato o modificato non viene trattenuto dalla convalida runtime. Verificare le informazioni di debug per verificare la presenza di errori di convalida.
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp"
    },
    "run_for_functions": [
      "*"
    ]
  }
]

Strumenti bloccati

Se è stato aggiunto un set fisso di strumenti, verificare che il runtimes runtime del server MCP specificato nella proprietà del manifesto del plug-in:

  • Include gli strumenti previsti nella proprietà di primo livello functions .
  • Fa riferimento agli strumenti nella mcp_tool_description proprietà:
    • Riferimento a un file JSON che contiene le descrizioni degli file strumenti nella proprietà OR
    • Elencare le descrizioni degli strumenti in linea nella tools proprietà
  • Include i nomi degli strumenti nella run_for_functions proprietà.
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp",
      "mcp_tool_description": {
        "file": "mcp-tools.json"
      }
    },
    "run_for_functions": [
      "get_widget",
      "create_widget"
    ]
  }
]

Strumenti che non si attivano dalla chat di Copilot

  • Rivedi le descrizioni degli strumenti e dei parametri per assicurarti che forniscano un contesto sufficiente. Considera di riscriverli usando "Usa questa funzione/parametro quando..." frase.
  • Mantenere le descrizioni al di sotto di 1.024 caratteri. Il testo che supera i 1.024 caratteri viene ignorato.
  • Assicurarsi che la visibilità dell'utensile sia impostata correttamente.
    • Per le app MCP, _meta.ui.visibility include model.
    • Per le app OpenAI SDK, meta["openai/visibility"] è impostato su public.

Viene selezionato lo strumento sbagliato

  • Evita gli strumenti con nomi simili o descrizioni sovrapposte.
  • Aggiungi chiari elementi di differenziazione nelle descrizioni che spiegano quando ogni strumento deve essere usato.

Problemi con i widget

Il widget non esegue il rendering

Se viene chiamato lo strumento MCP corretto ma il widget dell'interfaccia utente non viene visualizzato nella risposta, è probabile che il server MCP restituisca solo contenuto strutturato senza componenti dell'interfaccia utente. Assicurati che l'associazione dell'interfaccia utente sia configurata correttamente.

  • Per le app MCP, la definizione dello strumento include _meta.ui.resourceUri l'impostazione su una risorsa HTML registrata con tipo text/html;profile=mcp-appMIME.
  • Per le app OpenAI SDK, la definizione dello strumento include _meta["openai/outputTemplate"] il set su una risorsa HTML registrata con tipo text/html+skybridgeMIME.

Il widget non si carica

  • Apri gli strumenti di sviluppo del browser e verifica la presenza di violazioni dei criteri di sicurezza del contenuto (CSP) nella console. Assicurati che le richieste dall'URL host del widget siano consentite nell'elenco. Per altre informazioni, vedere Requisiti del server MCP per le app MCP.
  • Verifica che il widget compili tutte le dipendenze HTML e JavaScript in un unico file senza risorse esterne non risolte.

Il widget si carica senza dati

  • Verificare la struttura delle risposte dello strumento.
    • content Deve contenere solo i dati (modello).
    • structuredContent Deve contenere sia i dati che il widget.
    • _meta Deve contenere solo il widget.
  • Assicurati di includere structuredContent i _meta dati necessari.

Il widget ha una doppia barra di scorrimento

Il contenitore host Copilot ha già uno scorrimento con altezza massima. Disabilitare lo scorrimento interno nel widget impostando overflow: hidden gli stili del contenitore.

I tag <a> di ancoraggio non funzionano per i collegamenti esterni in Copilot. Utilizza invece le API della piattaforma appropriate.

  • Per le app MCP, usa app.openLink.
  • Per le app OpenAI SDK, usa window.openai.openExternal.

La modalità a schermo intero non funziona in alcuni host Copilot

La visualizzazione a schermo intero non è supportata in tutti gli host Copilot. Come procedura consigliata, verifica sempre le funzionalità host e visualizza in modo condizionale gli elementi dell'interfaccia utente, ad esempio un pulsante a schermo intero. Per altre informazioni, vedi Verificare la disponibilità dell'API.

Problemi di risposta

Problemi di scadenza dei risultati dell'utensile

Assicurarsi che le risposte dello strumento inviate content o structuredContent non siano eccessivamente grandi. Se il widget richiede metadati complessi che non sono utili per il modello, come URL avatar o dettagli specifici dell'interfaccia utente, includere i dati _meta completi e fornire un riepilogo conciso in content. Questo approccio garantisce che il modello conservi le informazioni chiave, supportando al contempo un'esperienza multigiro efficace.

Dati duplicati nel widget e nel riepilogo di testo

Risolvi il problema utilizzando una delle opzioni seguenti:

  • Ottimizza la separazione dei dati: utilizza _meta per dati specifici del widget e content per riepiloghi visibili al modello.
  • Formattazione steer: usa le istruzioni nel manifesto dell'agente dichiarativo per guidare la struttura e la presentazione delle risposte.

Problemi di autenticazione

Per problemi di autenticazione, ad esempio errori di accesso, errori di token, richieste di consenso e mancate corrispondenze della configurazione di autenticazione, vedere Risolvere i problemi di autenticazione dei plug-in MCP e API.