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 a working health tool that you can call before adding your own Python code.

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.

Creating the app also deploys the template code. Wait for deployment to finish on the app's Overview page; this is where you find its URL and deployment status.

Call the first tool

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

https://<app-hostname>/mcp

Connect your agent with this URL.

Ask your agent: "Call the health tool." Confirm that the tool returns "status": "healthy".

Add your own tool

Add a tool that converts text to uppercase:

  1. 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:

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

  3. Sync your changes and redeploy the app.

  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 Azure 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:

    - 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 Azure 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:

{
  "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:

    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.

Pricing and monitoring

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

  • Last updated on