Connect agents to third-party tools with MCP Services

An MCP Service is a Unity Catalog securable that registers an external MCP server and governs how agents use it. You address it by its three-level name, catalog.schema.mcp_service, and invoke it through Unity AI Gateway, the control plane for governing AI traffic.

Registering an MCP server as a Unity Catalog securable means you manage it with the same primitives that protect your other Unity Catalog assets. These include grants to control who can invoke it, tool selection to limit which tools it exposes, service policies to allow or deny individual tool calls, and audit and usage logging to track every invocation.

There are two ways to use MCP Services:

Requirements

• A workspace enabled for Unity Catalog.

• A workspace in a region where Model Serving is supported. See Model serving features availability.

How it works

An agent calls an MCP Service by its Unity AI Gateway URL, and every call flows through the same governed path:

1. Invoke: The agent sends an MCP request to the service's Unity AI Gateway URL, authenticated with the caller's Azure Databricks identity.
2. Authorize and govern: The gateway checks that the caller has EXECUTE on the MCP Service in Unity Catalog. The service exposes only the tools you selected and evaluates any attached service policy, which can allow, deny, or require approval for the call.
3. Proxy with managed credentials: The request is forwarded to the external MCP server through the service's HTTP connection. Azure Databricks stores the credentials and handles OAuth flows and token refresh, so the agent never sees them.
4. Log usage, audit, and traces: Every invocation is recorded in system tables, so you can monitor usage and audit activity over time.

Databricks-provided MCP Services

Azure Databricks provides ready-to-use MCP Services in the system.ai schema for common SaaS applications, so agents can reach these tools without hosting or registering your own MCP server. Each one is a built-in MCP Service that you address by its Unity Catalog name. To give an agent access, grant EXECUTE on the service (for example, system.ai.github). No connection setup required. Built-in services ship with platform-managed tools and a built-in service policy, such as one to block write operations. You govern them with grants rather than with custom tool selection or policy functions.

For Google Drive, Gmail, Google Calendar, or Microsoft 365, these built-in services handle OAuth for you, with no app registration required.

Invoke a built-in MCP Service

Address a built-in service by its Unity AI Gateway URL, with the fully qualified name in the path. Use the name exactly as it appears, with its dots and underscores, and don't URL-encode it:

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

To call the service from agent code, point a DatabricksMCPClient or an agent framework at this URL. See Use MCP servers in Custom Agents.

Discover a service's tools and read its results

Every MCP Service exposes a different set of tools, so discover them at runtime instead of hardcoding names. Call tools/list (or DatabricksMCPClient.list_tools()) to get each tool's name, description, and input schema. See Use MCP servers in Custom Agents.

Read a tool call's result from the result field. Its shape depends on whether the tool defines structured output:

• Typed output. A tool can advertise an outputSchema and return a typed JSON object in structuredContent. When structuredContent is present, use it directly. It needs no parsing. Some Azure Databricks tools, such as the Genie tools, work this way.
• Text output. When there is no structuredContent, read the text blocks instead. The first block holds a JSON document, so parse result.content[0].text as JSON.
• Neither. MCP does not require an output schema. When a tool defines none, inspect a sample response to learn its output fields.

For example, system.ai.google_calendar exposes read tools such as calendar_event_list, whose JSON result has an items array of events (each with id, summary, start, end, status, location, and links). A different service's tools and result shapes differ entirely, so always confirm with tools/list and a sample call.

Register an external MCP server

For any external MCP server not covered by managed OAuth or the Databricks-provided MCP Services, register it as an MCP Service to govern it as a Unity Catalog securable. See Register an external MCP server.

Authentication and security

Azure Databricks uses managed MCP proxies and Unity Catalog HTTP connections to securely handle authentication to external MCP servers.

• Shared principal authentication: All users share the same credentials when accessing the external service. This includes Bearer token, OAuth Machine-to-Machine (M2M), and OAuth User-to-Machine Shared authentication. Use this when the external service doesn't require user-specific access, or when a single service account is sufficient.
• Per-user authentication (OAuth U2M Per User): Each user authenticates with their own credentials. The external service receives requests on behalf of the individual user, enabling user-specific access control, auditing, and accountability. Use this when accessing user-specific resources, such as a user's GitHub repositories, Slack messages, or calendar.

Azure Databricks handles OAuth flows and token refresh, so end users don't see tokens. You view and manage your external MCP connections alongside your LLM endpoints from Unity AI Gateway. For detailed configuration instructions for each authentication method, see HTTP connections.

Enable per-user access (on-behalf-of-user access)

Some services read data that belongs to a specific user, such as their calendar or email. For these services, use per-user OAuth so each call runs as the user who made it, not as a shared identity. This applies to built-in system.ai.* services like system.ai.google_calendar, system.ai.gmail, and system.ai.microsoft_365, and to external services you register with per-user auth.

To set up on-behalf-of access from an agent:

1. Make sure the calling user can invoke the service. Invoking any MCP Service requires two things:

   • EXECUTE on the service.
   • USE CATALOG and USE SCHEMA on its parent catalog and schema. EXECUTE alone is not enough, because Unity Catalog also checks the parent chain (see Grant access to teammates).

   How you grant these depends on the service:

   • Built-in system.ai.* services: Account users already hold these privileges on system and system.ai by default, so you usually don't need to grant anything.
   • Custom services in your own catalog and schema: Grant the calling user or group the appropriate permissions (not only the app's service principal) from each securable's Permissions tab in Catalog Explorer, or with the REST API. SQL DDL is not available for MCP Services.

   To grant with the REST API, substitute your own <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. Add the ai-gateway user API scope to your app so the forwarded user token can reach the service. Declare user_api_scopes: [ai-gateway] on the app resource, and call the service with the per-user client (get_user_workspace_client()). See Authenticate to MCP Services and Author an agent and deploy it on Databricks Apps.

3. Each user consents once. The first time a user calls the service, they must complete a one-time OAuth login. Your app receives a login link to show the user, or the user can open the service in Catalog Explorer and click Login.

Limitations

The following limitations apply to MCP Services:

• SQL DDL for MCP Services (for example, CREATE MCP SERVICE) is not available. Create and manage MCP Services with the UI or the REST API.
• You can register only external MCP servers as your own MCP Service. Registering Genie, Apps, or Unity Catalog entity sources as an MCP Service is not currently supported. Azure Databricks also provides built-in MCP Services for common SaaS apps.
• Tool selection supports prefix (get_*) and exact-match patterns. Exclusion patterns (for example, !delete_*) are not supported.
• Unity Catalog Global Search does not surface MCP Services.

External MCP server connections also have the following limitations:

• External MCP servers are only available in regions where Model Serving is supported, including use in AI Playground, Genie Code, and Chat in Genie. See Model serving features availability.

Next steps

• Register an external MCP server to register and invoke an external MCP server.
• Govern an MCP service to restrict tools and apply service policies.
• Use MCP servers in Custom Agents to call an MCP Service programmatically from agent code, with examples for the OpenAI Agents SDK, LangGraph, and Model Serving.
• Connect MCPs to AI assistants and coding agents to connect coding agents and AI assistants.
• AI governance with Unity AI Gateway to govern MCP servers and LLM endpoints from a central location.