Agents koppelen aan tools van derden met MCP-services

Een MCP-service is een Unity Catalog beveiligbaar die een externe MCP-server registreert en bepaalt hoe agents deze gebruiken. Je spreekt het aan met zijn drie-niveaus naam, catalog.schema.mcp_service, en roept het aan via Unity Gateway, het controlevlak voor het beheren van AI-verkeer.

Het registreren van een MCP-server als een Unity Catalog beveiligbaar betekent dat u deze beheert met dezelfde primitieven die uw andere Unity Catalog-assets beschermen. Deze omvatten subsidies om te bepalen wie het kan aanroepen, selectie van hulpprogramma's om te beperken welke hulpprogramma's worden weergegeven, servicebeleid om afzonderlijke hulpprogramma-aanroepen toe te staan of te weigeren, en audit- en gebruikslogboekregistratie om elke aanroep bij te houden.

Note

MCP-diensten zijn een van de verschillende manieren om agenten te verbinden met externe MCP's en tools, en de aanbevolen methode wanneer de dienst een MCP-server publiceert. Voor de volledige set opties, waaronder managed OAuth, de Unity Catalog connections proxy en het direct aanroepen van REST API's, zie dat overzicht.

Er zijn twee manieren om MCP-services te gebruiken:

Approach Wanneer gebruiken
Een door Databricks geleverde MCP-service gebruiken Je wilt een gangbare software-as-a-service (SaaS) tool zoals Slack, GitHub of Google Drive zonder enige setup. Geen server om te hosten en geen verbinding om te maken.
Uw eigen externe MCP-server registreren U hebt een zelfgehoste MCP-server of een MCP-server van derden die u als een beveiligbaar object in Unity Catalog kunt beheren.

Requirements

  • Een werkruimte waarvoor Unity Catalog is ingeschakeld.

Hoe werkt het?

Een agent roept een MCP-service aan via zijn Unity Gateway-URL, en elke oproep loopt via hetzelfde bestuurde pad:

Een agent die is geconfigureerd met een MCP Service URL roept de service aan via Unity Gateway. De gateway autoriseert de aanroep tegen de MCP Service in Unity Catalog, die het uitvoeren-toekennings-, toolselectie- en servicebeleid afdwingt, en vervolgens het verzoek via een Unity Catalog HTTP-verbinding met beheerde inloggegevens naar de externe MCP-server stuurt, zoals GitHub of Slack. Gebruiks-, audit- en tracerecords landen in systeemtabellen.

  1. Aanroepen: De agent stuurt een MCP-verzoek naar de Unity Gateway-URL van de service, geauthenticeerd met de Azure Databricks-identiteit van de aanroeper.
  2. Autoriseren en beheren: de gateway controleert of de beller de MCP-service in Unity Catalog heeft EXECUTE . De service stelt alleen de hulpmiddelen beschikbaar die u hebt geselecteerd en evalueert elk gekoppeld servicebeleid, dat de aanroep kan toestaan, weigeren of goedkeuring kan vereisen.
  3. Proxy met beheerde referenties: de aanvraag wordt doorgestuurd naar de externe MCP-server via de HTTP-verbinding van de service. Azure Databricks slaat de inloggegevens op en handelt OAuth-processen en tokenvernieuwing af, zodat de agent ze nooit ziet.
  4. Logboekgebruik, controle en traceringen: elke aanroep wordt vastgelegd in systeemtabellen, zodat u gebruiks- en controleactiviteiten in de loop van de tijd kunt controleren .

Door Databricks geleverde MCP-services

Azure Databricks biedt kant-en-klare MCP-services in het system.ai schema voor algemene SaaS-toepassingen, zodat agents deze hulpprogramma's kunnen bereiken zonder uw eigen MCP-server te hosten of te registreren. Elke service is een ingebouwde MCP-service die u benadert via de Unity Catalog-naam. Om een agent toegang te geven, verleent u EXECUTE op de service (bijvoorbeeld system.ai.github). Geen verbinding nodig. Ingebouwde services worden geleverd met door het platform beheerde hulpprogramma's en een ingebouwd servicebeleid, zoals een servicebeleid om schrijfbewerkingen te blokkeren. U bepaalt deze met subsidies in plaats van met aangepaste hulpprogrammaselectie- of beleidsfuncties.

