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
- Notebook (service principal)
- Agent code (on-behalf-of-user)
- Agent code (service principal)
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}")
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}")
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.
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
OpenAI MCP tool-calling agent
Next steps
- Connect agents to external services for an overview of all approaches to connect agents to external services, including managed OAuth and the UC connections proxy.
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.