Skip to main content
Last updated on

Host an MCP server on Databricks Apps

Build an MCP server on Databricks Apps so your agent can call your own tools. Databricks Apps provides the compute to run the server and an HTTPS URL for agents to connect to it.

Choose your path​

Choose one of these three ways to host an MCP server on Databricks Apps:

Build a server from the Starter template​

The MCP Server (Starter) template includes two tools that you can call before adding your own Python code: health, which checks that the server is running, and get_current_user, which returns the calling user's identity. get_current_user works only when the app has user authorization scopes.

Find and deploy the template​

Use a workspace that meets the Databricks Apps requirements.

  1. In your workspace, open Unity Gateway and select MCPs.
  2. Click + MCP and choose Build a new MCP server. The Databricks Apps creation page opens.
  3. Find Install from a template. In this template gallery, select the Agents tab, then MCP Server (Starter).
  4. Review the resource, compute, and authorization settings. Click Next to continue through the setup.
  5. Name the app mcp-my-server and click Create app. Use another name starting with mcp- if that name is taken. This prefix lets AI Playground recognize the MCP server.

In the UI, creating an app from the template also deploys the template code. With the CLI, databricks apps create creates the app without deploying code, so run databricks apps deploy with --source-code-path as shown. Wait for deployment to finish. The app's Overview page shows its URL and deployment status.

Call the first tool​

Copy the app URL from its Overview page and append /mcp:

Text
https://<app-hostname>/mcp

Connect your agent with this URL.

Ask your agent: "Call the health tool." Confirm that the tool returns "status": "healthy". To check the server without an agent, see Call a tool from Python.

If get_current_user fails when your agent calls it, see Troubleshooting.

Add your own tool​

Add a tool that converts text to uppercase:

  1. Get the source code. If you deployed with the CLI, use your clone of the template. Otherwise, on the app's Overview page, follow Edit in your IDE to copy the source code to your computer and sync edits back to the workspace.

  2. Open server/tools.py. Add this function inside load_tools(mcp_server), alongside the existing tools:

    Python
        @mcp_server.tool
        def uppercase(text: str) -> str:
            """Convert a string to uppercase."""
            return text.upper()

  3. Sync your changes and redeploy the app. With the CLI, run this from the template folder:

    Bash
    databricks sync . /Workspace/Users/<your-email>/mcp-my-server && databricks apps deploy mcp-my-server --source-code-path /Workspace/Users/<your-email>/mcp-my-server

  4. Reconnect your agent to load the updated tools. Ask it to call uppercase with hello and confirm the result is HELLO.

See the Starter template source for the complete server.

Expose a REST API as MCP tools​

Use this option when you already have an HTTP API, such as a customer lookup API, and want your agent to call it. The MCP Server (OpenAPI) template provides tools to discover and call your API's endpoints.

Prepare the API​

The template needs two things:

  • An API description: Save your API's OpenAPI 3.x specification as spec.json and upload it to a volume. Place it at the volume root, outside any subfolder. See the example specification.
  • An HTTP connection: Create a connection that stores your API's authentication credentials, or use an existing one. Store the backend token or OAuth client credentials in this connection. Copy the connection name. Creating one requires CREATE CONNECTION.

Choose the connection's authentication method for the identity your API should receive:

  • Each user's provider account: Choose OAuth User-to-Machine Per User and configure the provider's OAuth settings.
  • A shared account: Choose Bearer token, OAuth Machine-to-Machine, or OAuth User-to-Machine Shared, depending on what the API supports.

See HTTP connection authentication methods for the supported options and connection properties for the required credentials and OAuth endpoints.

Create the app​

  1. In Unity Gateway, select MCPs, click + MCP, and choose Build a new MCP server.
  2. On the Apps creation page, under Install from a template, select Agents, then MCP Server (OpenAPI).
  3. For the uc-volume resource, select the volume containing spec.json. This gives the app access to your API description.
  4. Continue through the compute and authorization settings. Name the app mcp-my-api and click Create app.

Configure authentication and the connection​

