Connettere gli agenti a strumenti di terze parti con i servizi MCP

Un servizio MCP è un oggetto a protezione diretta di Unity Catalog che registra un server MCP esterno e disciplina il modo in cui gli agenti lo utilizzano. Lo si indirizza tramite il relativo nome a tre livelli, catalog.schema.mcp_service, e lo si richiama tramite Unity AI Gateway, il piano di controllo per gestire il traffico AI.

La registrazione di un server MCP come entità a protezione diretta del catalogo Unity significa gestirlo con le stesse primitive che proteggono gli altri asset del catalogo Unity. Queste includono concessioni per controllare chi può richiamarlo, la selezione degli strumenti per limitare gli strumenti esposti, i criteri di servizio per consentire o negare le singole chiamate agli strumenti e controllare e la registrazione dell'utilizzo per tenere traccia di ogni chiamata.

Esistono due modi per usare i servizi MCP:

I servizi MCP connettono gli agenti ai servizi esterni. Per Azure Databricks dati, usare server MCP gestiti; per ospitare strumenti personalizzati, usare un server MCP personalizzato.

Come funziona

Un agente chiama un servizio MCP tramite l'URL del gateway di intelligenza artificiale unity e ogni chiamata passa attraverso lo stesso percorso regolamentato:

1. Invoke: l'agente invia una richiesta MCP all'URL del gateway di intelligenza artificiale Unity del servizio, autenticato con l'identità Azure Databricks del chiamante.
2. Autorizzare e gestire: il gateway verifica che il chiamante disponga EXECUTE del servizio MCP nel catalogo Unity. Il servizio espone solo gli strumenti selezionati e valuta tutti i criteri di servizio associati, che possono consentire, negare, richiedere l'approvazione o trasformare la chiamata.
3. Proxy con credenziali gestite: la richiesta viene inoltrata al server MCP esterno tramite la connessione HTTP del servizio. Azure Databricks archivia le credenziali e gestisce i flussi OAuth e l'aggiornamento dei token, quindi l'agente non li vede mai.
4. Utilizzo dei log, controllo e tracce: ogni chiamata viene registrata nelle tabelle di sistema, in modo da poter monitorare l'attività di utilizzo e controllo nel tempo.

Requirements

• Un'area di lavoro abilitata per Unity Catalog.
• Per gestire un server MCP esterno come servizio MCP, devi avere Unity AI Gateway Beta e l'anteprima di Managed MCP Servers abilitati per il tuo account. Vedere Gestire le anteprime di Azure Databricks.

• Area di lavoro in un'area in cui è supportata la gestione dei modelli. Vedere Disponibilità delle funzionalità di gestione dei modelli.

Servizi MCP forniti da Databricks

Azure Databricks fornisce servizi MCP pronti all'uso system.ai nello schema per le applicazioni SaaS comuni, in modo che gli agenti possano raggiungere questi strumenti senza ospitare o registrare il proprio server MCP. Ognuno di essi è un servizio MCP predefinito a cui si fa riferimento in base al nome del catalogo Unity. Per concedere a un agente l'accesso, concedere EXECUTE al servizio (ad esempio) system.ai.github- nessuna configurazione della connessione necessaria. I servizi predefiniti vengono forniti con strumenti gestiti dalla piattaforma e criteri di servizio predefiniti, ad esempio uno per bloccare le operazioni di scrittura. È possibile gestirli con concessioni anziché con funzioni personalizzate di selezione o criteri degli strumenti.

Per Google Drive, Gmail, Google Calendar o SharePoint, questi servizi predefiniti gestiscono automaticamente OAuth, senza alcuna registrazione dell'app.

Registrare un server MCP esterno

Registrare il proprio server MCP esterno come servizio MCP in cinque passaggi:

1. Creare una connessione del catalogo Unity al server MCP.
2. Creare il servizio MCP da tale connessione.
3. Eseguire l'autenticazione, se la connessione usa OAuth per utente.
4. Concedere l'accesso ai colleghi.
5. Richiamare il servizio, quindi controllarlo con la selezione degli strumenti e i criteri del servizio.

Il server MCP esterno deve usare il meccanismo di trasporto HTTP streamable. Sono necessarie queste autorizzazioni:

• Per creare la connessione, CREATE CONNECTION nello schema in cui la crei.
• Per creare un servizio MCP, USE CATALOG e USE SCHEMA sul catalogo padre e sullo schema, CREATE SERVICE sullo schema e USE CONNECTION sulla connessione a cui fa riferimento il servizio MCP.
• Per invocare un servizio MCP, EXECUTE sul servizio MCP, USE CATALOG e USE SCHEMA sul catalogo padre e sullo schema padre, nonché l'assegnazione all'area di lavoro da cui si invia la richiesta.

Crea una connessione

