Register an external MCP server

Beta

This feature is in Beta. Account admins can control access to this feature from the account console Previews page. See Manage Databricks previews.

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.
• The Unity AI Gateway Beta and the Managed MCP Servers preview enabled for your account. See Manage Databricks previews.

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

Register an external MCP server

Register your own external MCP server as an MCP Service in five steps:

1. Create a Unity Catalog connection to the MCP server.
2. Create the MCP Service from that connection.
3. Authenticate, if the connection uses per-user OAuth.
4. Grant access to your teammates.
5. 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. 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:

1. Go to Catalog > Connections > Create connection.
2. Select HTTP as the connection type.
3. Enter the MCP server URL.
4. 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—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 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 Beta does not support SQL DDL for MCP Services.

UI

1. In your Databricks workspace, go to AI Gateway > MCPs > Register MCP Server, or go to Catalog, select a schema, and click Create > MCP Service.
2. Enter the catalog, schema, and a name for the MCP Service. The name can't be changed after creation.
3. 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.
4. Under Tools, select which tools to make available. See Select which tools are exposed.
5. Optionally, add a comment that describes the MCP Service.
6. Click Create. The MCP Service is published to the catalog and schema you specified.

REST API

Create an MCP Service that references an existing Unity Catalog HTTP connection. Set parent to the target schema and mcp_service_id to the service name:

Bash

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 controls which tools the service exposes. An empty list exposes all tools. See Select which tools are exposed.

Update an existing MCP Service with a PATCH request and an update_mask that names the fields to change:

Bash

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

Step 3. Authenticate

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

1. Open the MCP Service detail page in Catalog Explorer.
2. Click Login and complete the provider's OAuth consent flow.
3. 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.

Step 4. Grant access to teammates

By default, only the MCP Service owner can invoke it. Grant EXECUTE to let other users, groups, or service principals invoke the service. A single EXECUTE grant covers all of the service's tools.

UI

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

REST API

Bash

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.

Test the MCP Service

AI Playground

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

1. Go to AI Playground in your Databricks workspace.
2. Select a model with the Tools enabled label.
3. Click Tools > + Add tool and select MCP Servers.
4. Select External MCP servers, then select the MCP Service.
5. 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 generated request on the MCP Service detail page. In Get started, click Generate Access Token to copy an access token into the request examples. The examples pass the token as a bearer token in the Authorization header.

You can also authenticate the Databricks CLI to your workspace, then use databricks auth token to get an OAuth access token:

Bash

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:

Bash

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:

Bash

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 agents.
• AI assistants and coding agents (Claude, Claude Code, Cursor): see Connect MCPs to AI assistants and coding agents.

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.
• AI governance with Unity AI Gateway to govern MCP servers and LLM endpoints from a central location.