Custom

You can run a custom MCP server to host the MCP endpoints for your Databricks Apps or locally for development. This server supports connecting clients via a standard HTTP MCP URL and can be started locally with the uv tool, or deployed to Databricks Apps using the Databricks CLI and related Bundles tooling. This guide walks you through practical usage, installation steps, and deployment options so you can choose the workflow that fits your environment.

How to use

Connect your MCP client to the HTTP MCP endpoint when hosting the server on Databricks Apps. The transport URL is a Streamable HTTP endpoint that ends with /mcp/. Use a Bearer token for authentication, obtained from your active Databricks profile.

How to install

Prerequisites you need before starting: the Databricks CLI must be installed and configured, and you need the uv tool available in your environment.

# Prerequisites (example commands)
# 1) Ensure Databricks CLI is installed and configured
# 2) Ensure the uv tool is available in your PATH

How to install

Local development and running the server locally uses the uv tool to sync and start the server. Run the following commands to set up and launch the server during development. Changes will trigger a reload.

uv sync
uv run custom-server

How to install

To deploy the server on Databricks Apps, authenticate with a Databricks profile and use the Apps deployment flow.

export DATABRICKS_CONFIG_PROFILE=<your-profile-name> # e.g. custom-mcp-server

databricks auth login --profile "$DATABRICKS_CONFIG_PROFILE"

How to install

Deployment via Databricks Apps involves creating an app, syncing your code, and deploying the app with the source code path.

databricks apps create mcp-custom-server

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

How to install

If you prefer the bundle approach, prepare the app configuration to run a server via uvicorn, then build and deploy the bundle.

# In the directory with your app.yaml and MCP server code
# Update app.yaml to specify the command to run
# command: ["uvicorn", "custom_server.app:app"]

uv build --wheel
databricks bundle deploy
databricks bundle run custom-mcp-server

How to use

Once deployed, you connect to the MCP server via the HTTP endpoint or use the local stdio runtime to run the server locally. For the HTTP endpoint, the URL will be provided by your Databricks Apps deployment.

Additional notes

If you need to authenticate, you can generate a Bearer token from your Databricks profile and use it with your MCP client. The HTTP URL must be reachable and end with /mcp/ to ensure proper routing.

Troubleshooting and tips

• Ensure the URL you use ends with /mcp/ exactly, including the trailing slash.
• If local changes are not picked up, verify that your uv command is correct and that the server module is named or exposed as expected by your app.
• When deploying, confirm that your Databricks profile is configured and that you have network access to the Databricks workspace.
• Keep token generation steps handy for refreshing tokens as needed.

Available tools

uv

Runs the MCP server locally and enables live reload during development.

databricks_apps_cli

Deploys the MCP server to Databricks Apps via the apps CLI.

databricks_bundle_cli

Deploys the MCP server using the Databricks bundle workflow.

uvicorn

Runs the ASGI application for the MCP server when using a bundle approach.