Un servizio MCP fa riferimento a una connessione HTTP del catalogo Unity che archivia in modo sicuro l'endpoint e le credenziali del server esterno. Azure Databricks esegue un proxy gestito davanti a esso per gestire l'autenticazione e l'aggiornamento del token, in modo da non incorporare le credenziali nel codice dell'agente o del client.

Creare la connessione a livello di schema in modo che sia governata insieme al servizio MCP. È possibile configurarlo in anticipo con i passaggi seguenti oppure crearne uno durante la creazione del servizio MCP facendo clic su Crea nuova connessione. Le connessioni a livello di metastore sono supportate ma non consigliate.

Scegliere uno dei due modi seguenti:

Creare una connessione HTTP

Per qualsiasi server MCP, inclusi i server self-hosted o di terze parti:

1. Passare a Catalogo>Connessioni>Crea connessione.
2. Selezionare HTTP come tipo di connessione.
3. Immettere l'URL del server MCP.
4. Scegliere un tipo di autenticazione: token Bearer, OAuth M2M, OAuth U2M o registrazione dinamica del client. Per informazioni dettagliate sull'installazione, vedere Creare una connessione al servizio esterno.

Per i provider OAuth gestiti, ovvero Glean, GitHub, Atlassian e Slack, Azure Databricks gestisce le credenziali, quindi non si registra la propria app OAuth. Vedere Provider OAuth gestiti.

Installare da Marketplace

Usare un server MCP curato da Azure Databricks Marketplace con una connessione preconfigurata. Vedere Ottenere l'accesso ai server MCP esterni.

Creare il servizio MCP

È possibile creare un servizio MCP dall'interfaccia utente o con l'API REST. La versione beta non supporta SQL DDL per i servizi MCP.

Interfaccia utente

1. Nell'area di lavoro di Azure Databricks, vai a AI Gateway>MCPs>Registra server MCP, oppure vai a Catalog, seleziona uno schema e fai clic su Crea>Servizio MCP.
2. Immettere il catalogo, lo schema e un nome per il servizio MCP. Il nome non può essere modificato dopo la creazione.
3. Selezionare una connessione HTTP esistente al server MCP oppure fare clic su Crea nuova connessione per crearne una. Sfoglia all'interno di uno schema per selezionare una connessione a livello di schema; per usare una connessione a livello di metastore, disattiva Sfoglia all'interno di uno schema.
4. In Strumenti selezionare gli strumenti da rendere disponibili. Vedere Selezionare gli strumenti esposti.
5. Facoltativamente, aggiungere un commento che descrive il servizio MCP.
6. Clicca su Crea. Il servizio MCP viene pubblicato nel catalogo e nello schema specificato.

REST API

Creare un servizio MCP che faccia riferimento a una connessione HTTP del catalogo Unity esistente. Impostare parent sullo schema di destinazione e mcp_service_id sul nome del servizio:

databricks api post \
  "/api/2.1/unity-catalog/mcp-services?parent=schemas/main.default&mcp_service_id=my_mcp" \
  --json '{
    "comment": "External MCP server",
    "config": {
      "connection": {
        "name": "connections/main.default.my_connection"
      },
      "include_tool_selectors": []
    }
  }'

include_tool_selectors determina quali strumenti il servizio espone. Un elenco vuoto espone tutti gli strumenti. Vedere Selezionare gli strumenti esposti.

Aggiornare un servizio MCP esistente con una PATCH richiesta e un oggetto update_mask che denomina i campi da modificare:

databricks api patch \
  "/api/2.1/unity-catalog/mcp-services/main.default.my_mcp?update_mask=comment" \
  --json '{ "comment": "Updated description" }'

Authenticate

Se il servizio MCP fa riferimento a una connessione che usa OAuth per singolo utente, effettuare un accesso una tantum prima della prima chiamata:

1. Aprire la pagina dei dettagli del servizio MCP in Esplora cataloghi.
2. Fare clic su Login e completare la procedura di consenso OAuth del provider.
3. Dopo l'accesso, la pagina dei dettagli mostra automaticamente l'elenco degli strumenti individuati.

Unity Catalog archivia il token associandolo alla tua identità. Se si chiama il servizio MCP prima dell'accesso, il gateway di intelligenza artificiale restituisce un errore che richiede di eseguire l'autenticazione.

Concedere l'accesso ai compagni di squadra

Per impostazione predefinita, solo il proprietario del servizio MCP può richiamarlo. Concedi EXECUTE per consentire ad altri utenti, gruppi o alle entità servizio di invocare il servizio. Una singola EXECUTE concessione copre tutti gli strumenti del servizio.

Interfaccia utente

1. Apri il servizio MCP in Catalog Explorer oppure vai a AI Gateway>MCPs e seleziona il servizio.
2. Passare alla scheda Autorizzazioni .
3. Fare clic su "Concedi".
4. Selezionare gli utenti, i gruppi o le entità servizio a cui concedere l'accesso.
5. Selezionare il privilegio EXECUTE .
6. Fare clic su "Concedi".

