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://<workspace>.databricks.com/apps/<app-name>/mcp	OAuth only — use --auth-type databricks-cli

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 required):

{
  "mcpServers": {
    "my-app": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "uc-mcp-proxy",
        "--url", "https://<workspace>.databricks.com/apps/<app-name>/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	✅	❌ not supported
oauth-m2m — service principal	✅	✅
OAuth U2M — browser-based	✅	✅

Databricks Apps require OAuth. PAT auth will fail with a 401. Always use --auth-type databricks-cli or OAuth for Apps.

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 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: 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).