MCP-service Maakt verbinding met
system.ai.slack Slack
system.ai.github GitHub
system.ai.atlassian Jira en Confluence
system.ai.google_drive Google Drive
system.ai.google_calendar Google Agenda
system.ai.gmail Gmail
system.ai.microsoft_365 Microsoft 365 (SharePoint, Outlook en Teams)

Voor Google Drive, Gmail, Google Agenda of Microsoft 365 verwerken deze ingebouwde services OAuth voor u, zonder dat hiervoor app-registratie is vereist.

Roep een ingebouwde MCP-service aan

Adresseer een ingebouwde dienst via de Unity Gateway-URL, met de volledig gekwalificeerde naam in het pad. Gebruik de naam precies zoals hij verschijnt, met stippen en onderstreepjes, en codeer hem niet via URL:

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

Om de dienst vanuit agentcode aan te roepen, wijs je een DatabricksMCPClient of een agentframework naar deze URL. Zie MCP-servers gebruiken in Custom Agents.

Ontdek de tools van een dienst en lees de resultaten ervan

Elke MCP-dienst stelt een andere set tools beschikbaar, dus ontdek ze tijdens runtime in plaats van namen hardcodeerend. Bel tools/list (of DatabricksMCPClient.list_tools()) om de naam, beschrijving en invoerschema van elk gereedschap te verkrijgen. Zie MCP-servers gebruiken in Custom Agents.

Lees het resultaat van een tool call vanuit het result veld. De vorm hangt af van of het hulpmiddel gestructureerde output definieert:

  • Getypte uitvoer. Een tool kan een outputSchema aankondigen en een getypeerd JSON-object retourneren in structuredContent. Wanneer structuredContent aanwezig, gebruik het dan direct. Het behoeft geen ontleding. Sommige Azure Databricks-tools, zoals de Genie-tools, werken op deze manier.
  • Tekstuitvoer. Als er geen structuredContent is, lees dan in plaats daarvan de tekstblokken. Het eerste blok bevat een JSON-document, dus parse result.content[0].text als JSON.
  • Geen van beide. MCP vereist geen uitvoerschema. Wanneer een tool geen enkele definieert, inspecteer dan een voorbeeldrespons om de uitvoervelden te leren.

Bijvoorbeeld, system.ai.google_calendar biedt hulpmiddelen voor lezen, zoals calendar_event_list, waarvan het JSON-resultaat een items-array van gebeurtenissen bevat (elk met id, summary, start, end, status, location en links). De tools en resultaatstructuren van een andere dienst verschillen volledig van elkaar, dus controleer dit altijd met tools/list en een voorbeeldaanroep.

Note

Ingebouwde diensten beheren hun eigen OAuth-scopes. Een service kan standaard alleen een subset van zijn tools voor lezen beschikbaar stellen wanneer het ingebouwde servicebeleid schrijfbewerkingen blokkeert.

Een externe MCP-server registreren

Voor elke externe MCP-server die niet wordt gedekt door beheerde OAuth of de door Databricks geleverde MCP Services, registreer deze als een MCP Service om deze te beheren als een Unity Catalog securable. Zie Registreer een externe MCP-server.

Verificatie en beveiliging

Azure Databricks beheerde MCP-proxy's en HTTP-verbindingen van Unity Catalog gebruikt om verificatie veilig te verwerken voor externe MCP-servers.

  • Gedeelde principalverificatie: alle gebruikers delen dezelfde referenties bij het openen van de externe service. Dit omvat Bearer-token, OAuth Machine-to-Machine (M2M) en OAuth User-to-Machine gedeelde authenticatie. Gebruik deze optie wanneer voor de externe service geen gebruikersspecifieke toegang is vereist of wanneer één serviceaccount voldoende is.
  • Verificatie per gebruiker (OAuth U2M Per gebruiker):elke gebruiker wordt geverifieerd met hun eigen referenties. De externe service ontvangt aanvragen namens de afzonderlijke gebruiker, waardoor gebruikersspecifiek toegangsbeheer, controle en verantwoordelijkheid mogelijk zijn. Gebruik deze optie bij het openen van gebruikersspecifieke resources, zoals de GitHub opslagplaatsen van een gebruiker, Slack-berichten of agenda.

