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:

Requisiti

• Un'area di lavoro abilitata per Unity Catalog.

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

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 del servizio associati, che possono consentire, negare o richiedere l'approvazione per 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.

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 dare accesso a un agente, concedere EXECUTE sul servizio (ad esempio, system.ai.github). Nessuna 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 Microsoft 365, questi servizi predefiniti gestiscono automaticamente OAuth senza alcuna registrazione dell'app.

Invoca un servizio MCP integrato

Fai riferimento a un servizio integrato tramite il relativo URL di Unity AI Gateway, con il nome completo nel percorso. Usa il nome esattamente come appare, con i suoi punti e sottoline, e non codificarlo tramite URL:

https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<mcp-service>

Per chiamare il servizio dal codice dell'agente, indirizza DatabricksMCPClient o un framework per agenti a questo URL. Vedi Usa i server MCP negli Custom Agents.

Scopri gli strumenti di un servizio e leggi i suoi risultati

Ogni servizio MCP espone un set diverso di strumenti, quindi scoprili in tempo reale invece di codificare i nomi in modo rigido. Chiama tools/list (o DatabricksMCPClient.list_tools()) per ottenere il nome, la descrizione e lo schema di input di ogni strumento. Vedi Usa i server MCP negli Custom Agents.

Leggi il risultato di una chiamata di uno strumento dal result campo. La sua forma dipende dal fatto che lo strumento defina o meno un'uscita strutturata:

• Output digitato. Uno strumento può dichiarare un outputSchema e restituire un oggetto JSON tipizzato in structuredContent. Quando structuredContent è presente, usalo direttamente. Non richiede alcuna analisi sintattica. Alcuni strumenti di Azure Databricks, come quelli di Genie, funzionano così.
• Output di testo. Quando non c'è structuredContent, leggi invece i blocchi di testo. Il primo blocco contiene un documento JSON, quindi analizzalo result.content[0].text come JSON.
• Nessuno dei due. MCP non richiede uno schema di output. Quando uno strumento non definisce nessuno, ispeziona una risposta campione per conoscere i suoi campi di output.

Ad esempio, system.ai.google_calendar espone strumenti di lettura come calendar_event_list, il cui risultato JSON ha un items array di eventi (ciascuno con id, summary, start, end, status, location, e link). Gli strumenti e le strutture dei risultati di un altro servizio sono completamente diversi, quindi verifica sempre con tools/list e con una chiamata di esempio.

Registrare un server MCP esterno

Per qualsiasi server MCP esterno non coperto da OAuth gestito o dai servizi MCP forniti da Databricks, registralo come servizio MCP per gestirlo come oggetto securizzabile di Unity Catalog. Vedi Registra un server MCP esterno.

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.

Abilita l'accesso per utente (accesso per conto dell'utente)

Alcuni servizi leggono dati appartenenti a un utente specifico, come il calendario o la posta elettronica. Per questi servizi, usa OAuth per utente in modo che ogni chiamata venga eseguita come utente che l'ha effettuata, non come identità condivisa. Questo vale per i servizi integrati system.ai.* come system.ai.google_calendar, system.ai.gmail, e system.ai.microsoft_365, e per i servizi esterni che registri con l'autenticazione per utente.

Per configurare l’accesso per conto di un agente:

1. Assicurati che l'utente chiamante possa invocare il servizio. Invocare qualsiasi Servizio MCP richiede due cose:

   • EXECUTE nel servizio.
   • USE CATALOG e USE SCHEMA sul suo catalogo e schema genitore. EXECUTE da solo non basta, perché Unity Catalog controlla anche la gerarchia superiore (vedi Concedere l'accesso ai colleghi).

   Come li concedi dipende dal servizio:

   • Servizi integrati system.ai.* : gli utenti dell'account hanno già questi privilegi attivi system e system.ai di default, quindi di solito non è necessario concedere nulla.
   • Servizi personalizzati nel tuo catalogo e schema: Concedi all'utente o al gruppo chiamante le autorizzazioni appropriate (non solo all'entità servizio dell'app) dalla scheda Autorizzazioni di ciascun oggetto proteggibile in Catalog Explorer oppure tramite l'API REST. SQL DDL non è disponibile per i servizi MCP.

   Per autorizzare con l'API REST, sostituisci con il tuo <catalog>.<schema>.<service>:

   databricks api patch "/api/2.1/unity-catalog/permissions/mcp_service/<catalog>.<schema>.<service>" \
     --json '{ "changes": [ { "principal": "data-team", "add": ["EXECUTE"] } ] }'
   databricks api patch "/api/2.1/unity-catalog/permissions/catalog/<catalog>" \
     --json '{ "changes": [ { "principal": "data-team", "add": ["USE_CATALOG"] } ] }'
   databricks api patch "/api/2.1/unity-catalog/permissions/schema/<catalog>.<schema>" \
     --json '{ "changes": [ { "principal": "data-team", "add": ["USE_SCHEMA"] } ] }'
   

2. Aggiungi l'ambito API utente ai-gateway alla tua app in modo che il token utente inoltrato possa raggiungere il servizio. Dichiara user_api_scopes: [ai-gateway] nella risorsa dell'app e chiama il servizio con il client per utente (get_user_workspace_client()). Consulta Autenticazione ai servizi MCP e Crea un agente e distribuiscilo in Databricks Apps.

3. Ogni utente dà il consenso una volta. La prima volta che un utente chiama il servizio, deve completare un login OAuth una tantum. La tua app riceve un link di accesso per mostrare all'utente, oppure l'utente può aprire il servizio in Esplora cataloghi e cliccare su Accedi.

Limitazioni

Le seguenti limitazioni 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

• Registrare un server MCP esterno per registrare e richiamare un server MCP esterno.
• Gestire un servizio MCP per limitare gli strumenti e applicare i criteri di servizio.
• Usa i server MCP in Custom Agents per chiamare un servizio MCP in modo programmatico dal codice dell'agente, con esempi per l'SDK OpenAI Agents, LangGraph e Model Serving.
• Connetti gli MCP agli assistenti IA e agli agenti di codifica per connettere gli agenti di codifica e gli assistenti IA.
• Monitora tutta l'attività dell'IA utilizzando la tabella di traccia unificata per monitorare, debugare e auditare tutte le attività MCP da un unico posto.
• Governance dell’IA con Unity AI Gateway per governare i server MCP e gli endpoint LLM da un’unica posizione centrale.