Usa il tuo server MCP (BYO)

Utilizzando la funzione server MCP Bring Your Own (BYO), la tua organizzazione può registrare i propri server remoti Model Context Protocol (MCP) con Microsoft Agent 365 per una governance centralizzata e osservabilità.

Important

  • Questa funzionalità è in versione di anteprima.
  • Le funzionalità di anteprima non sono destinate ad essere utilizzate per la produzione e sono soggette a restrizioni. Queste funzionalità sono soggette a condizioni per l'utilizzo supplementari e sono disponibili prima di una versione ufficiale in modo che i clienti possano ottenere l'accesso in anteprima e fornire feedback.

Le grandi aziende spesso creano e gestiscono server MCP interni per supportare i propri agenti in vari flussi di lavoro aziendali. Questi server vengono in genere eseguiti al di fuori di qualsiasi limite di governance dell'organizzazione, senza visibilità amministrativa sugli strumenti esposti, nessuna imposizione dei criteri sul modo in cui vengono richiamati e nessuna telemetria di utilizzo per i team di sicurezza e conformità. Il server BYO MCP risolve questo problema instradando i server registrati attraverso l'Agent 365 Tooling Gateway, offrendo agli amministratori IT il controllo tramite l'interfaccia di amministrazione di Microsoft 365 e ai team di sicurezza i dati di osservabilità di cui hanno bisogno.

Note

Le superfici client supportate durante l'anteprima sono Copilot Studio, Visual Studio Code, Claude Code e GitHub Copilot CLI. Azure AI Foundry e Microsoft 365 Declarative Agents non sono supportati.

Come funziona un server BYO MCP

Un server MCP BYO segue questo flusso da sviluppatore ad amministratore in modo che i server MCP remoti vengano esaminati e gestiti prima che gli agenti possano accedervi:

La registrazione e l'approvazione in questo flusso si applicano al server MCP, non a un intero pacchetto di plugin. Non approvano automaticamente agenti o plugin che usano il server. Non dare per scontato che questi controlli si applichino a tutti i prodotti o ai componenti collegati.

  1. Uno sviluppatore registra il server tramite la CLI Agent 365 e fornisce l'URL del server, il tipo di autenticazione e gli strumenti da esporre. Per ulteriori informazioni, vedere Registrare un server MCP remoto.

  2. Un amministratore IT esamina la richiesta nel centro interfaccia di amministrazione di Microsoft 365 e la approva o la rifiuta. Dopo l'approvazione, l'amministratore concede le autorizzazioni di Microsoft Entra necessarie per il server. Per ulteriori informazioni, vedere Rivedere e approvare le richieste MCP.

  3. I client supportati utilizzano il server approvato, come Copilot Studio e Visual Studio Code, per costruire e testare agenti con attive reali invocazioni degli strumenti. Per ulteriori informazioni, vedere Utilizzare un server MCP approvato.

  4. Il team di sicurezza monitora attività e invocazioni degli strumenti tramite Microsoft Defender Advanced Hunting per la conformità e il rilevamento delle anomalie. Per ulteriori informazioni, vedere Monitorare e osservare l'attività del server MCP.

Important

Questo processo richiede revisioni di governance e conformità prima che le integrazioni MCP esterne diventino disponibili per gli utenti finali.

Note

Non è possibile ripubblicare le nuove versioni del server MCP remoto durante l'anteprima.

Registrare un server MCP remoto

Tip

Gli amministratori possono utilizzare questi passaggi per comprendere il processo di registrazione o fornirli a uno sviluppatore.

Tu o uno sviluppatore puoi registrare un server MCP remoto con Agent 365 utilizzando la CLI. Dopo la registrazione, un amministratore IT può esaminare e approvare il server per l'uso nelle interfacce per la creazione di agenti.

Completare le attività seguenti:

Prerequisiti per gli sviluppatori

Prima di registrare un server MCP remoto, assicurati di:

  • Avere installato la CLI Agent 365 versione 1.1.165-preview o successiva.

  • Viene eseguito il provisioning del service principal Agent 365 nel tenant. Se non è possibile trovare il service principal associato all'ID app ea9ffc3e-8a23-4a7d-836d-234d7c7565c1, eseguirne il provisioning usando le risorse seguenti:

  • Il server MCP dispone di un endpoint accessibile pubblicamente.

  • Il server utilizza uno dei seguenti tipi di autenticazione supportati:

    • NoAuth.
    • APIKey con un'intestazione o un parametro di query.
    • ExternalOAuth.
    • EntraOAuth.

Installa la CLI di Agent 365

