MCP API and SDK reference

Use these examples to automate MCP setup. The API represents each MCP as an McpService resource. For the workspace UI, see External MCP servers. For access controls and policies, see Govern an MCP.

Prerequisites

Replace main.default.my_mcp, the connection name, and data-team with your own values. Creating MCPs with SQL commands such as CREATE MCP SERVICE isn't supported.

API operations

The MCP REST API provides these operations. Follow each link for its fields, permissions, and responses.

Operation Use it to
Create Register an MCP server through an HTTP connection.
List Find MCPs you can access in a schema.
Get Read an MCP's configuration and current etag.
Update Change the comment, connection, tool selection, or rate limits.
Delete Remove a registered MCP.
Sign in Sign in or re-authenticate the caller with the provider.
Check sign-in Read the caller's provider login state.
Sign out Revoke the caller's provider credential.

To discover and call tools, use an MCP client with the MCP URL, https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>. These management APIs use the unity-catalog OAuth scope. MCP tool calls use ai-gateway.

Create a connection

Create a schema-level HTTP connection to your MCP server. These examples connect to https://mcp.example.com/mcp with a bearer token. For OAuth and other authentication settings, see HTTP connection settings.

For REST or CLI, save this request as connection.json, replacing the URL and token with your server's values. Keep this credential file out of source control.

{
  "name": "my_connection",
  "parent": "schemas/main.default",
  "connection_type": "HTTP",
  "options": {
    "host": "https://mcp.example.com",
    "port": "443",
    "base_path": "/mcp",
    "bearer_token": "<mcp-server-token>"
  }
}

REST API

Send the request to the Connections API:

databricks api post /api/2.1/unity-catalog/connections --json @connection.json

CLI

databricks connections create --json @connection.json

Python SDK

Make the server's bearer token available in the MCP_SERVER_TOKEN environment variable.

import os
from databricks.sdk import WorkspaceClient
from databricks.sdk.service import catalog as c

w = WorkspaceClient()

connection = w.connections.create(
    name="my_connection",
    parent="schemas/main.default",
    connection_type=c.ConnectionType.HTTP,
    options={
        "host": "https://mcp.example.com",
        "port": "443",
        "base_path": "/mcp",
        "bearer_token": os.environ["MCP_SERVER_TOKEN"],
    },
)

The connection's full name is main.default.my_connection. Reference it as connections/main.default.my_connection when creating the MCP below. If the connection already exists, use its name and skip this step.

Create an MCP

The MCP references an existing HTTP connection. To limit the tools it exposes, configure tool selection.

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 identifies the Unity Catalog HTTP connection to the MCP server. Set include_tool_selectors to restrict tools, or omit it to expose all tools. See Choose available tools.

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

Pass the parent schema and MCP name, and supply the configuration with --json. Set include_tool_selectors to restrict tools, or omit it to expose all tools.

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 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"
    }
  }
}

Bundles (Beta)

Define the MCP in a bundle and deploy it with databricks bundle deploy. MCP resources require Databricks CLI version 1.17.0 and above and the direct deployment engine.

resources:
  mcp_services:
    my_mcp:
      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 with the Databricks SDK for Python:

from databricks.sdk import WorkspaceClient
from databricks.sdk.service import catalog as c

w = WorkspaceClient()

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 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",
			},
		},
	},
})

Go Modular SDK

Create and manage an MCP Service with the Databricks AI Gateway SDK for Go. Optional fields are pointers, so the example uses a one-line helper, func ptr[T any](v T) *T { return &v }.

mcpService, err := c.CreateMcpService(ctx, aigateway.CreateMcpServiceRequest{
	Parent:       ptr("schemas/main.default"),
	McpServiceId: ptr("my_mcp"),
	McpService: &aigateway.McpService{
		Comment: ptr("External MCP server"),
		Config: &aigateway.McpServiceConfig{
			Source: &aigateway.McpServiceConfig_Source_SourceConnection{
				SourceConnection: aigateway.McpServiceConfig_SourceConnection{
					Name: ptr("connections/main.default.my_connection"),
				},
			},
		},
	},
})

Java SDK

Create and manage an MCP 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 Modular SDK

Create and manage an MCP with the JavaScript SDK:

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' },
      },
    },
  },
});

Find an MCP

List the MCPs you can access in a schema, then get an MCP's configuration by its resource name. For built-in MCPs, use schemas/system.ai as the parent.

REST API

databricks api get \
  "/api/2.1/unity-catalog/mcp-services?parent=schemas/main.default&view=FULL"

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

When the list response includes next_page_token, pass it as page_token in the next request. Continue until next_page_token is absent or empty.

CLI

databricks ai-gateway list-mcp-services --parent schemas/main.default --view FULL

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

Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service import catalog as c

w = WorkspaceClient()

for service in w.ai_gateway.list_mcp_services(
    parent="schemas/main.default",
    view=c.ListMcpServicesRequestView.FULL,
):
    print(service.name)

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

List responses use BASIC view by default, which omits source-connection details and rate-limit principal names. Use FULL to include those fields. The CLI and Python iterator handle pagination for you.

