Use external MCP servers

Preview

This feature is in Public Preview.

Connect agents to third-party Model Context Protocol (MCP) servers through Databricks-managed proxies to access external tools and services.

Databricks supports both shared principal and per-user authentication for external MCP servers. See Supported authentication methods.

Requirements

• A workspace with the Managed MCP Servers preview enabled. See Manage Databricks previews.
• You must have CREATE CONNECTION privilege on the Unity Catalog metastore that stores the MCP connection information.
• The MCP server must use the Streamable HTTP transport mechanism.

Install an external MCP server

You have four options for installing external MCP servers to use with your agents. Start with Managed OAuth if your MCP provider is supported since it requires no credential management. If not, check Databricks Marketplace for a pre-built integration. For any other server, use a Custom HTTP connection. All methods create a Unity Catalog connection for secure, authenticated access.

Choose your installation method based on your MCP server:

Managed OAuth (recommended)

Databricks provides managed OAuth flows for select services, eliminating the need to register your own OAuth app or manage credentials. Databricks recommends Managed OAuth for development and testing. If production use cases require generating custom OAuth credentials, see the providers' documentation for more information.

The following integrations use Databricks-managed OAuth credentials stored securely in the backend.

Provider	Configuration notes	Supported scopes	Description
Glean MCP	Requires Host. Base path is configurable (defaults to /mcp/default).	mcp	Access Glean enterprise search, chat, documents, and agent tools.
GitHub MCP	None	repo read:project read:org	Access GitHub repositories, organizations, and project data.
Google Drive API	None	https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/documents.readonly https://www.googleapis.com/auth/spreadsheets.readonly offline_access	Read-only access to Google Drive files.
SharePoint API	None	https://graph.microsoft.com/Sites.Read.All offline_access openid profile	Read-only access to SharePoint sites.

To set up managed OAuth:

1. In your Databricks workspace, go to Catalog > Connections > Create connection.
2. Select HTTP as the connection type.
3. Select OAuth User to Machine Per User as the auth type.
4. From the OAuth Provider dropdown, select your provider.
5. Configure the provider settings as needed (see the configuration notes in the table above).
6. For the OAuth Scope field, enter the scopes you need as a space-delimited string (for example, MCP SEARCH). Refer to the supported scopes in the table above for your selected provider. If you leave this field empty, Databricks requests the full default set of scopes.
7. Click Create connection.

Each user will be prompted to authorize with the provider on first use.

From Databricks Marketplace

Preview

This feature is in Public Preview.

Install curated MCP servers directly from Databricks Marketplace:

1. In your Databricks workspace, go to Marketplace > Agents > MCP Servers tab.

2. Find the MCP server you want to install and click Install.

3. On the installation dialog, configure the connection:

   • Connection name: Enter a name for the Unity Catalog connection (for example, github_connection).
   • Host: The host domain is pre-populated for curated servers.
   • Base path: The base path is pre-populated for curated servers.

4. Configure credentials: Enter your authentication credentials. The required fields depend on the server's credential type:

   • For bearer token authentication, provide your bearer token.
   • For OAuth U2M authentication, provide your client ID and client secret.

   See the MCP server provider's documentation for instructions on obtaining these credentials.

5. Click Install to create the connection.

For complete details about Marketplace installation, see Get access to external MCP servers.

Custom HTTP connection

Create a Unity Catalog HTTP connection to install any MCP server, including self-hosted or third-party servers not available in Marketplace.

1. Create an HTTP connection. See HTTP connection.

2. When creating the HTTP connection, select the Is mcp connection checkbox to enable MCP functionality.

3. Verify that the connection URL points to a valid MCP server endpoint.

Dynamic Client Registration (Experimental)

Preview

This feature is in Public Preview.

Use Dynamic Client Registration (DCR) to automatically register and install MCP servers that support OAuth 2.0 DCR (RFC7591).

DCR automatically handles OAuth discovery, client registration, and Unity Catalog connection creation without requiring manual credential configuration.

To use DCR, you must meet the following requirements:

• The MCP server must support DCR and OAuth 2.0 authorization.
• The MCP server must expose OAuth metadata endpoints.

1. Install or upgrade the databricks-mcp package to get the latest version:

   Python

   %pip install -U databricks-mcp
   %restart_python

2. Use the DCR registration function to create a Unity Catalog connection:

   Python

   from databricks.sdk import WorkspaceClient
   from databricks_mcp import register_mcp_server_via_dcr
   
   # Initialize workspace client
   workspace_client = WorkspaceClient()
   
   # Register MCP server via DCR
   connection_url = register_mcp_server_via_dcr(
       connection_name="my_mcp_server",
       mcp_url="https://mcp.example.com/api",
       workspace_client=workspace_client
   )
   
   print(f"Connection created: {connection_url}")

View your MCP server

After completing any installation method:

• A Unity Catalog connection is created with your MCP server details

• Databricks provisions a managed proxy endpoint that securely handles authentication and token management

• The MCP server is available in AI Playground and can be used programmatically in your agents

• You can grant other users access to the connection through Unity Catalog permissions

• The proxy endpoint URL follows this format:

  https://<workspace-hostname>/api/2.0/mcp/external/{connection_name}

To view your MCP server, go to your workspace > Agents > MCP Servers

Share the MCP server connection

Grant USE CONNECTION privileges to identity principals that need to use the MCP server connection:

1. In your workspace, go to Catalog > Connections > Your connection > Permissions.
2. Grant identities appropriate access to the Unity Catalog connection.