The template uses the caller's Databricks token to access the HTTP connection. The connection supplies the external API's credential. This applies even when all callers use a shared backend account.

  1. Under user authorization, verify that the app requests catalog.connections, the scope declared by the template.

  2. Grant each caller CAN USE on the app and USE CONNECTION on the HTTP connection. To grant connection access, open Catalog > Connections, select the connection, and use its Permissions tab.

  3. On the app's Overview page, follow Edit in your IDE to copy the source code to your computer and set up syncing to the workspace.

  4. Open app.yaml. In the env section, find UC_CONNECTION_NAME and set its value to your connection's name:

    YAML
    - name: UC_CONNECTION_NAME
      value: my_api_connection

    Replace my_api_connection with your connection's name. Leave the other template settings unchanged.

  5. Sync the updated file, then redeploy the app. Wait for deployment to finish on Overview.

Make the first call​

Connect with a Databricks OAuth token that includes the app's user authorization scopes. See OAuth scopes for app calls. For a per-user connection, each caller must also authorize their provider account using the HTTP connection's OAuth sign-in flow.

  1. Copy the app URL from Overview, append /mcp, and connect your agent.
  2. Ask your agent to call list_api_endpoints. Check that the result includes the endpoints in your specification.
  3. Ask the agent to call a read-only endpoint and confirm that it returns data from your API.

The template reads the user token from x-forwarded-access-token and calls serving_endpoints.http_request with the connection name. See the authentication helper and API request handler.

For new code that calls the API outside this template, Databricks recommends the HTTP connection proxy.

Example OpenAPI specification​

This specification describes GET /widgets. Replace the URL and operations with your API's values:

JSON
{
  "openapi": "3.1.0",
  "info": { "title": "Example API", "version": "1.0.0" },
  "servers": [{ "url": "https://api.example.com" }],
  "paths": {
    "/widgets": {
      "get": {
        "summary": "List widgets",
        "responses": { "200": { "description": "A list of widgets" } }
      }
    }
  }
}

Deploy an existing MCP server​

Host your existing MCP server on Databricks Apps.

Prepare your server​

Your source folder needs:

  • An HTTP server: Configure Streamable HTTP. Listen on 0.0.0.0 and the port in DATABRICKS_APP_PORT (default 8000). Note your MCP path, such as /mcp.

  • Dependencies: Include the appropriate dependency file, such as requirements.txt for Python or package.json for Node.js.

  • A start command: Add app.yaml with the command that starts your server. For a Python entry point named server.py, use:

    YAML
    command: ['python', 'server.py']

Deploy and connect​

  1. In Unity Gateway, select MCPs, click + MCP, and choose Build a new MCP server.
  2. On the Apps creation page, choose Create a custom app. Name it with the mcp- prefix and complete the app setup.
  3. On the app's Overview page, follow Edit in your IDE to sync your source folder to the workspace.
  4. Click Deploy, select the workspace folder, then click Select and Deploy. Wait for deployment to finish. See Deployment instructions.
  5. Copy the app URL and append your MCP path. Connect your agent with that URL and call one of your server's tools to check the connection.

Connect your agent​

Use the MCP URL for the path you chose. For the Starter and OpenAPI templates, append /mcp to the app URL. For an existing server, use the MCP path configured in your server.

Choose your agent's setup guide:

Callers need CAN USE on the app and an OAuth token. Personal access tokens aren't supported. See Apps permissions and token authentication for Apps.

Call a tool from Python​

To test the server without an agent, call health with version 2 of the MCP Python SDK:

Bash
pip install --upgrade "mcp>=2"

Get an OAuth token with databricks auth token and copy its access_token value. A token from the Databricks CLI includes the all-apis scope, which covers any app's user authorization scopes. See token authentication for Apps. Then open a session against the app's MCP URL and call the tool:

Python
import asyncio

import httpx2
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

MCP_URL = "https://<app-hostname>/mcp"


async def main(databricks_token):
    http_client = httpx2.AsyncClient(headers={"Authorization": f"Bearer {databricks_token}"})
    async with http_client, streamable_http_client(MCP_URL, http_client=http_client) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            result = await session.list_tools()
            print([tool.name for tool in result.tools])

            result = await session.call_tool("health", arguments={})
            print(result)


asyncio.run(main("<oauth-token>"))

The health result includes "status": "healthy".

Troubleshooting​

  • get_current_user returns Authentication token not found in request headers (x-forwarded-access-token). The app lacks user authorization scopes. Add scopes to the app, then connect with an OAuth token that includes them. See token authentication for Apps.

Pricing and monitoring​

Apps use Databricks Apps pricing. For deployment and request logs, see Logging and monitoring for Databricks Apps.

On this page