Custom MCP servers

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.

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

Step 2: 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".

Step 3: 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.

Step 1: 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. Copy the connection name. Creating one requires CREATE CONNECTION.

Step 2: 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.

Step 3: Set the API connection

The app needs the HTTP connection name to authenticate requests to your API.

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

  2. 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.

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

Step 4: Make the first call

Each caller needs USE CONNECTION on the HTTP connection. If it uses per-user OAuth, sign in to the provider when prompted.

  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.

See the OpenAPI template source for configuration details.

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.

Step 1: 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']

Step 2: 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. See Apps permissions.

Pricing and monitoring

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

  • Last updated on