uc-mcp-proxy

name	uc-mcp-proxy
description	Connect Claude Desktop or Claude Code to a Databricks MCP server using uc-mcp-proxy. Use this when setting up, configuring, or troubleshooting a Databricks MCP connection — including Managed MCP, External MCP, and App-hosted MCP servers. Covers auth, .mcp.json config, URL patterns, and common errors.
user-invocable	true
allowed-tools	Bash, Read

uc-mcp-proxy: Connect Claude to Databricks MCP Servers

What It Does

uc-mcp-proxy is a stdio-to-Streamable-HTTP bridge. MCP clients like Claude Desktop and Claude Code speak stdio — but Databricks MCP servers speak HTTP. The proxy sits between them and injects a fresh Databricks OAuth token on every request.

Install

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

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

Requires Python 3.10+.

Databricks MCP Server Types

Type	URL Pattern	Notes
Managed MCP — UC Functions, Vector Search, Genie, SQL	https://<workspace>/api/2.0/mcp/functions/{catalog}/{schema}	PAT or OAuth
External MCP — GitHub, Google Drive, others	https://<workspace>/api/2.0/mcp/external/{connection_name}	PAT or OAuth
Apps — custom MCP servers (e.g. generated by uc-mcp-gen)	https://<app-name>-<workspace-id>.<region>.databricksapps.com/<path>	Raw PATs are rejected — use --auth-type databricks-cli

An App has its own hostname on databricksapps.com; it is not a path under the workspace host. The URL is assigned at app creation and cannot be changed — copy it from the Apps page in the workspace UI instead of constructing it. <path> is whatever route the app serves MCP on, commonly /mcp.

Configure in Claude Code / Claude Desktop

Add to your .mcp.json (project-level) or ~/.claude/mcp.json (global):

{
  "mcpServers": {
    "my-service": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "uc-mcp-proxy",
        "--url", "https://<workspace>/api/2.0/mcp/functions/main/default"
      ]
    }
  }
}

For Databricks Apps (OAuth token required):

{
  "mcpServers": {
    "my-app": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "uc-mcp-proxy",
        "--url", "https://<app-name>-<workspace-id>.<region>.databricksapps.com/mcp",
        "--auth-type", "databricks-cli"
      ]
    }
  }
}

CLI Flags

Flag	Description
--url	(required) Remote MCP server URL
--profile	Databricks CLI profile from ~/.databrickscfg (uses default if omitted)
--auth-type	Force a specific auth method (see below)

Authentication

The proxy uses the Databricks SDK for auth — it auto-detects the method from your environment, or you can force one with --auth-type.

Auth type	Managed / External	Apps
databricks-cli — token from ~/.databrickscfg	✅	✅ recommended
pat — personal access token	✅	❌ rejected
oauth-m2m — service principal	✅	✅ (needs CAN_USE on the app)
OAuth U2M — browser-based	✅	✅

Databricks Apps require an OAuth token. A raw PAT is rejected, so PAT auth fails against an App — but that is a limit on the token, not on the profile: having a PAT does not make an App unreachable, it just means you authenticate with --auth-type databricks-cli (or another OAuth route) instead.

oauth-m2m works against an App — verified end-to-end through the proxy with a service principal. Grant the principal CAN_USE on the app first; without that grant the App returns 401, which reads like a bad credential but is really a missing permission.

[sp-m2m]
host          = https://<workspace>.cloud.databricks.com
auth_type     = oauth-m2m
client_id     = <service-principal-application-id>
client_secret = <service-principal-oauth-secret>

uc-mcp-proxy --url https://<app>.../mcp --profile sp-m2m --auth-type oauth-m2m --no-auto-login

Use --no-auto-login for service principals: auto-login only applies to databricks-cli profiles, and M2M is meant to run headless anyway.

Set Up Databricks CLI Auth

# Install Databricks CLI
pip install databricks-cli
# or
brew install databricks/tap/databricks

# Configure auth (interactive)
databricks configure

# Or set env vars
export DATABRICKS_HOST=https://your-workspace.azuredatabricks.net
export DATABRICKS_TOKEN=your-pat-token

To use a named profile:

databricks configure --profile myprofile
# then use: uc-mcp-proxy --url <url> --profile myprofile

How It Works

1. Starts a local MCP stdio server (Claude connects to this)
2. Opens an HTTP connection to the remote Databricks MCP server
3. Injects a fresh OAuth token on every outbound request
4. Bridges messages bidirectionally between the two transports

Troubleshooting

Tools not appearing in Claude Restart Claude Code/Desktop after editing .mcp.json. The proxy must be running — check with uvx uc-mcp-proxy --url <url> directly in terminal.

401 Unauthorized

• For Apps: make sure you're using --auth-type databricks-cli, not PAT
• For Apps: a 401 also means "identity has no CAN_USE on this app" — check the app's Permissions before concluding the credential is wrong
• For Managed/External: check your token is valid — databricks auth env
• Try --profile to specify a non-default profile

Connection refused / timeout

• Verify the URL is correct — check workspace URL and endpoint path
• For Apps: the host is <app-name>-<workspace-id>.<region>.databricksapps.com, not a path on the workspace host — a workspace-path URL will not resolve
• For Apps: ensure the Databricks App is running (databricks bundle run)
• Check your workspace firewall/network policies

uvx: command not found Install uv via pip install uv or brew install uv. Alternatively, install uc-mcp-proxy directly: pip install uc-mcp-proxy (always verify the package source is pypi.org/project/uc-mcp-proxy).