Register an external MCP server

This page describes how to register a self-hosted or third-party MCP server as an MCP Service in Unity Catalog, then invoke it from AI Playground, the command line, or your agent code. Registering the server as a Unity Catalog securable lets Unity AI Gateway proxy every call with managed credentials, so agents never handle the server's tokens. To restrict which tools the service exposes and govern individual calls, see Govern an MCP service.

For a ready-to-use SaaS tool with no server to host, use a Databricks-provided MCP Service instead.

Requirements

A workspace enabled for Unity Catalog.

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

Register an external MCP server

Create a Unity Catalog connection to the MCP server.
Create the MCP Service from that connection.
Authenticate, if the connection uses per-user OAuth.
Grant access to your teammates.
Invoke the service, then govern it with tool selection and service policies.

The external MCP server must use the Streamable HTTP transport mechanism. You need these permissions:

To create the connection, CREATE CONNECTION on the schema where you create it.
To create an MCP Service, USE CATALOG and USE SCHEMA on the parent catalog and schema, CREATE SERVICE on the schema, and USE CONNECTION on the connection that the MCP Service references.
To invoke an MCP Service, EXECUTE on the MCP Service, USE CATALOG and USE SCHEMA on its parent catalog and schema, and assignment to the workspace where you issue the request.

Warning

Invoking an MCP Service requires no privilege on the underlying connection—EXECUTE on the MCP Service is sufficient. Don't grant USE CONNECTION to end users: it lets them call the external server directly through the connection, or register their own MCP Service on it, bypassing the tool selection, service policies, and auditing of your MCP Service. Reserve connection access for service authors and administrators.

Step 1. Create a connection

An MCP Service references a Unity Catalog HTTP connection that securely stores the external server's endpoint and credentials. Azure Databricks runs a managed proxy in front of it to handle authentication and token refresh, so you don't embed credentials in your agent or client code.

Create the connection at the schema level so it's governed alongside the MCP Service. You can set it up ahead of time with the steps below, or create one while you create the MCP Service by clicking Create new connection. Metastore-level connections are supported but not recommended.

Choose one of two ways:

Create an HTTP connection

For any MCP server, including self-hosted or third-party servers:

Go to Catalog > Connections > Create connection.
Select HTTP as the connection type.
Enter the MCP server URL.
Choose an authentication type: bearer token, OAuth M2M, OAuth U2M, or Dynamic Client Registration. For setup details, see Create a connection to the external service.

For managed-OAuth providers—Glean, GitHub, Atlassian, and Slack—Azure Databricks manages the credentials, so you don't register your own OAuth app. See Managed OAuth providers.

Install from Marketplace

Use a curated MCP server from Azure Databricks Marketplace with a pre-configured connection. See Get access to external MCP servers.

Step 2. Create the MCP Service

You can create an MCP Service from the UI or with the REST API, the Azure Databricks CLI, the Azure Databricks SDKs, or Terraform. SQL DDL for MCP Services is not supported.

UI

In your Azure Databricks workspace, go to AI Gateway > MCPs > Register MCP Server, or go to Catalog, select a schema, and click Create > MCP Service.
Enter the catalog, schema, and a name for the MCP Service. The name can't be changed after creation.
Select an existing HTTP connection to the MCP server, or click Create new connection to create one. Browse under a schema to select a schema-level connection; to use a metastore-level connection, turn off Browse under a schema.
Under Tools, select which tools to make available. See Select which tools are exposed.
Optionally, add a comment that describes the MCP Service.
Click Create. The MCP Service is published to the catalog and schema you specified.

REST API

Send a POST to /api/2.1/unity-catalog/mcp-services, passing parent and mcp_service_id as query parameters. config.source_connection.name is the Unity Catalog HTTP connection that hosts the MCP server. To restrict which tools the service exposes, add an include_tool_selectors allowlist; omit it to expose all tools. See Select which tools are exposed.

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": {
    "source_connection": {
      "name": "connections/main.default.my_connection"
    }
  }
}'

CLI

Create an MCP Service that references an existing Unity Catalog HTTP connection. Pass the parent schema and a leaf name, and supply the config with --json. To restrict which tools the service exposes, add an include_tool_selectors allowlist; omit it to expose all tools. To install the CLI, see Install or update the Databricks CLI.

databricks ai-gateway create-mcp-service schemas/main.default my_mcp --json '{
  "comment": "External MCP server",
  "config": {
    "source_connection": {
      "name": "connections/main.default.my_connection"
    }
  }
}'

