Skip to main content

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.

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

Requirements​

  • A workspace with the Managed MCP Servers preview enabled. See Manage Databricks Previews.
  • In order to connect to external MCP servers, you need to use a Unity Catalog HTTP connection. To create a Unity Catalog connection, you must have CREATE CONNECTION privileges on the Unity Catalog metastore attached to the workspace. See Create a Unity Catalog HTTP connection for more details.

Create a Unity Catalog HTTP connection​

Create an HTTP connection by following the Unity Catalog connections documentation. Unity Catalog connections support multiple authentication mechanisms. Choose the right mechanism for your use case:

  • Bearer token: Obtain a bearer token for simple token-based authentication.
  • OAuth 2.0 Machine to Machine: Create and configure an app to enable authentication between two systems or services without any user involvement. Use this when services or backends need to securely communicate server-to-server using only their own identities.
  • OAuth 2.0 User to Machine Shared: Authenticate with user interaction to authorize a service or machine under a shared user identity (such as a single admin or service principal). Use this when a single user account (such as a service principal or admin) can be authorized once and then used by all users across all machines or services.
  • OAuth 2.0 User to Machine Per User: Authenticate with individual user interaction to establish access between each user's identity and the machine or service. Use this when each user must log in and authenticate with their own credentials to access external services under their personal identity. Note: Each user needs to login with their Databricks account for authentication.
note

When creating the HTTP connection, ensure you:

  • Select the Is mcp connection checkbox to enable MCP functionality.
  • Verify that the connection URL points to a valid MCP server endpoint.

With OAuth, Databricks automatically handles token exchange and refreshes on expiry—users don't need to manage tokens manually.

After the UC connection is created, Databricks automatically provisions a proxy endpoint. This endpoint securely proxies traffic to the external MCP server, managing token injection and renewal under the hood.

  • Tokens are never exposed to end users.
  • Databricks manages all token lifecycle operations—including OAuth flows and token refresh.

This ensures secure, low-friction access to external MCP services from notebooks, agents, and workflows.

Proxy endpoints URLs follow this format:

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

Connect with AI Playground​

You can easily test external MCP servers directly in AI Playground without writing any code:

  1. Open AI Playground: Navigate to the AI Playground in your Databricks workspace.

  2. Select a tool-calling model: Choose a model with the Tools enabled label.

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

  4. Choose external MCP server: In the MCP Servers section, select External MCP servers to browse available external connections.

  5. Select your connection: To connect to your external MCP server, choose the Unity Catalog HTTP connection you created earlier (e.g., github_u2m_connection) to connect to your external MCP server.

  6. Test interactively: Start chatting with the LLM to test how it interacts with your external MCP server tools. AI Playground automatically discovers available tools from your external MCP server and makes them available to the LLM.

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

Use the open source MCP SDK​

With the connection's proxy endpoint URL, you can connect to an external MCP server using the open source Python SDK for Model Context Protocol servers and clients. This lets your Databricks agents invoke tools exposed by external MCP servers.

The example below shows how to use a Unity Catalog connection named github_u2m_connection to connect to a GitHub MCP server, list available tools, and call the list_commits tool to retrieve recent commits:

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_u2m_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()

Authentication and security benefits​

Databricks-managed external MCP servers provide several security advantages:

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

Limitations​

Next steps​

Last updated on