Databricks MCP

Read-only Streamable HTTP MCP server for a Databricks workspace. It exposes catalog metadata and bounded SQL tools while preserving the caller's identity through an OAuth-protected resource-server boundary.

MCP authorization is optional in the protocol, but this service is designed for private data and therefore requires authorization in production. The authorization server can be self-hosted or provided by a third party. See docs/authorization.md for the protocol flow and configuration contract.

Tools

• list_warehouses

• list_catalogs

• list_schemas

• list_tables

• describe_table

• sample_table

• search_tables

• run_readonly_sql

SQL accepts one SELECT, WITH, SHOW, DESCRIBE, or EXPLAIN statement and returns at most 200 rows. No write, cluster, job, DBFS, or secret tools are exposed. Table sampling requires a three-part Unity Catalog identifier and is capped at 100 rows.

Related MCP server: DB MCP Gateway

Client configuration

Configure an MCP client with the public resource URL:

{
  "mcpServers": {
    "databricks": {
      "type": "http",
      "url": "https://mcp.example.com/databricks"
    }
  }
}

The client discovers the authorization server after the resource server returns an OAuth challenge. Do not place OAuth client secrets, Databricks PATs, or resource-server private keys in client configuration.

Configuration

Start from deploy/service.env.example. Keep real credentials and deployment-specific values outside Git.

Local run

uv run uvicorn mcp_databricks.server:app --host 127.0.0.1 --port 6328
# or
python -m mcp_databricks

The canonical Python entrypoint is mcp_databricks.server. The ASGI app is available as mcp_databricks.server:app for uvicorn, Hypercorn, or another ASGI host.

Docker deployment

docker build -f deploy/Dockerfile -t databricks-mcp:latest .
docker run --rm -p 127.0.0.1:6328:6328 \
  --env-file deploy/service.env.example \
  databricks-mcp:latest

For production, mount the resource-server exchange key read-only, use a real secret-managed environment file, and put the service behind an HTTPS reverse proxy. The reverse proxy must route the MCP endpoint and the protected-resource metadata endpoint; authorization-server endpoints remain owned by the separate authorization service.

Layout

mcp_databricks/
  server.py          canonical uvicorn/module entrypoint
  app.py             FastMCP instance and Streamable HTTP ASGI assembly
  auth/              resource-server auth configuration and display metadata
  middleware.py      per-request token exchange and caller identity
  client.py          per-request Databricks WorkspaceClient
  config.py          request credentials and SQL/identifier validation
  policy.py          fail-closed group and warehouse policy
  usage_metrics.py   best-effort SQLite request metrics
  tools/             explicit tool registration modules
tests/               auth, policy, discovery, and SQL validation tests
deploy/              generic Docker and reverse-proxy examples
docs/                authorization and integration notes

Tools are plain module-scope functions registered explicitly, so importing a tool module has no server-side side effects and each function remains directly callable from tests.