Skip to main content
Last updated on

Host your own MCP server

Host custom or third-party MCP servers as Databricks apps. Custom MCP servers are useful if you already have an MCP server you want to deploy, if you want to run a third-party MCP server as a source of tools, or if you want to wrap an existing REST API as MCP tools.

Access to custom MCP servers is controlled through Databricks Apps permissions. To monitor custom MCP activity alongside your other MCP servers and LLM endpoints, use Unity Gateway.

To use a hosted custom MCP server in agent code, see Use MCP servers in Custom Agents.

Requirements​

  • An MCP server hosted as a Databricks app must implement an HTTP-compatible transport, such as the streamable HTTP transport.

Create a custom MCP server from the Apps template​

Use the built-in Hello World MCP Server template to create and deploy an MCP server with example tools already included:

  1. In the sidebar, click Compute.

  2. Click the Apps tab.

  3. Click Create app.

  4. Under the Agents category, select the MCP Server - Hello World template.

  5. Enter an app name starting with mcp- (for example, mcp-hello-world).

    note

    The app name must start with mcp- to be recognized as an MCP server in the AI Playground.

  6. Click Create app.

Databricks deploys the app with example code that you can customize.

The template includes two example tools to get you started:

  • health(): A diagnostic tool that confirms the server is operational and returns status information.
  • get_current_user(): A tool that retrieves the current user's information using the Databricks SDK, demonstrating how to integrate workspace authentication.

Add a custom tool​

To add your own tool, open the app source code and define a new function using the @mcp.tool() decorator. For example, the following tool converts a string to uppercase:

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

Each tool must include a docstring. Agents use the docstring to understand when to call the tool. After adding a tool, redeploy the app to make it available.

See Create an app from a template for more details on working with app templates, or see the template source code on GitHub.

Wrap a REST API as an MCP server from the Apps template​

Use the built-in MCP Server (OpenAPI) template to expose any REST API as MCP tools without writing custom tool code. You provide an OpenAPI specification that describes the API and a Unity Catalog connection that authenticates to it, and the server turns the API's operations into tools that any agent can call.

The template deploys an MCP server with three tools:

  • list_api_endpoints: Lists the endpoints defined in the OpenAPI specification.
  • get_api_endpoint_schema: Returns the request and response schema for a specific endpoint.
  • invoke_api_endpoint: Calls an endpoint with the supplied parameters and returns the response.

An agent calls list_api_endpoints and get_api_endpoint_schema to discover what the API offers, and then calls invoke_api_endpoint to run an operation.

Prerequisites​

Gather the following before you create the app:

  • An OpenAPI 3.x specification for your REST API, in JSON format.
  • A Unity Catalog volume to store the specification file. See What are Unity Catalog volumes?.
  • A Unity Catalog HTTP connection that authenticates to the API. The connection supports bearer token, OAuth machine-to-machine (M2M), and OAuth user-to-machine (U2M) authentication. To create one, see Create a connection to the external service. Creating a connection requires the CREATE CONNECTION privilege; if you don't have it, ask a workspace admin to create the connection.

The specification must be a valid OpenAPI 3.x document in JSON. At a minimum, it declares the API's base URL under servers and the operations to expose under paths:

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" } }
      }
    }
  }
}

Create the MCP server​

  1. Upload your OpenAPI specification to the Unity Catalog volume. By default, the template reads spec.json from the root of the volume.

  2. In the sidebar, click Compute.

  3. Click the Apps tab.

  4. Click Create app.

  5. Under the Agents category, select the MCP Server (OpenAPI) template.

  6. For the Unity Catalog volume resource, select the volume that contains your specification file. See Add resources to a Databricks app.

  7. Enter an app name starting with mcp- (for example, mcp-my-api).

    note

    The app name must start with mcp- to be recognized as an MCP server in the AI Playground.

  8. Click Create app.

Configure the specification and connection​

After Databricks deploys the app, set the following environment variables in the app.yaml file, and then redeploy the app:

  • SPEC_FILE_NAME: The path to your OpenAPI specification file, relative to the root of the Unity Catalog volume. Defaults to spec.json.
  • UC_CONNECTION_NAME: The name of the Unity Catalog HTTP connection that the server uses to authenticate to the API.

After the app redeploys, the MCP server endpoint is available at https://<app-url>/mcp. To call the server from agent code, see Use MCP servers in Custom Agents. To connect an external client such as Claude or Cursor, see Connect MCPs to AI assistants and coding agents.

For implementation details, see the template source code on GitHub.

Host an existing MCP server as a Databricks app​

To host an existing Python MCP server as a Databricks app, follow these steps:

Set up your environment​

Before deploying your MCP server, authenticate to your workspace using OAuth.

  1. Run the following in a local terminal:

    Bash
    databricks auth login --host https://<your-workspace-hostname>

Set up the MCP server​

Use uv for dependency management and unified tooling when deploying your MCP server.

  1. Add a requirements.txt to the MCP server's root directory and include uv as a dependency.

    uv handles installing additional dependencies defined in your project configuration.

    Txt
    uv

  2. Create a pyproject.toml file that defines a script entry point for your server.

    Example pyproject.toml:

    Toml
    [project.scripts]
    custom-server = "server.main:main"

    In this example:

    • custom-server is the script name you use with uv run
    • server.main:main specifies the module path (server/main.py) and function (main) to run

  3. Add an app.yaml file specifying the CLI command to run the MCP server using uv run.

    By default, Databricks apps listen on port 8000. If the server listens on a different port, set it using an environment variable override in the app.yaml file.

    Example app.yaml:

    YAML
    command: [
        'uv',
        'run',
        'custom-server', # This must match a script defined in pyproject.toml
      ]

When you run uv run custom-server, uv looks up the script definition, finds the module path, and calls the main() function.

Deploy the MCP server as a Databricks app​

  1. Create a Databricks app to host the MCP server:

    Bash
    databricks apps create mcp-my-server
    note

    Prefix your app name with mcp- to clearly identify it as an MCP server. This naming convention helps with discoverability and organization in your workspace.

  2. Upload the source code to Databricks and deploy the app by running the following commands from the directory containing your app.yaml file:

    Bash
    DATABRICKS_USERNAME=$(databricks current-user me | jq -r .userName)
    databricks sync . "/Users/$DATABRICKS_USERNAME/mcp-my-server"
    databricks apps deploy mcp-my-server --source-code-path "/Workspace/Users/$DATABRICKS_USERNAME/mcp-my-server"

Find your deployed app URL​

After deployment, you can find your app URL in the Databricks UI. The MCP server endpoint is available at https://<app-url>/mcp.

Pricing​

Custom MCP servers are subject to Databricks Apps pricing.

Additional resources​

On this page