Grant access

These examples grant EXECUTE on the MCP. For the full access requirements, including parent permissions, see Share an MCP.

REST API

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

CLI

Grant EXECUTE with the Databricks CLI:

databricks grants update mcp_service main.default.my_mcp \
  --json '{"changes": [{"principal": "data-team", "add": ["EXECUTE"]}]}'

Terraform

Grant EXECUTE with the Databricks Terraform provider and the databricks_grant resource:

resource "databricks_grant" "example" {
  mcp_service = "main.default.my_mcp"
  principal   = "data-team"
  privileges  = ["EXECUTE"]
}

Bundles (Beta)

Add a grants block to the MCP resource in your bundle and redeploy to grant access.

resources:
  mcp_services:
    my_mcp:
      parent: schemas/main.default
      mcp_service_id: my_mcp
      comment: External MCP server
      config:
        source_connection:
          name: connections/main.default.my_connection
      grants:
        - principal: data-team
          privileges: [EXECUTE]

Python SDK

Grant EXECUTE with the Databricks SDK for Python:

from databricks.sdk.service import catalog as c

w.grants.update(
    securable_type="mcp_service",
    full_name="main.default.my_mcp",
    changes=[c.PermissionsChange(principal="data-team", add=[c.Privilege.EXECUTE])],
)

Go SDK

Grant EXECUTE with the Databricks SDK for Go:

_, err := w.Grants.Update(ctx, catalog.UpdatePermissions{
	SecurableType: "mcp_service",
	FullName:      "main.default.my_mcp",
	Changes: []catalog.PermissionsChange{{
		Principal: "data-team",
		Add:       []catalog.Privilege{catalog.PrivilegeExecute},
	}},
})

Java SDK

Grant EXECUTE with the Databricks SDK for Java:

w.grants().update(
    new UpdatePermissions()
        .setSecurableType("mcp_service")
        .setFullName("main.default.my_mcp")
        .setChanges(Arrays.asList(
            new PermissionsChange().setPrincipal("data-team").setAdd(Arrays.asList(Privilege.EXECUTE)))));

Manage provider sign-in

For MCPs that use per-user OAuth, each caller signs in to the external provider. For interactive sign-in, follow External services setup.

The credential APIs are in Beta. To integrate them into your own OAuth flow:

  1. Create the caller's credential with the OAuth exchange fields: authorization_code, pkce_verifier, and oauth_redirect_uri.
  2. Check the credential status. provisioning_info.state must be ACTIVE before the credential is usable. NOT_FOUND means the caller has no credential yet.
  3. To sign out, delete the caller's credential.

These operations manage the calling user's credential. The caller needs access to the MCP.

Update an MCP

These examples update the MCP comment. The MCP name cannot be changed.

Set update_mask to the fields you want to change, such as comment, config.source_connection.name, config.include_tool_selectors, or config.rate_limits. Using config replaces the whole configuration and clears omitted optional fields. When changing the connection, the MCP owner also needs USE CONNECTION on the new connection.

For a conditional update, first get the MCP and pass its etag with the update. The update succeeds only if the MCP hasn't changed since that read. URL-encode the etag when adding it to a REST query string.

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.

Bundles (Beta)

Edit comment (or any other mutable field) in the bundle resource and run databricks bundle deploy. Changes apply in place.

Python SDK

from databricks.sdk.service import catalog as c
from databricks.sdk.common.types.fieldmask import FieldMask

updated = w.ai_gateway.update_mcp_service(
    name="mcp-services/main.default.my_mcp",
    update_mask=FieldMask(["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"},
})

Go Modular SDK

mask, err := types.NewFieldMask[aigateway.McpService]("comment")
updated, err := c.UpdateMcpService(ctx, aigateway.UpdateMcpServiceRequest{
	McpService: &aigateway.McpService{
		Name:    ptr("mcp-services/main.default.my_mcp"),
		Comment: ptr("Updated: governs an MCP server"),
	},
	UpdateMask: mask,
})

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 Modular 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'),
});

Example: update tool selection

To expose only tools whose names start with get_:

databricks api patch \
  "/api/2.1/unity-catalog/mcp-services/main.default.my_mcp?update_mask=config.include_tool_selectors" \
  --json '{
    "config": {
      "include_tool_selectors": ["get_*"]
    }
  }'

An empty include_tool_selectors list exposes all tools. See Choose available tools for the UI steps.

Delete an MCP

Delete only the MCP you intend to remove. Clients configured with its URL can no longer call it.

You can also pass the MCP's current etag to make deletion conditional on it not having changed since the last read. URL-encode the etag in REST query strings.

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

Remove the MCP resource from your configuration and run terraform apply. Review the plan before applying it.

Bundles (Beta)

Remove the MCP resource from the bundle and run databricks bundle deploy. Review the deployment changes before applying them.

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",
})

Go Modular SDK

err := c.DeleteMcpService(ctx, aigateway.DeleteMcpServiceRequest{
	Name: ptr("mcp-services/main.default.my_mcp"),
})

Java SDK

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

JS Modular SDK

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

Additional resources

  • Last updated on