| 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
uvx uc-mcp-proxy --url <MCP_SERVER_URL>
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
pip install databricks-cli
brew install databricks/tap/databricks
databricks configure
export DATABRICKS_HOST=https://your-workspace.azuredatabricks.net
export DATABRICKS_TOKEN=your-pat-token
To use a named profile:
databricks configure --profile myprofile
How It Works
- Starts a local MCP stdio server (Claude connects to this)
- Opens an HTTP connection to the remote Databricks MCP server
- Injects a fresh OAuth token on every outbound request
- 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).
