uc-mcp-proxy

MCP stdio-to-Streamable-HTTP proxy with Databricks OAuth.

Lets any MCP client that speaks stdio (e.g. Claude Desktop, Claude Code) connect to any Databricks MCP server — Managed, External, or Apps — handling authentication automatically.

Installation

# Run directly (no install needed)
uvx uc-mcp-proxy --url <MCP_SERVER_URL>

# Or install globally
uv tool install uc-mcp-proxy

Requires Python 3.10+.

First-run authentication

uc-mcp-proxy expects a configured Databricks CLI profile. Set one up first:

databricks configure --host https://<workspace>

Then pass it to the proxy:

uvx uc-mcp-proxy --url <MCP_SERVER_URL> --profile <name>

If the profile uses OAuth U2M (auth_type = databricks-cli) and the cached token is expired, uc-mcp-proxy runs databricks auth login --profile <name> automatically the first time it launches, opening a browser tab. Subsequent runs use the refreshed token.

uc-mcp-proxy will only auto-login for OAuth (databricks-cli) profiles. For PAT, M2M, Azure, or other auth types, the proxy diagnoses the failure and points you at the right remediation — it never runs databricks auth login against a non-OAuth profile because that would overwrite your existing credentials in ~/.databrickscfg.

To skip the auto-login (CI / headless), pass --no-auto-login and ensure DATABRICKS_TOKEN or another credential is set in the environment.

Databricks MCP Server Types

An App is served from its own hostname on databricksapps.com — not from a path under your workspace host. Databricks assigns the URL when the app is created and it cannot be changed afterwards, so copy it from the Apps page in the workspace UI (or databricks apps list) rather than constructing it by hand — on the workspace we tested, the segment Databricks documents as <region> is the cloud name (aws), not a region like us-east-1. The <path> is whatever route the app serves MCP on; /mcp is the common convention.

Apps reject raw personal access tokens. The App front door requires an OAuth token, so use --auth-type databricks-cli (browser-based OAuth U2M) when connecting to a Databricks App. Managed and External MCP servers also work with PAT and other auth types.

Usage

Claude Desktop / Claude Code (.mcp.json)

Add to your MCP client configuration:

{
  "mcpServers": {
    "unity-catalog": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "uc-mcp-proxy",
        "--url", "<MCP_SERVER_URL>"
      ]
    }
  }
}

CLI

uc-mcp-proxy --url <MCP_SERVER_URL> [--profile <DATABRICKS_PROFILE>] [--auth-type <AUTH_TYPE>]

Meta Parameters (Managed MCP)

Databricks Managed MCP servers accept configuration — for example, selecting a SQL warehouse — via the MCP _meta field in the JSON-RPC request body, not as HTTP headers. See the Databricks meta-param docs for the supported keys per server type.

Use --meta KEY=VALUE (repeatable) — the proxy merges these into params._meta on every outgoing tools/call request:

uvx uc-mcp-proxy \
  --url https://workspace.databricks.com/api/2.0/mcp/sql \
  --meta warehouse_id=abc123

Or in .mcp.json:

{
  "mcpServers": {
    "sql-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "uc-mcp-proxy",
        "--url", "https://workspace.databricks.com/api/2.0/mcp/sql",
        "--meta", "warehouse_id=abc123"
      ]
    }
  }
}

If the MCP client already sets a _meta key that the proxy is also configured to inject, the proxy value wins and a warning is written to stderr.

SSL Certificate Verification

Some Azure Databricks instances use self-signed or internally-signed certificates that are not trusted by the system's default CA bundle. This causes errors like:

SSL_CERTIFICATE_VERIFY_FAILED: certificate verify failed: unable to get local issuer certificate

Use --no-verify-ssl to disable certificate verification:

uvx uc-mcp-proxy \
  --url https://workspace.azuredatabricks.net/api/2.0/mcp/functions/main/default \
  --no-verify-ssl

Or in .mcp.json:

{
  "mcpServers": {
    "unity-catalog": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "uc-mcp-proxy",
        "--url", "https://workspace.azuredatabricks.net/api/2.0/mcp/functions/main/default",
        "--no-verify-ssl"
      ]
    }
  }
}

Security warning: --no-verify-ssl disables all certificate validation, which exposes connections to man-in-the-middle (MITM) attacks. Only use this flag in trusted network environments (e.g. a private corporate VPN) where you control the network path to the Databricks workspace.

How It Works

1. Starts an MCP stdio server (stdin/stdout)
2. Connects to the remote MCP server via Streamable HTTP
3. Injects a fresh Databricks OAuth token on every HTTP request
4. Bridges messages bidirectionally between the two transports

Authentication

Authentication is handled by the Databricks SDK. The SDK auto-detects the method, or you can force one with --auth-type.

Troubleshooting

When the remote MCP server refuses a request, the proxy prints a diagnosis to stderr naming the status, the URL, the profile, and the auth type in use.

A failure on the background server→client stream is reported but does not stop the proxy: the SDK retries a bounded number of times and then stops, so server-initiated messages may be lost while tool calls keep working.

Development

uv sync                        # install dependencies
uv run pytest -m unit -v       # run unit tests
uv run pytest -m integration -v # run integration tests
uv build                       # build package

License

MIT