Terraform

Create and manage an MCP Service with the Databricks Terraform provider and the databricks_ai_gateway_mcp_service resource:

resource "databricks_ai_gateway_mcp_service" "example" {
  parent         = "schemas/main.default"
  mcp_service_id = "my_mcp"
  comment        = "External MCP server"

  config = {
    source_connection = {
      name = "connections/main.default.my_connection"
    }
  }
}

Python SDK

Create and manage an MCP Service with the Databricks SDK for Python:

from databricks.sdk.service import catalog as c

mcp_service = w.ai_gateway.create_mcp_service(
    parent="schemas/main.default",
    mcp_service_id="my_mcp",
    mcp_service=c.McpService(
        comment="External MCP server",
        config=c.McpServiceConfig(
            source_connection=c.McpServiceConfigSourceConnection(
                name="connections/main.default.my_connection"
            ),
        ),
    ),
)

Go SDK

Create and manage an MCP Service with the Databricks SDK for Go:

mcpService, err := w.AiGateway.CreateMcpService(ctx, catalog.CreateMcpServiceRequest{
	Parent:       "schemas/main.default",
	McpServiceId: "my_mcp",
	McpService: catalog.McpService{
		Comment: "External MCP server",
		Config: &catalog.McpServiceConfig{
			SourceConnection: &catalog.McpServiceConfigSourceConnection{
				Name: "connections/main.default.my_connection",
			},
		},
	},
})

Java SDK

Create and manage an MCP Service with the Databricks SDK for Java:

McpService mcpService =
    w.aiGateway()
        .createMcpService(
            new CreateMcpServiceRequest()
                .setParent("schemas/main.default")
                .setMcpServiceId("my_mcp")
                .setMcpService(
                    new McpService()
                        .setComment("External MCP server")
                        .setConfig(
                            new McpServiceConfig()
                                .setSourceConnection(
                                    new McpServiceConfigSourceConnection()
                                        .setName("connections/main.default.my_connection")))));

JS SDK

Create and manage an MCP Service with the Databricks AI Gateway SDK for JavaScript:

const created = await client.createMcpService({
  parent: 'schemas/main.default',
  mcpServiceId: 'my_mcp',
  mcpService: {
    comment: 'External MCP server',
    config: {
      source: {
        $case: 'sourceConnection',
        sourceConnection: { name: 'connections/main.default.my_connection' },
      },
    },
  },
});

Step 3. Authenticate

If the MCP Service references a connection that uses per-user OAuth, complete a one-time login before the first call:

Open the MCP Service detail page in Catalog Explorer.
Click Login and complete the provider's OAuth consent flow.
After you sign in, the detail page automatically shows the list of discovered tools.

Unity Catalog stores the token against your identity. If you call the MCP Service before logging in, AI Gateway returns an error prompting you to authenticate.

Note

Users with Consumer access can't use the per-user OAuth login, which requires Workspace access. See Manage entitlements.

By default, only the MCP Service owner can invoke it. To let others invoke an MCP Service, grant them EXECUTE on it, plus USE CATALOG and USE SCHEMA on its catalog and schema. A single EXECUTE grant covers all of the service's tools.

UI

Open the MCP Service in Catalog Explorer, or go to AI Gateway > MCPs and select the service.
Go to the Permissions tab.
Click Grant.
Select the users, groups, or service principals to give access to.
Select the EXECUTE privilege.
Click Grant.

REST API

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

Step 5. Invoke an MCP Service

Try an MCP Service in AI Playground, from the command line, or from your agent or client code.

Note

Users with Consumer access can invoke an MCP Service shared with them but cannot register an MCP Service. See Manage entitlements.

Test the MCP Service

AI Playground

Test an MCP Service's tools in the UI without writing code:

Go to AI Playground in your Azure Databricks workspace.
Select a model with the Tools enabled label.
Click Tools > + Add tool and select MCP Servers.
Select External MCP servers, then select the MCP Service.
Chat with the model to see how it calls the MCP Service's tools.

You can also test from Genie Code — see Add MCP servers to the Assistant.

CURL

For a quick command-line check, use the request examples on the MCP Service detail page under Get started. The examples pass the token as a bearer token in the Authorization header.

Authenticate the Databricks CLI to your workspace, then use databricks auth token to get an OAuth access token:

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

All requests go to the same MCP Service endpoint—the JSON-RPC method in the request body selects the operation. List the tools the service exposes:

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":{}}'

