Use custom MCP servers in agents

After hosting a custom MCP server as a Databricks app, connect to it from notebooks, local development, or agent code using the databricks-mcp Python library.

To host a custom MCP server, see Host a custom MCP server.

Connect to the custom MCP server

Click the tabs to see how to connect to an MCP server from various environments.

Local environment

Authenticate to your workspace using OAuth as described in Set up your environment.

The following example shows how to connect to the custom MCP server and list available tools:

from databricks_mcp import DatabricksMCPClient
from databricks.sdk import WorkspaceClient

# Replace with your deployed app URL
# Example: https://mcp-my-server-6051921418418893.aws.databricksapps.com/mcp
mcp_server_url = "https://<app-url>/mcp"

databricks_cli_profile = "DEFAULT"
workspace_client = WorkspaceClient(profile=databricks_cli_profile)

mcp_client = DatabricksMCPClient(server_url=mcp_server_url, workspace_client=workspace_client)

# List available tools
tools = mcp_client.list_tools()
print(f"Available tools: {tools}")

Notebook (service principal)

Use a service principal to access the hosted Databricks app in a Databricks notebook. Pass the client secret values directly as shown below, or use Databricks secrets to securely retrieve credentials. For example: client_id=dbutils.secrets.get(scope="my-scope", key="client-id").

from databricks_mcp import DatabricksMCPClient
from databricks.sdk import WorkspaceClient

# Replace with your deployed app URL
mcp_server_url = "https://<app-url>/mcp"

workspace_client = WorkspaceClient(
    host="<workspace-url>",
    client_id="<client-id>",
    client_secret="<client-secret>"
)

mcp_client = DatabricksMCPClient(server_url=mcp_server_url, workspace_client=workspace_client)

# List available tools
tools = mcp_client.list_tools()
print(f"Available tools: {tools}")

Agent code (on-behalf-of-user)

Set up on-behalf-of-user authorization. See On-behalf-of-user authentication.

The following example shows how to enable on-behalf-of-user access using ModelServingUserCredentials to access the hosted Databricks app from an agent:

from databricks_mcp import DatabricksMCPClient
from databricks.sdk import WorkspaceClient
from databricks.sdk.credentials_provider import ModelServingUserCredentials

# Replace with your deployed app URL
mcp_server_url = "https://<app-url>/mcp"

workspace_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())

mcp_client = DatabricksMCPClient(server_url=mcp_server_url, workspace_client=workspace_client)

# List available tools
tools = mcp_client.list_tools()
print(f"Available tools: {tools}")

Log the agent model using apps scope. See On-behalf-of-user authentication.

Agent code (service principal)

Enable System auth using service principal to access the hosted Databricks app from an agent:

from databricks_mcp import DatabricksMCPClient
from databricks.sdk import WorkspaceClient

# Replace with your deployed app URL
mcp_server_url = "https://<app-url>/mcp"

workspace_client = WorkspaceClient()

mcp_client = DatabricksMCPClient(server_url=mcp_server_url, workspace_client=workspace_client)

# List available tools
tools = mcp_client.list_tools()
print(f"Available tools: {tools}")

Log the agent model using DatabricksApps as a resource. See Automatic authentication passthrough.

Example notebooks: Build an agent with Databricks MCP servers

The following notebooks show how to author LangGraph and OpenAI agents that call MCP tools with custom MCP servers hosted on Databricks apps.

LangGraph MCP tool-calling agent

Get notebook

OpenAI MCP tool-calling agent

Get notebook

Next steps

The apps cookbook provides end-to-end code examples for integrating MCP servers with different frameworks:

For complete source code and additional examples, see the Databricks Apps Cookbook repository.

  • Last updated on