Azure Databricks verwerkt OAuth-stromen en tokenvernieuwing, zodat eindgebruikers geen tokens zien. Je bekijkt en beheert je externe MCP-verbindingen samen met je LLM-endpoints vanuit Unity Gateway. Zie HTTP-verbindingen voor gedetailleerde configuratie-instructies voor elke verificatiemethode.

Schakel toegang op gebruikersniveau in (toegang namens de gebruiker)

Sommige diensten lezen gegevens die toebehoren aan een specifieke gebruiker, zoals hun agenda of e-mail. Voor deze diensten gebruik je per-user OAuth zodat elke oproep draait als de gebruiker die het heeft gemaakt, niet als een gedeelde identiteit. Dit geldt voor system.ai.* ingebouwde diensten zoals system.ai.google_calendar, system.ai.gmail en system.ai.microsoft_365, en voor externe diensten die je registreert met authenticatie per gebruiker.

Toegang namens een agent instellen:

  1. Zorg ervoor dat de roepende gebruiker de dienst kan oproepen. Het aanroepen van een MCP-dienst vereist twee dingen:

    • EXECUTE op de service.
    • USE CATALOG en USE SCHEMA op de hoofdcatalogus en het schema. EXECUTE alleen is niet genoeg, want Unity Catalog controleert ook de ouderketen (zie Toegang verlenen aan teamgenoten).

    Hoe je deze toekent hangt af van de dienst:

    • Ingebouwde system.ai.* diensten: Accountgebruikers hebben deze privileges standaard al aan system en system.ai bij voorkeur, dus je hoeft meestal niets toe te kennen.
    • Aangepaste diensten in uw eigen catalogus en schema: Verleen de aanroepende gebruiker of groep de juiste rechten (niet alleen de serviceprincipal van de app) via het tabblad Rechten van elke securable in Catalog Explorer, of met de REST API. SQL DDL is niet beschikbaar voor MCP Services.

    Om toegang te verlenen met de REST API, vervang je <catalog>.<schema>.<service> door je eigen:

    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. Voeg de ai-gateway gebruikers-API-scope toe aan je app zodat het doorgestuurde gebruikerstoken de service kan bereiken. Declareer user_api_scopes: [ai-gateway] op de app-resource en roep de service aan met de per-user client (get_user_workspace_client()). Zie Verifiëren bij MCP-services en Een agent maken en implementeren op Databricks Apps.

  3. Elke gebruiker geeft één keer toestemming. De eerste keer dat een gebruiker de dienst oproept, moet hij of zij een eenmalige OAuth-login uitvoeren. Je app ontvangt een inloglink om de gebruiker te tonen, of de gebruiker kan de dienst openen in Catalogusverkenner en op Inloggen klikken.

Note

Je kunt deze EXECUTE toegang niet via een bundel geven. Een Declarative Automation Bundles-resource uc_securable ondersteunt alleen de beveiligbare objecten VOLUME, TABLE, FUNCTION en CONNECTION, niet MCP Services, dus moet je EXECUTE afzonderlijk toekennen via de UI of de bovenstaande REST API. Let op: databricks bundle validate markeert de ontbrekende machtiging niet, waardoor de agent probleemloos kan worden uitgerold en pas faalt wanneer deze de service voor het eerst aanroept.

Limitations

De volgende beperkingen gelden voor MCP-diensten:

  • SQL DDL voor MCP-services (bijvoorbeeld CREATE MCP SERVICE) is niet beschikbaar. Maak en beheer MCP-services met de gebruikersinterface of de REST API.
  • U kunt alleen externe MCP-servers registreren als uw eigen MCP-service. Het registreren van genie-, apps- of Unity Catalog-entiteitsbronnen als een MCP-service wordt momenteel niet ondersteund. Azure Databricks biedt ook ingebouwde MCP-services voor algemene SaaS-apps.
  • Het selecteren van hulpprogramma's ondersteunt prefixpatronen (get_*) en exacte-matchpatronen. Uitsluitingspatronen (bijvoorbeeld !delete_*) worden niet ondersteund.
  • Global Search in Unity Catalog biedt geen MCP-services.

Externe MCP-serververbindingen hebben ook de volgende beperkingen:

Volgende stappen 

  • Last updated on