Call a tool:

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":{}}}'

Use from agent code or a coding agent

Agent code (OpenAI Agents SDK, LangGraph, or Model Serving): see Use MCP servers in Custom Agents.
AI assistants and coding agents (Claude, Claude Code, Cursor): see Connect MCPs to AI assistants and coding agents.

Manage an MCP Service

Update an MCP Service

You must be an owner or have MANAGE.

UI

Edit the MCP Service's configuration from the Unity AI Gateway UI or Catalog Explorer. Changes apply in place.

REST API

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

CLI

databricks ai-gateway update-mcp-service mcp-services/main.default.my_mcp comment \
  --json '{"comment": "Updated: governs an MCP server"}'

Terraform

Edit comment (or any other mutable field) on the databricks_ai_gateway_mcp_service resource and re-apply. Changes apply in place.

Python SDK

from databricks.sdk.service import catalog as c
from google.protobuf.field_mask_pb2 import FieldMask

updated = w.ai_gateway.update_mcp_service(
    name="mcp-services/main.default.my_mcp",
    update_mask=FieldMask(paths=["comment"]),
    mcp_service=c.McpService(comment="Updated: governs an MCP server"),
)

Go SDK

updated, err := w.AiGateway.UpdateMcpService(ctx, catalog.UpdateMcpServiceRequest{
	Name:       "mcp-services/main.default.my_mcp",
	UpdateMask: *fieldmask.New([]string{"comment"}),
	McpService: catalog.McpService{Comment: "Updated: governs an MCP server"},
})

Java SDK

McpService updated =
    w.aiGateway()
        .updateMcpService(
            new UpdateMcpServiceRequest()
                .setName("mcp-services/main.default.my_mcp")
                .setUpdateMask(FieldMask.newBuilder().addPaths("comment").build())
                .setMcpService(new McpService().setComment("Updated: governs an MCP server")));

JS SDK

import { mcpServiceFieldMask } from '@databricks/sdk-aigateway/v1';

const updated = await client.updateMcpService({
  mcpService: {
    name: 'mcp-services/main.default.my_mcp',
    comment: 'Updated: governs an MCP server',
  },
  updateMask: mcpServiceFieldMask('comment'),
});

Delete an MCP Service

You must be an owner or have MANAGE.

UI

Open the MCP Service in the Unity AI Gateway UI or Catalog Explorer and select Delete from the kebab menu.

REST API

databricks api delete "/api/2.1/unity-catalog/mcp-services/main.default.my_mcp"

CLI

databricks ai-gateway delete-mcp-service mcp-services/main.default.my_mcp

Terraform

Run terraform destroy, or remove the resource block and re-apply.

Python SDK

w.ai_gateway.delete_mcp_service(name="mcp-services/main.default.my_mcp")

Go SDK

err := w.AiGateway.DeleteMcpService(ctx, catalog.DeleteMcpServiceRequest{
	Name: "mcp-services/main.default.my_mcp",
})

Java SDK

w.aiGateway().deleteMcpService(new DeleteMcpServiceRequest().setName("mcp-services/main.default.my_mcp"));

JS SDK

await client.deleteMcpService({ name: 'mcp-services/main.default.my_mcp' });

Next steps

Govern an MCP service to restrict which tools the service exposes and apply service policies.
Connect agents to third-party tools with MCP Services for an overview of MCP Services and Databricks-provided services.
Monitor all AI activity using the unified trace table to monitor, debug, and audit all MCP activity from one place.
AI governance with Unity AI Gateway to govern MCP servers and LLM endpoints from a central location.

Tilbakemeldinger

Var denne siden nyttig?

Last updated on 2026-08-31

Register an external MCP server

Requirements

Register an external MCP server

Step 1. Create a connection

Create an HTTP connection

Install from Marketplace

Step 2. Create the MCP Service

UI

REST API

CLI

Terraform

Python SDK

Go SDK

Java SDK

JS SDK

Step 3. Authenticate

Step 4. Grant access to an MCP Service

UI

REST API

Step 5. Invoke an MCP Service

Test the MCP Service

AI Playground

CURL

Use from agent code or a coding agent

Manage an MCP Service

Update an MCP Service

UI

REST API

CLI

Terraform

Python SDK

Go SDK

Java SDK

JS SDK

Delete an MCP Service

UI

REST API

CLI

Terraform

Python SDK

Go SDK

Java SDK

JS SDK

Next steps

Tilbakemeldinger

Flere ressurser