REST API

databricks api patch \
  "/api/2.1/unity-catalog/permissions/mcp_service/main.default.my_mcp" \
  --json '{
    "changes": [
      { "principal": "data-team", "add": ["EXECUTE"] }
    ]
  }'

Richiamare un servizio MCP

Provare un servizio MCP in AI Playground, dalla riga di comando o dal codice dell'agente o del client.

Testare il servizio MCP

Area di Sperimentazione IA

Testare gli strumenti di un servizio MCP nell'interfaccia utente senza scrivere codice:

1. Passare a AI Playground nell'area di lavoro Azure Databricks.
2. Selezionare un modello con l'etichetta Strumenti abilitata .
3. Fare clic su Strumenti > e aggiungi strumento e selezionare Server MCP.
4. Selezionare Server MCP esterni e quindi selezionare il servizio MCP.
5. Chattare con il modello per vedere come chiama gli strumenti del servizio MCP.

È anche possibile eseguire il test da Genie Code . Vedere Aggiungere server MCP all'Assistente.

CURL

Per un rapido controllo della riga di comando, usare la richiesta generata nella pagina dei dettagli del servizio MCP. In Introduzione fare clic su Genera token di accesso per copiare un token di accesso negli esempi di richiesta. Gli esempi passano il token come token di connessione nell'intestazione Authorization .

È anche possibile autenticare l'interfaccia della riga di comando di Databricks nell'area di lavoro, quindi usare databricks auth token per ottenere un token di accesso OAuth:

databricks auth login --host https://<workspace-url>

Tutte le richieste passano allo stesso endpoint del servizio MCP. Il JSON-RPC method nel corpo della richiesta seleziona l'operazione. Elencare gli strumenti esposti dal servizio:

TOKEN=$(databricks auth token | jq -r .access_token)

curl -s -X POST \
  "https://<workspace-url>/ai-gateway/mcp-services/main.default.my_mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Chiamare uno strumento:

curl -s -X POST \
  "https://<workspace-url>/ai-gateway/mcp-services/main.default.my_mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"<tool_name>","arguments":{}}}'

Usare dal codice dell'agente o da un agente di codifica

• Codice agente (OpenAI Agents SDK, LangGraph o Model Serving): vedere Usare i server MCP negli agenti.
• Assistenti di intelligenza artificiale e agenti di codifica (Claude, Claude Code, Cursor): vedere Connettere mcp agli assistenti di intelligenza artificiale e agli agenti di codifica.

Gestire un servizio MCP

Selezionare gli strumenti esposti

Per impostazione predefinita, un servizio MCP rende disponibili tutti gli strumenti forniti dal server MCP. Per rendere disponibile solo un subset, selezionare gli strumenti quando si crea il servizio MCP o aggiornare la selezione in un secondo momento. Ogni selettore viene confrontato con i nomi degli strumenti: un modello che termina con * corrisponde a un prefisso (get_* corrisponde a get_me e get_issue), mentre qualsiasi altro valore corrisponde in modo esatto (search_repositories corrisponde solo a quello strumento).

Interfaccia utente

Nel flusso di creazione, in Strumenti:

• Seleziona Seleziona manualmente per selezionare ogni strumento singolarmente.
• Selezionare Avanzate per immettere i criteri di selezione usando il prefisso e le regole di corrispondenza esatta descritte in precedenza.
• Attivare Includi automaticamente gli strumenti aggiunti a questo server in futuro per rendere disponibili nuovi strumenti man mano che il server MCP li aggiunge.

REST API

Per modificare la selezione dello strumento dopo la creazione, imposta include_tool_selectors tramite una richiesta PATCH. Limitare un servizio ai soli get_* strumenti:

databricks api patch \
  "/api/2.1/unity-catalog/mcp-services/main.default.my_mcp?update_mask=config.include_tool_selectors" \
  --json '{
    "config": {
      "include_tool_selectors": ["get_*"]
    }
  }'

Reimposta per rendere disponibili tutti gli strumenti impostando include_tool_selectors su un elenco vuoto.

Gli strumenti non selezionati non vengono visualizzati in tools/liste il servizio MCP rifiuta un tools/call per uno strumento non selezionato:

{ "code": -32003, "message": "Tool not allowed by MCP service configuration." }

Applicare un criterio di servizio

I criteri di servizio valutano ogni chiamata di strumento prima dell'esecuzione (ON CALL) e, facoltativamente, il relativo risultato (ON RESULT). Un criterio può consentire, negare, richiedere l'approvazione umana o trasformare la richiesta, ad esempio per bloccare operazioni distruttive o modificare le informazioni personali, senza modificare gli strumenti disponibili. Le policy di servizio fanno parte della governance dell'IA in Unity Catalog.

