Skip to main content

Connect your app to MCP tools

Build your own app on top of Model Context Protocol (MCP) servers, including the MCPs in the system.ai schema and MCPs you register. Your app calls tools as the signed-in user. Unity Gateway governance controls which MCPs and tools each user can call.

Use user authorization when your app runs on Databricks Apps. If your app signs users in with an external identity provider, use OAuth token federation to get a Databricks token. This guide covers apps that serve multiple users. To build and test an agent locally with your own credentials, see Call MCP tools from a Python agent.

For MCPs that use per-user OAuth, users also authorize their external provider account. The following steps cover both getting the Databricks token and completing provider sign-in.

Configure authentication and access​

Before adding code, give users access to the MCPs and configure your app's authentication.

Give users access to the MCPs​

These requirements apply to both authentication methods:

  • Add each user to the Databricks workspace. Consumer access is sufficient to call MCPs through Unity Gateway.
  • Grant each user EXECUTE on the MCPs, plus USE CATALOG and USE SCHEMA on their parent catalog and schema. See Share an MCP.

Configure your app's authentication​

Choose the option that matches your app:

  1. Enable user authorization for the app. Your app uses the forwarded Databricks user token directly, without token exchange or an account federation policy.
  2. Add the user authorization scopes: ai-gateway for tool calls and unity-catalog for discovery and sign-in status APIs.
  3. Grant each user CAN USE on the app.

Your app's server must also be able to reach the workspace. If IP access lists are enabled, allow its outbound IP. See MCP networking.

system.ai.dbsql, system.ai.sandbox, and system.ai.web_search are in Beta. To use them, an account admin must enable the Enhanced Unity Gateway preview from the account console Previews page. Unity Gateway itself is generally available. See Manage account previews.

Set up your app​

Keep the token and client specific to the signed-in user throughout these steps.

Get a Databricks token for the user​

Choose the option that matches how your app authenticates users. Both options give you databricks_token for the remaining steps.

Databricks Apps supplies the user's Databricks token in the x-forwarded-access-token request header. Use that token directly. Your app doesn't need to perform token exchange.

Read the token within the current request. For example, in a Flask request handler:

Python
from flask import request

databricks_token = request.headers.get("x-forwarded-access-token")
if not databricks_token:
raise ValueError("A Databricks user token is required.")

For other frameworks, see Retrieve user authorization credentials.

List MCPs​

List the MCPs the user can access in a schema. For Databricks-provided MCPs, use schemas/system.ai. For registered MCPs, use the schema where they are registered, such as schemas/main.default.

Install the SDK:

Bash
pip install --upgrade databricks-sdk

Create a client with the user's token and list the MCPs:

Python
from databricks.sdk import WorkspaceClient

workspace_client = WorkspaceClient(
host="https://<workspace-hostname>",
token=databricks_token,
auth_type="pat",
)

for service in workspace_client.ai_gateway.list_mcp_services(parent="schemas/system.ai"):
print(service.name)

The SDK setting auth_type="pat" selects the supplied token instead of the app's environment credentials. The supplied token is still the user's OAuth token. Create a WorkspaceClient for each user so that every call uses that user's token. The following steps reuse workspace_client. The SDK handles pagination for you.

Each name is a resource path of the form mcp-services/<catalog>.<schema>.<service>, such as mcp-services/system.ai.github. Pass it unchanged to the sign-in status API, and use it to build the MCP URL in Call tools. See List MCP services.

Check the user's sign-in status​

Check each MCP your app uses. The response shows whether the MCP uses per-user OAuth and, if it does, whether the user is signed in to the external provider:

Get the user's credential for the MCP:

Python
from databricks.sdk.errors import InvalidParameterValue, NotFound
from databricks.sdk.service.catalog import ProvisioningInfoState

mcp_name = service.name # From List MCPs, for example "mcp-services/system.ai.github"

needs_sign_in = True
try:
credential = workspace_client.ai_gateway.get_mcp_service_user_mapped_credential(
name=mcp_name
)
signed_in = (
credential.provisioning_info is not None
and credential.provisioning_info.state == ProvisioningInfoState.ACTIVE
)
except NotFound:
signed_in = False
except InvalidParameterValue:
# The MCP doesn't use per-user OAuth.
needs_sign_in = False
signed_in = True
  • If provisioning_info.state is ACTIVE, the user is signed in. Go to Call tools.
  • If the request returns NOT_FOUND, or the state is anything other than ACTIVE, show a sign-in button for the MCP.
  • If the request returns INVALID_PARAMETER_VALUE, the MCP doesn't use per-user OAuth, so the user doesn't need to sign in. This is the case for the Databricks data and tools MCPs. Go to Call tools.

See Get the caller's credential.

Sign the user in to the provider​

When the user clicks your sign-in button, open the MCP's sign-in page in a popup. The page's name parameter is the MCP name without the mcp-services/ prefix, such as system.ai.github. The user signs in on that page and authorizes access on the provider's consent screen.

JavaScript
// mcpName is the MCP name without the mcp-services/ prefix, for example "system.ai.github"
const signInUrl = `https://${workspaceHostname}/mcp-service-login?name=${encodeURIComponent(mcpName)}`;
window.open(signInUrl, 'mcp-sign-in', 'popup,width=600,height=700');

The sign-in page doesn't send a message back to your app. To detect when sign-in finishes, check the sign-in status again when the user returns to your app.

The sign-in page uses the user's Databricks browser session. If the user isn't signed in to the workspace in that browser, Databricks asks them to sign in first. The provider credential is saved for the user who is signed in on the page, so that user must be the same user your app acts as.

Call tools​

Send MCP requests to the MCP's URL with the user's Databricks token. The MCP URL is https://<workspace-hostname>/ai-gateway/ followed by the name from List MCPs, for example https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.github.

Your app can call tools directly, as shown in this step, or give them to an agent that decides which tools to call. To run an agent, follow Step 3: Run an agent with these tools and pass the workspace_client you created with the user's token in List MCPs, so the agent calls tools as that user. The agent frameworks use version 1 of the MCP Python SDK, so install the packages listed on that page.

Install the packages:

Bash
pip install --upgrade databricks-mcp

Connect with the user's workspace_client from List MCPs, then list and call tools:

Python
from databricks_mcp import DatabricksMCPClient

mcp_name = "mcp-services/system.ai.github" # A name from List MCPs

mcp_client = DatabricksMCPClient(
server_url=f"https://<workspace-hostname>/ai-gateway/{mcp_name}",
workspace_client=workspace_client,
)

for tool in mcp_client.list_tools():
print(f"{tool.name}: {tool.description}")

result = mcp_client.call_tool("<tool-name>", arguments={})
print(result.isError)
print(result.content)

Discover tool names and input schemas with list_tools() before you call a tool, and check whether each result is an error: result.isError with databricks-mcp, or result.is_error with version 2 of the MCP Python SDK. For how to read results, see Call a tool directly to troubleshoot. If the tool list is empty or the connection fails, see MCP authentication.

Additional resources​