Test MCP servers within Databricks

You can test MCP servers directly within Databricks without writing any code.

Using Genie Code: follow steps in Add MCP servers to Genie Code

Using AI Playground:

1. Go to AI Playground in your Databricks workspace.

2. Choose a model with the Tools enabled label.

3. Click Tools > + Add tool and select MCP Servers from the available tool options.

4. In the MCP Servers section, select External MCP servers to browse available connections.

5. Choose the Unity Catalog connection you installed earlier (for example, github_connection).

6. Chat with the LLM to test how it interacts with your MCP server tools. AI Playground automatically discovers available tools from your MCP server and makes them available to the LLM.

This allows you to quickly prototype and test MCP server integrations before building full agents or deploying to production.

Use MCP servers programmatically

After installing an MCP server, use it programmatically in your agent code by connecting to the proxy URL. The Databricks proxy makes external servers behave like managed MCP servers, handling authentication and token management.

Databricks MCP Client

The recommended approach treats external MCP servers as Databricks managed servers by adding the proxy endpoint to your MANAGED_MCP_SERVER_URLS list.

Python

from databricks.sdk import WorkspaceClient
from databricks_mcp import DatabricksMCPClient

# Initialize workspace client
workspace_client = WorkspaceClient()
host = workspace_client.config.host

# External MCP servers are proxied as managed servers, allowing you
# to use the same API for both managed and external servers
MANAGED_MCP_SERVER_URLS = [
    f"{host}/api/2.0/mcp/functions/system/ai",  # Default managed MCP
    f"{host}/api/2.0/mcp/external/github_connection"  # External MCP proxy
]

To use the MCP server in an agent, pass the proxy URL to the managed_server_urls parameter:

Python

# Use with agents - external servers work just like managed ones
import asyncio
from your_agent_code import create_mcp_tools  # Your agent's tool creation function

# Create tools from both managed and external (proxied) servers
mcp_tools = asyncio.run(
    create_mcp_tools(
        ws=workspace_client,
        managed_server_urls=MANAGED_MCP_SERVER_URLS
    )
)

You can also call the tool directly using the Databricks MCP Client:

Python

# Direct tool call using DatabricksMCPClient
mcp_client = DatabricksMCPClient(
    server_url=f"{host}/api/2.0/mcp/external/github_connection",
    workspace_client=workspace_client
)

# List available tools
tools = mcp_client.list_tools()
print(f"Available tools: {[tool.name for tool in tools]}")

# Call a tool
response = mcp_client.call_tool(
    "list_commits",
    {"owner": "mlflow", "repo": "mlflow", "sha": "master"}
)
print(response.content[0].text)

Standard MCP SDK

Connect to MCP servers using the standard MCP SDK with async/await:

Python

%pip install -U databricks-sdk databricks_mcp tabulate databricks_ai_bridge
%restart_python

import json
from databricks.sdk import WorkspaceClient
from databricks_mcp import DatabricksOAuthClientProvider
from databricks.sdk.credentials_provider import ModelServingUserCredentials
from mcp.client.streamable_http import streamablehttp_client as connect
from mcp import ClientSession
from tabulate import tabulate


async def main():
    app_url = "https://<workspace-hostname>/api/2.0/mcp/external/github_connection"
    client = WorkspaceClient()

    async with connect(app_url, auth=DatabricksOAuthClientProvider(client)) as (
        read_stream,
        write_stream,
        _,
    ):
        async with ClientSession(read_stream, write_stream) as session:
            init = await session.initialize()
            print(json.dumps(init.model_dump(), indent=2))
            tools = await session.list_tools()
            print(json.dumps(tools.model_dump(), indent=2))

            arguments = {
                "owner": "mlflow",
                "repo": "mlflow",
                "sha": "master"
            }
            response = await session.call_tool(name="list_commits", arguments=arguments)

            data = json.loads(response.content[0].text)
            rows = []
            for commit in data:
                author = commit.get("commit", {}).get("author", {}).get("name")
                message = commit.get("commit", {}).get("message", "").split("\n")[0]
                html_url = commit.get("html_url", "")
                rows.append([author, message, html_url])

            # Print as table
            print(tabulate(rows, headers=["Author", "Message", "Commit URL"], tablefmt="github"))

await main()

Example notebooks: Build an agent with Databricks MCP servers

The following notebooks show how to author LangGraph and OpenAI agents that call MCP tools, including external MCP servers accessed through Databricks proxy endpoints.

LangGraph MCP tool-calling agent

Open notebook in new tab

OpenAI MCP tool-calling agent

Open notebook in new tab

Authentication and security

Databricks uses managed MCP proxies and Unity Catalog HTTP connections to securely handle authentication to external MCP servers. The following authentication methods are supported:

Supported authentication methods

Databricks supports the following types of authentication for 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 like a user's GitHub repositories, Slack messages, or calendar.

For detailed configuration instructions for each authentication method, see HTTP connections.

Security benefits

• Secure token management: Databricks handles all OAuth flows and token refresh automatically
• No exposed credentials: Tokens are never exposed to end users
• Centralized authentication: Consistent authentication patterns using Unity Catalog connections

Limitations

• Databricks supports only external MCP servers that use the Streamable HTTP transport mechanism.

Next steps

• Use managed MCP servers alongside external servers
• Connect clients to MCP servers for accessing Databricks MCP infrastructure
• Build custom MCP servers for your organization's needs
• Deploy agents that use external MCP servers

• Use external MCP servers with Agent Bricks: Supervisor Agent.