Per scrivere una funzione di criteri e collegarla a un servizio MCP, vedere Criteri di servizio per le entità a protezione diretta di intelligenza artificiale e Creare e collegare criteri di servizio.

Impostare i limiti di frequenza

Limitare la frequenza con cui gli agenti possono chiamare un servizio MCP per controllare i costi e proteggere il server esterno. Vedere Configurare i limiti di frequenza per i servizi di intelligenza artificiale usando Unity AI Gateway.

Monitorare l'utilizzo

Unity AI Gateway registra l'attività per ogni servizio MCP nelle tabelle di sistema del catalogo Unity:

• Utilizzo: volume delle chiamate, errori e latenza in system.ai_gateway.usage (filtro service_type = 'MCP_SERVICE'). Vedere Utilizzo del modello per i servizi gateway di intelligenza artificiale Unity.
• Audit: modifiche al piano di controllo (createMcpService, updateMcpService, deleteMcpService) e ogni invocazione (mcpCall) in system.access.audit. Consultare la tabella di sistema del registro di controllo .
• Tracce: le richieste di chiamata agli strumenti, le risposte e le decisioni relative ai criteri vengono acquisite dalla registrazione di traccia, che viene abilitata una sola volta a livello di account e condivisa in tutti i servizi MCP.
• Dashboard: il traffico del server MCP esterno viene visualizzato nel dashboard di utilizzo predefinito del gateway di intelligenza artificiale unity. Vedere Dashboard di utilizzo predefinito.

Per tutte le tabelle di sistema di Unity Catalog, vedere Informazioni di riferimento sulle tabelle di sistema. Per una panoramica sulla governance del traffico AI, consulta Governance dell'AI in Unity Catalog.

Autenticazione e sicurezza

Azure Databricks usa proxy MCP gestiti e connessioni HTTP del catalogo Unity per gestire in modo sicuro l'autenticazione ai server MCP esterni.

• Autenticazione condivisa del principale: Tutti gli utenti condividono le stesse credenziali quando accedono al servizio esterno. Sono inclusi token Bearer, OAuth Machine-to-Machine (M2M) e autenticazione condivisa OAuth User-to-Machine. Usare questa opzione quando il servizio esterno non richiede l'accesso specifico dell'utente o quando è sufficiente un singolo account del servizio.
• Autenticazione per utente (OAuth U2M per utente): ogni utente esegue l'autenticazione con le proprie credenziali. Il servizio esterno riceve richieste per conto del singolo utente, abilitando il controllo di accesso, il controllo e la responsabilità specifici dell'utente. Usare questa opzione quando si accede a risorse specifiche dell'utente, ad esempio i repository di GitHub di un utente, i messaggi Slack o il calendario.

Azure Databricks gestisce i flussi OAuth e l'aggiornamento dei token, quindi gli utenti finali non vedono i token. È possibile visualizzare e gestire le connessioni MCP esterne insieme agli endpoint LLM da Unity AI Gateway. Per istruzioni dettagliate sulla configurazione per ogni metodo di autenticazione, vedere Connessioni HTTP.

Limitations

Durante la versione beta, le limitazioni seguenti si applicano ai servizi MCP:

• DDL SQL per i servizi MCP (ad esempio , CREATE MCP SERVICE) non è disponibile. Creare e gestire i servizi MCP con l'interfaccia utente o l'API REST.
• È possibile registrare solo server MCP esterni come servizio MCP. La registrazione di fonti di entità Genie, Apps o Unity Catalog come servizio MCP non è attualmente supportata. Azure Databricks fornisce anche servizi MCP predefiniti per le app SaaS comuni.
• La selezione degli strumenti supporta i prefissi (get_*) e i modelli di corrispondenza esatta. I modelli di esclusione (ad esempio , !delete_*) non sono supportati.
• La ricerca globale di Unity Catalog non mostra i servizi MCP.

Le connessioni server MCP esterne presentano anche le limitazioni seguenti:

• I server MCP esterni sono disponibili solo nelle aree in cui è supportata la gestione dei modelli, tra cui l'uso in AI Playground, Genie Code e Chat in Genie. Vedere Disponibilità delle funzionalità di gestione dei modelli.

Passaggi successivi

• Usa i server MCP negli agenti per chiamare a livello di programmazione un servizio MCP dal codice dell'agente.
• Connetti gli MCP agli assistenti IA e agli agenti di codifica per connettere gli agenti di codifica e gli assistenti IA.
• Gateway di intelligenza artificiale Unity per gestire i server MCP e gli endpoint LLM da una posizione centrale.
• Governance dell'intelligenza artificiale in Unity Catalog per una panoramica della governance degli asset di intelligenza artificiale e del traffico di intelligenza artificiale.