Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Un plug-in di Microsoft 365 Copilot connette le esperienze Microsoft supportate agli strumenti forniti da un server MCP (Model Context Protocol) remoto. Il pacchetto plugin contiene la configurazione della connessione e il server funziona separatamente.
Usa Work IQ Dev Tools (WIQD) per creare, convalidare e creare pacchetti del plug-in. Inizia con : Crea un plug-in con gli strumenti di sviluppo di Work IQ.
Le sezioni seguenti illustrano la configurazione sottostante per gli sviluppatori che devono modificare manualmente il manifesto. Registrare il server MCP remoto del plug-in nell'array agentConnectors del manifesto dell'app Microsoft 365. Questo identificatore di schema rimane agentConnectors anche se il pacchetto installabile è chiamato plug-in.
Importante
Questa configurazione usa il manifesto dell'app Microsoft 365, non il manifesto del plug-in MCP usato per le azioni dell'agente dichiarativo. È inoltre separato dalla route di registrazione CLI di Agent 365. Per queste alternative, vedere Creare o riutilizzare i server MCP. Il supporto per MCP da solo non stabilisce il supporto per questo modello di registrazione.
Prerequisiti
Prima di iniziare, assicurati di avere:
- Un tenant di test e un'esperienza Microsoft di destinazione che supporta i plug-in configurati tramite
agentConnectors. - Un server MCP funzionante con un endpoint HTTPS accessibile pubblicamente, TLS 1.2 o versione successiva e un trasporto supportato dall'esperienza di destinazione.
- Pacchetto di app di Microsoft 365 con una versione manifesto supportata dall'esperienza di destinazione e dal tipo di autorizzazione scelto.
- Una configurazione di autorizzazione registrata per il server, ad esempio una configurazione OAuth o una configurazione di chiave API, a meno che il server non consenta l'accesso anonimo.
Per i requisiti del server WIQD e il requisito della descrizione degli strumenti Copilot Cowork, vedi Strumenti di sviluppo di Work IQ.
Aggiungere il server MCP al manifesto dell'app
Dichiara il server MCP nella matrice agentConnectors al livello radice del manifesto dell'app.
- Aprire il manifesto dell'app nel pacchetto dell'app Microsoft 365.
- Individuare o creare la matrice a livello
agentConnectorsdi radice. - Aggiungere una voce con un , a
displayName, adescriptione a univocoidtoolSourceche identifichi il server MCP remoto.
Il codice JSON seguente è un frammento da unire al manifesto dell'app esistente, non un manifesto dell'app completo:
{
"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.30/MicrosoftTeams.schema.json",
"manifestVersion": "1.30",
"agentConnectors": [
{
"id": "my-mcp-server",
"displayName": "My Automation Server",
"description": "Provides workflow automation and task management tools.",
"toolSource": {
"remoteMcpServer": {
"mcpServerUrl": "https://mcp.example.com/mcp",
"authorization": {
"type": "OAuthPluginVault",
"referenceId": "my-oauth-config"
},
"mcpToolDescription": {
"file": "toolDescription.json"
}
}
}
}
]
}
Sostituire l'endpoint e il riferimento di autorizzazione con i valori del server. Ogni voce deve essere univoca id all'interno di agentConnectors. Mantenere le altre proprietà del manifesto dell'app richieste nel file esistente.
Configurare l'endpoint server
Imposta toolSource.remoteMcpServer.mcpServerUrl sull'endpoint HTTPS. Verificare che il server sia raggiungibile dall'esperienza di destinazione e risponda all'inizializzazione MCP e alle successive richieste di protocollo.
Configurare l'autenticazione
Impostato authorization all'interno di agentConnectors[].toolSource.remoteMcpServer. Nella tabella seguente sono elencati i tipi di autorizzazione e la relativa configurazione. Per informazioni dettagliate sullo schema, vedere lo schema di autorizzazione.
| Tipo di autorizzazione | Configurazione |
|---|---|
None |
Non è necessaria l'autenticazione. Utilizzare solo quando il server consente l'accesso anonimo. |
OAuthPluginVault |
Configurazione OAuth archiviata nel vault di Microsoft e a cui fa riferimento l'ID. |
ApiKeyPluginVault |
Configurazione della chiave API archiviata in un insieme di credenziali e a cui fa riferimento l'ID. |
DynamicClientRegistration |
Configurazione della registrazione client OAuth dinamico a cui fa riferimento l'ID. |
AzureKeyVault |
Configurazione di Azure Key Vault a cui fa riferimento l'ID. Richiede il supporto dell'host. |
ConnectionVault (anteprima per sviluppatori) |
Configurazione della connessione a cui fa riferimento l'ID. |
Un valore di schema non garantisce il supporto nell'esperienza di destinazione. Controlla i requisiti di autenticazione prima di scegliere un metodo.
Identifica referenceId una configurazione acquisita separatamente dal manifesto. Non inserire chiavi API, token di accesso, segreti client o valori segreti in questo campo o in altre parti del manifesto dell'app.
Usare l'autenticazione OAuth
Per i token OAuth 2.0 archiviati nell'insieme di credenziali di Microsoft, utilizza l'oggetto seguente authorization :
{
"type": "OAuthPluginVault",
"referenceId": "my-oauth-config"
}
Registrare la configurazione OAuth nel portale per sviluppatori e utilizzare l'ID di configurazione restituito come referenceId. Per informazioni dettagliate, vedere Configurare OAuth nel portale per sviluppatori.
Aggiungere l'URL di callback seguente agli URI di reindirizzamento consentiti nella registrazione del provider OAuth:
https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect
Usa l'autenticazione con chiave API
Per una chiave API archiviata in un insieme di credenziali, utilizza l'oggetto seguente authorization :
{
"type": "ApiKeyPluginVault",
"referenceId": "my-apikey"
}
Registrare la chiave nel portale per sviluppatori e sostituirla my-apikey con l'ID di registrazione restituito. Per informazioni dettagliate, consulta Autenticazione con chiave API.
Utilizzare la registrazione client dinamica
La registrazione dinamica del client consente all'host di registrarsi come client OAuth nel server MCP utilizzando RFC 7591. Entrambi devono supportare il flusso di registrazione. Microsoft Entra ID non fornisce un endpoint di registrazione RFC 7591; utilizzare la registrazione OAuth statica per un server protetto da Entra.
Usare l'oggetto seguente authorization :
{
"type": "DynamicClientRegistration",
"referenceId": "my-dcr-config"
}
Registrare la configurazione nel portale per sviluppatori e sostituirla my-dcr-config con il relativo ID di riferimento. La configurazione fornisce i valori di autorizzazione usati dall'host durante la negoziazione delle credenziali client.
Il server deve:
- Esporre un endpoint di registrazione client RFC 7591.
- Restituisce le informazioni di registrazione client richieste dal flusso OAuth dell'host.
- Supportare l'aggiornamento del token, se necessario, per sessioni di lunga durata.
Usare l'autenticazione di Azure Key Vault
AzureKeyVault è incluso negli schemi manifesto dell'app 1.29 e 1.30. Usalo solo quando l'esperienza di destinazione documenta un'integrazione di Azure Key Vault e un processo per l'acquisizione del riferimento alla configurazione.
Usare l'oggetto seguente authorization :
{
"type": "AzureKeyVault",
"referenceId": "my-keyvault-config"
}
Seguire i requisiti di archiviazione e accesso delle credenziali dell'integrazione e sostituire my-keyvault-config con il riferimento restituito. La dichiarazione manifesta da sola non concede l'accesso ai segreti.
Usare l'autenticazione dell'insieme di credenziali della connessione
Nota
L'autenticazione di Connection Vault è disponibile nell'anteprima per sviluppatori. Usa lo schema del manifesto dell'app di anteprima per sviluppatori per configurarlo ConnectionVault; non è disponibile negli schemi manifesto dell'app generalmente disponibili.
Per un'integrazione di connection-vault supportata, utilizzare l'oggetto seguente authorization :
{
"type": "ConnectionVault",
"referenceId": "shared_example"
}
Sostituire shared_example con il riferimento di connessione fornito dall'integrazione di destinazione.
Non usare l'autenticazione
Se il server consente l'accesso anonimo, impostarlo authorization.typeNone o ometterlo authorization quando l'host lo consente.
Preferisci l'accesso autenticato per gli scenari di produzione e aziendali e OAuth su chiavi API, se supportato.
Definire l'individuazione degli utensili
Usa definizioni di strumenti in pacchetto quando il set di strumenti è fisso o l'individuazione dinamica quando la versione del manifesto dell'app e l'host di destinazione lo supportano.
Usare definizioni di utensili statici
Includere un file di descrizione dello strumento nel pacchetto dell'app e farvi riferimento all'interno di remoteMcpServer. Il percorso è relativo al pacchetto dell'app. Usa le definizioni dello strumento dal risultato del tools/list server, inclusi il nome, la descrizione e lo schema di input di ogni strumento. Ad esempio, un file minimo toolDescription.json può contenere:
{
"mcpToolDescription": {
"file": "toolDescription.json"
}
}
{
"tools": [
{
"name": "get_task",
"description": "Gets a task by its identifier.",
"inputSchema": {
"type": "object",
"properties": {
"taskId": {
"type": "string",
"description": "The identifier of the task."
}
},
"required": [
"taskId"
]
}
}
]
}
Mantenere le definizioni dei pacchetti coerenti con il server.
Usare il rilevamento dinamico degli utensili
L'individuazione dinamica consente a un host di recuperare l'elenco di strumenti in fase di esecuzione tools/list anziché basarsi sulle definizioni in pacchetto.
Il manifesto dell'app versione 1.29 o successiva consente di omettere mcpToolDescription. Le versioni precedenti richiedono il file.
Copilot Cowork richiede ancora un file di descrizione dello strumento, anche con la versione 1.29 o successiva. Con WIQD, forniscilo tramite --tool-description; vedi Work IQ Dev Tools.
Per un'esperienza di destinazione che supporta l'individuazione dinamica, omettere mcpToolDescription in modo che possa recuperare le definizioni tramite tools/list. Restituisce i nomi degli strumenti, le descrizioni e gli schemi di input e verifica come vengono aggiornate le modifiche al set di strumenti.
Convalidare e testare il plug-in
Convalidare il pacchetto prima della distribuzione e quindi testarlo nell'esperienza di destinazione:
- Convalidare il manifesto dell'app completo in base allo schema dichiarato e usare la convalida del pacchetto dell'app nel portale per sviluppatori.
- Verificare che l'endpoint risponda all'inizializzazione MCP e che il file in pacchetto o
tools/listfornisca definizioni di strumenti valide. - Distribuire il pacchetto nel tenant di test tramite il processo supportato dell'esperienza di destinazione. Completare la configurazione di accesso o approvazione dell'amministratore richiesta. La distribuzione non sostituisce l'accesso dell'utente, il consenso o le autorizzazioni del servizio di origine.
- Eseguire prompt di test per le operazioni esposte dal server, ad esempio "Cerca problemi aperti assegnati all'utente" o, per un server con strumenti di scrittura, "Aggiornare lo stato del ticket numero 123".
- Verifica che gli strumenti previsti siano disponibili, che le richieste di consenso vengano visualizzate quando necessario e che le chiamate agli strumenti restituiscano i risultati previsti. Testare l'aggiornamento del token OAuth, se applicabile.
- Verificare gli errori per input non validi, servizi non disponibili, errori di autorizzazione e timeout, incluso il comportamento di ripetizione dei tentativi.
- Eseguire il test tra tenant se lo scenario richiede il supporto multitenant.
Risolvere i problemi comuni
| Sintomo | Assegno |
|---|---|
| Impossibile connettersi al server | Accessibilità degli endpoint, HTTPS, supporto del trasporto, impostazioni del firewall e inizializzazione MCP. |
| Gli strumenti non vengono visualizzati | Percorso del file in pacchetto e definizioni valide o supporto per l'individuazione dinamica con mcpToolDescription omesso e un file .tools/list |
| L'autenticazione non riesce | Registrate referenceId, validità delle credenziali, autorizzazioni, consenso e intestazioni di autorizzazione in uscita. |
| Le chiamate allo strumento hanno esito negativo o scadono | Registri del server, convalida dell'input, formato della risposta MCP, concorrenza, timeout e tentativi. |
Passaggi successivi
Quando l'integrazione è pronta, crea un pacchetto del plug-in e segui un metodo di pubblicazione o condivisione supportato.