Per installare la CLI di Agent 365, seguire le istruzioni in Installare la CLI di Agent 365.

Registra il server MCP

Scegliere uno dei seguenti metodi per registrare il server MCP con Agent 365:

  • Registrazione manuale tramite CLI: esegui il a365 develop-mcp register-external-mcp-server comando dalla CLI e fornisci manualmente i dettagli del server, il tipo di autenticazione e gli strumenti che il tuo server MCP espone.
  • Registrazione tramite file JSON: Usa a365 develop-mcp register-external-mcp-server -f <path-to-file.json> per registrare il tuo server MCP fornendo un file JSON che contiene tutti i dettagli del server, il tipo di autenticazione e le definizioni degli strumenti in un unico file, invece di specificarli singolarmente sulla riga di comando.

Important

I seguenti esempi utilizzano zava.com come dominio fittizio e nomi generici di server e strumenti per l'illustrazione. Sostituire questi valori con l'URL effettivo del server, il nome e gli identificatori dello strumento.

Gli esempi seguenti mostrano come registrare un server MCP utilizzando l'interfaccia a riga di comando di Agent 365 con diversi tipi di autenticazione.

NoAuth

Per i server MCP che non richiedono l'autenticazione:

a365 develop-mcp register-external-mcp-server \
--server-name "ZavaServer" \
--server-url "https://mcp.zava.com/mcp" \
--publisher "Contoso" \
--description "My external MCP server for document search" \
--auth-type "NoAuth" \
--tools "tool1,tool2"
{
  "serverName": "ext_DocsSearch",
  "serverUrl": "https://docs.contoso.com/api/mcp",
  "authType": "NoAuth",
  "description": "Documentation search MCP Server for Contoso developer docs.",
  "publisherName": "Contoso",
  "tools": [
    {
      "name": "search_docs",
      "description": "Search Contoso developer documentation and code samples."
    }
  ],
  "remoteScopes": null,
  "externalOAuth": null,
  "apiKey": null
}

APIKey (parametro di query)

Per i server che passano la chiave API come parametro di query:

a365 develop-mcp register-external-mcp-server \
--server-name "ZavaServer" \
--server-url "https://mcp.zava.com/mcp" \
--publisher "Contoso" \
--description "My external MCP server for document search" \
--auth-type APIKey \
--api-key-location Query \
--api-key-name apiKey \
--tools "tool1,tool2"
{
  "serverName": "ext_MarketData",
  "serverUrl": "https://api.contoso.com/market/mcp",
  "authType": "APIKey",
  "description": "Real-time stock market data and search from Contoso Market Services.",
  "publisherName": "Contoso",
  "tools": [
    {
      "name": "stock-market-data",
      "description": "Get real-time stock market data and financial information."
    },
    {
      "name": "real-time-search",
      "description": "Search the web for real-time information and news."
    }
  ],
  "remoteScopes": null,
  "externalOAuth": null,
  "apiKey": {
    "location": "Query",
    "name": "apiKey"
  }
}

APIKey (intestazione)

Per i server che passano la chiave API in un'intestazione di richiesta:

a365 develop-mcp register-external-mcp-server \
--server-name "ZavaServer" \
--server-url "https://mcp.zava.com/mcp" \
--publisher "Contoso" \
--description "My external MCP server for document search" \
--auth-type APIKey \
--api-key-location Header \
--api-key-name token \
--tools "tool1,tool2"
{
  "serverName": "ext_InternalTools",
  "serverUrl": "https://tools.contoso.com/mcp",
  "authType": "APIKey",
  "description": "Contoso internal tools MCP Server with API key authentication.",
  "publisherName": "Contoso",
  "tools": [
    {
      "name": "tool1",
      "description": "First tool exposed by the server."
    },
    {
      "name": "tool2",
      "description": "Second tool exposed by the server."
    }
  ],
  "remoteScopes": null,
  "externalOAuth": null,
  "apiKey": {
    "location": "Header",
    "name": "X-API-Key"
  }
}

ExternalOAuth

Per i server che eseguono l'autenticazione tramite un provider OAuth esterno:

a365 develop-mcp register-external-mcp-server \
--server-name "ZavaServer" \
--server-url "https://zava.com/mcp" \
--publisher "Contoso" \
--description "My external MCP server for document search" \
--auth-type ExternalOAuth \
--idp-authorization-url "https://idp.zava.com/o/oauth2/v2/auth" \
--idp-token-url "https://idp.zava.com/oauth2/token" \
--idp-scopes "https://api.zava.com/read" \
--idp-client-id "<your-client-id>" \
--idp-client-secret "<your-client-secret>" \
--remote-scopes "https://api.zava.com/read" \
--tools "tool1,tool2"

