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. Either use --auth-type databricks-cli (browser-based OAuth U2M), or point a PAT profile at the App URL and the proxy exchanges the PAT for an app-scoped token automatically — see Databricks Apps from a PAT profile. The PAT must be one the exchange accepts (a Lakebox credential, not a classic dapi… PAT). Managed and External MCP servers work with PAT and other auth types as-is.

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>]

Databricks Apps from a PAT profile

A Databricks App refuses a raw personal access token — its front door wants an OAuth token minted for that app. Rather than forcing a browser login, the proxy trades your PAT for one (RFC 8693 token exchange) on your behalf, and it works this out automatically.

The common case needs no exchange flags. Point a PAT profile at an App URL and the proxy detects the App host (*.databricksapps.com), looks up the app's oauth2_app_client_id and effective_user_api_scopes from workspace metadata, and runs the exchange:

uc-mcp-proxy \
  --url https://<app-name>-<workspace-id>.aws.databricksapps.com/mcp \
  --profile MY_PAT_PROFILE

{
  "mcpServers": {
    "databricks-app": {
      "command": "uvx",
      "args": [
        "uc-mcp-proxy",
        "--url", "https://<app-name>-<workspace-id>.aws.databricksapps.com/mcp",
        "--profile", "MY_PAT_PROFILE"
      ]
    }
  }
}

The credential must be one the exchange accepts. A Lakebox-generated environment credential works; a classic, hand-minted dapi… PAT does not — the platform rejects it as an exchange subject. When the proxy sees an App URL with a dapi… token it refuses up front with that explanation rather than leaking the token on a doomed request. See docs/token-exchange.md for the evidence.

Overrides, for when detection or discovery is not enough:

• --client-id <oauth2_app_client_id> — set the audience explicitly and skip discovery (e.g. the identity cannot list the app). --scope then supplies the scopes, since discovery is skipped.
• --scope "a b" — override the discovered scopes. Repeatable.
• --pat-exchange — force the exchange when --url is not recognized as an App host, and bypass the classic-PAT refusal. Discovery still fills the client id and scopes unless --client-id is given.

Worth knowing:

• The exchange requires a PAT profile. --client-id / --pat-exchange on any other auth type exit immediately rather than pretending to work. DATABRICKS_TOKEN counts as a PAT.
• --scope is required by real Apps. An App with declared effective_user_api_scopes rejects a scope-less exchange; discovery supplies them automatically, and the proxy warns if it ends up with none to send.
• The exchanged token is short-lived (about an hour) and is re-minted automatically, including once in-place if the app rejects it mid-session, so long sessions do not need restarting.
• Your PAT is never forwarded to the app. It goes only to the workspace token endpoint, as the subject of the exchange. For any pat profile the proxy also stops populating X-Forwarded-Access-Token, which the platform supplies itself — a raw PAT there would be handed to arbitrary app code, and it would survive a cross-origin redirect that strips Authorization.
• Verified on one AWS workspace at one point in time. The accepted request shape is undocumented, so treat it as empirical rather than contractual; a refusal prints the exact request that was sent so a platform change is diagnosable rather than mysterious.

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.

Combined with --client-id the exposure is wider than usual: the token exchange sends your PAT in a request body to the workspace token endpoint, not only as a header. Anyone able to intercept that connection reads a long-lived, full-privilege credential.

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