Use external MCP servers

Beta

This feature is in Beta.

Connect Databricks to external Model Context Protocol (MCP) servers to give your agents access to a wider range of tools that are hosted outside of Databricks. External MCP servers are third-party MCP servers hosted outside of Databricks that you connect to through Databricks-managed proxies.

Authentication and security

Databricks uses managed MCP proxies and Unity Catalog HTTP connections to securely handle authentication to your workspace:

• 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

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 two options for installing external MCP servers to use with your agents. Both methods create a Unity Catalog connection that enables secure, authenticated access to the MCP server.

Choose your installation method based on your MCP server:

From Databricks Marketplace

Preview

This feature is in Public Preview.

Install curated and pre-configured 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.

   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.

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

4. 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.

After completing either 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 with AI Playground

Test MCP servers directly in AI Playground without writing any code:

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

Limitations

• Private connectivity to resources in your VPC using Private Link is not supported. Contact your support team if you need this functionality.

• 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: Multi-Agent Supervisor.