{
  "serverName": "ext_Analytics",
  "serverUrl": "https://analytics.contoso.com/mcp",
  "authType": "ExternalOAuth",
  "description": "Contoso Analytics MCP Server for dataset and query operations.",
  "publisherName": "Contoso",
  "tools": [
    {
      "name": "list_datasets",
      "description": "List all available analytics datasets."
    }
  ],
  "remoteScopes": "https://analytics.contoso.com/.default",
  "externalOAuth": {
    "authorizationUrl": "https://auth.contoso.com/oauth2/authorize",
    "tokenUrl": "https://auth.contoso.com/oauth2/token",
    "scopes": "https://analytics.contoso.com/.default",
    "clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "clientSecret": "<your-client-secret>"
  },
  "apiKey": null
}

EntraOAuth

Per i server che eseguono l'autenticazione tramite Microsoft Entra ID:

a365 develop-mcp register-external-mcp-server \
--server-name "ZavaServer" \
--server-url "https://mcp.zava.com/mcp" \
--publisher "Contoso" \
--description "My external MCP server for document search" \
--auth-type EntraOAuth \
--remote-scopes "https://api.zava.com/.default" \
--tools "tool1,tool2"
{
  "serverName": "ext_OrgDirectory",
  "serverUrl": "https://directory.contoso.com/mcp",
  "authType": "EntraOAuth",
  "description": "Contoso organization directory MCP Server secured with Entra OAuth.",
  "publisherName": "Contoso",
  "tools": [
    {
      "name": "list_users",
      "description": "List users in the organization directory."
    },
    {
      "name": "get_user_profile",
      "description": "Get the profile of a specific user by ID or UPN."
    }
  ],
  "remoteScopes": "api://contoso-directory/.default",
  "externalOAuth": null,
  "apiKey": null
}

Dopo aver completato la registrazione, inviare il server MCP per la revisione da parte dell'amministratore nell'interfaccia di amministrazione di Microsoft 365.

Valutare i server MCP

Puoi valutare la qualità delle definizioni degli strumenti MCP usando il a365 develop-mcp evaluate comando. Questo comando esamina gli schemi degli strumenti del server e genera un report con indicazioni utili per migliorare i nomi degli strumenti, le descrizioni e gli schemi dei parametri.

La CLI dell'agente di codifica (GitHub Copilot CLI o Claude Code) che viene eseguita localmente sulla tua macchina, con il tuo account e abbonamento AI, valuta i controlli semantici. Questo comando non invia dati dello schema dello strumento a Microsoft.

Important

Esegui evaluate solo contro server MCP di cui ti fidi. I nomi degli strumenti, le descrizioni e gli schemi dei parametri del server vengono letti tramite una chiamata MCP tools/list standard e consegnati a un agente di codifica in esecuzione sul computer per il punteggio. Questo avviso di attendibilità viene stampato una sola volta all'inizio di ogni esecuzione che usa un agente. Non si applica a --eval-engine none, che mantiene tutto locale.

Non è necessario un ruolo di amministratore per eseguire la valutazione. Viene eseguito localmente rispetto all'URL del server MCP che fornisci e non chiama Azure o Microsoft Graph.

Prerequisites

  • Installare Agent 365 CLI.
  • Per il punteggio semantico (AI), installa localmente un CLI di coding agent:
    • GitHub Copilot CLI: Installa con npm install -g @github/copilot (Node.js 18 o successiva). Questa CLI è il binario standalonecopilot, non l'estensione gh copilot CLI di GitHub.
    • Claude Code: Installa con npm install -g @anthropic-ai/claude-code, oppure segui Claude Code install.
  • Se non installi nessuno degli agenti, il comando esegue comunque i controlli deterministici e scrive la checklist, poi si ferma così puoi puntare i controlli semantici con il tuo LLM (bring-your-own-LLM). Usa --eval-engine none per ignorare completamente il rilevamento dell'agente.

Come funziona la valutazione

Il comando esegue una pipeline in cinque passaggi e registra lo stato di avanzamento, come illustrato nella tabella seguente:

Step Funzionamento
1. Scopri gli strumenti Si connette al server MCP, chiama tools/liste acquisisce lo schema di ogni strumento.
2. Generare una checklist Scrive il file <server-name>_checklist.json nella directory di output.
3. Eseguire la valutazione semantica Passa l'elenco di controllo all'agente di codifica selezionato per la valutazione. Salta quando specifichi --eval-engine none o non c'è un agente disponibile.
4. Analizzare Aggrega i punteggi complessivi e per strumento e determina il livello di maturità.
5. Scrivere report Genera <server-name>_eval_report.html e <server-name>_eval_report.json.

Ogni controllo è di due tipi:

  • Deterministico: Logica basata su regole nella CLI; passare o fallire è esatto e non richiede IA (ad esempio, "nome dello strumento non è vuoto").
  • Semantica: Valutata dall'agente di codifica, con una reason stringa che spiega il giudizio.

L'esecuzione è idempotente. Rieseguire lo stesso comando riutilizza un <server-name>_checklist.json esistente e salta la scoperta del server. Questo processo supporta il viaggio di andata e ritorno del tuo LLM: punteggio la checklist da solo, poi ripeti per riprendere. Eliminare il file checklist per forzare una nuova scoperta dopo aver modificato gli schemi dello strumento.

Examples

Valutare un server locale con la selezione automatica del motore:

a365 develop-mcp evaluate --server-url "http://localhost:5000/mcp"

Valutare un server autenticato, con il token fornito tramite una variabile di ambiente e artefatti scritti in una sottocartella:

$env:A365_MCP_AUTH_TOKEN = "<bearer-token>"
a365 develop-mcp evaluate --server-url "https://my-mcp-server.contoso.com/mcp" --output-dir "./eval"

Genera solo la lista di controllo, quindi assegna un punteggio con il tuo LLM:

a365 develop-mcp evaluate --server-url "https://my-mcp-server.contoso.com/mcp" --eval-engine none

Forza un motore di punteggio specifico:

a365 develop-mcp evaluate --server-url "http://localhost:5000/mcp" --eval-engine claude-code

Leggi il report

Apri <server-name>_eval_report.html dalla directory di output in un browser. Il report mostra:

  • Il punteggio complessivo (0-100; più alto è meglio).
  • I punteggi per strumento con suddivisioni per categoria: nome strumento, descrizione strumento, nome parametro, descrizione parametro e struttura dello schema.
  • Elenco di azioni prioritarie, ordinate in base all'impatto, inclusi i requisiti concreti per raggiungere il livello di maturità successivo.

Screenshot del report HTML develop-mcp che mostra punteggio di qualità complessivo, livello di maturità, conteggio delle chiavi e punteggi per categoria per dimensione.

Gestione dei dati e trasparenza dell'IA

  • Il comando elabora solo gli schemi di strumenti statici del server MCP (nomi, descrizioni e schemi di parametri) da tools/list. Non elabora payload di runtime, dati dell'utente finale o dati personali.
  • Il CLI dell'agente di coding viene eseguito sul tuo computer nell'ambito del tuo abbonamento AI. La chiamata API del modello viene effettuata direttamente da tale CLI al provider di intelligenza artificiale secondo i tuoi termini di servizio e la tua fatturazione. La a365 CLI specifica il modello ma non media la chiamata.
  • Il --auth-token valore viene mantenuto in memoria, inviato solo come intestazione HTTP Authorization al server e mai scritto su disco o passato all'agente di codifica.
  • I file di output (_checklist.json, _eval_report.html, _eval_report.json) vengono scritti solo sul tuo --output-dir e rimangono sul tuo computer.

Troubleshooting

Usare la seguente guida alla risoluzione dei problemi per diagnosticare gli errori comuni e applicare la correzione consigliata.

Sintomo Causa possibile Correzione
Unauthorized da tools/list Token bearer errato o scaduto Riacquisire il token e passarlo tramite A365_MCP_AUTH_TOKEN.
Unknown eval engine Valore non valido --eval-engine Usare uno di auto, github-copilot, claude-codeo none.
La pipeline si arresta dopo [2/5] Nessun agente di codifica su PATH Installa GitHub Copilot CLI o Claude Code oppure assegna un punteggio all'elenco di controllo e riesegui.
--output-dir cannot be empty or whitespace Un valore vuoto è stato passato a --output-dir Passare un percorso di directory valido o omettere l'opzione per utilizzare la directory corrente.
Failed to read existing checklist Il file dell'elenco di controllo è bloccato o non valido Eliminare il file dell'elenco di controllo per forzare una nuova individuazione all'esecuzione successiva.

Rivedere e approvare le richieste del server BYO MCP

Dopo che uno sviluppatore ha registrato un server BYO MCP, un amministratore lo esamina e lo approva allo stesso modo di qualsiasi altra richiesta di strumento. Per i passaggi completi di revisione e approvazione, vedere Rivedere e approvare le richieste MCP.

Controlli di governance chiave

Nella tabella seguente sono riepilogati i controlli di governance principali:

CTRL Description
Approvazione o rifiuto Un amministratore approva o rifiuta ogni server BYO MCP prima che possa essere utilizzato.
Blocco a livello di server Un amministratore può bloccare un server approvato. Il Gateway degli Strumenti Agent 365 impedisce ai client supportati di invocare il server bloccato tramite il gateway.
Blocco a livello di strumento Il blocco individuale degli strumenti per i server BYO MCP è previsto per una futura versione. I controlli a livello di strumento stanno venendo implementati per altri tipi di server MCP supportati registrati su Agent 365. Per ulteriori informazioni, vedere Gestire i singoli strumenti all'interno di un server MCP.
Panoramica degli strumenti Un amministratore può visualizzare gli strumenti dichiarati da ciascun server MCP.
Applicazione delle regole durante il runtime L'Agent 365 Tooling Gateway applica il blocco dei server per le invocazioni instradate attraverso il gateway dai client supportati. Non dare per scontato che il blocco impedisca l'accesso diretto all'endpoint del server sottostante.
Delete Un amministratore può eliminare un server BYO MCP registrato che non è più necessario. Per ulteriori informazioni, vedere Eliminare un server BYO MCP.

Utilizzare un server MCP approvato

Dopo l'approvazione di un server MCP e la concessione del consenso da parte di Microsoft Entra, è possibile utilizzarlo nelle interfacce supportate per la creazione di agenti. Le superfici client seguenti supportano i server BYO MCP approvati durante l'anteprima:

Client Condizione
Copilot Studio Supported
Visual Studio Code Supported
Claude Code Supported
interfaccia della riga di comando (CLI) di GitHub Copilot Supported

In Copilot Studio, segui questa procedura per richiamare il server BYO MCP approvato:

  1. Vai a Copilot Studio nel tuo ambiente.

  2. Creare un nuovo agente personalizzato (o aprirne uno esistente).

  3. Vai alla sezione Strumenti e seleziona Server MCP.

  4. Selezionare il server MCP dal registro.

  5. Testa l'agente immettendo un prompt che richiami il server MCP.

Note

La prima volta che si richiama il server, potrebbe essere richiesto di completare una configurazione di connessione una tantum. Segui l'URL fornito per creare la connessione richiesta, ad esempio inserendo la chiave API per un server basato su APIKey. Al termine, torna dal tuo agente e riprova la richiesta. Dopo un'invocazione riuscita, il server MCP restituisce l'output dello strumento.

Scopri come invocare server BYO MCP approvati da Claude Code, VS Code e dall'interfaccia a riga di comando di GitHub Copilot nella sezione Configurazione dei server MCP Work IQ per gli agenti di codifica della panoramica di Work IQ MCP.

Note

Work IQ MCP fornisce controlli di policy a livello di tenant che aiutano gli amministratori a governare come gli agenti accedono e agiscono sulle risorse di Microsoft 365. Per imparare a configurare questi controlli, consulta Governance delle politiche per Work IQ MCP.

Monitorare e osservare l'attività del server MCP

Usa Microsoft Defender advanced hunting per tracciare e analizzare le invocazioni del server MCP instradate attraverso l'Agent 365 Tooling Gateway. Questo processo mostra quali agenti richiamano quali server MCP, quando si verificano le chiamate e altri metadati che possono aiutarti a rilevare utilizzi insoliti o non autorizzati. Questa telemetria non fornisce una copertura completa di monitoraggio per ogni plugin o ogni componente in un pacchetto plugin.

La query KQL seguente fornisce un esempio per la ricerca avanzata di Defender:

CloudAppEvents
| where ActionType in ( "ExecuteToolByGateway")
| where RawEventData contains "tool name"

Questa query restituisce dettagli tra cui il nome dell'agente, il nome del server MCP e i metadati di chiamata.

Eliminare un server BYO MCP

È possibile eliminare un server BYO MCP registrato dall'interfaccia di amministrazione di Microsoft 365 quando non è più necessario. Eliminare la registrazione rimuove il server dal registro e gli agenti non possono più invocarlo tramite l'Agent 365 Tooling Gateway. Non considerare la cancellazione della registrazione come spegnere il servizio remoto, revocare le sue credenziali o impedire l'accesso diretto al suo endpoint.

Per eliminare un server BYO MCP, attenersi alla seguente procedura:

  1. Accedi all'interfaccia di amministrazione di Microsoft 365.
  2. Selezionare Agenti>, quindi selezionare la scheda Registro.
  3. Seleziona il server BYO MCP che desideri eliminare per aprirne il riquadro di panoramica.
  4. Seleziona Elimina.
  5. Confermare l'eliminazione selezionando Elimina.