Connecting MCP clients to Databricks managed MCP through a stdio proxy

02What a managed MCP server is

Databricks runs the MCP server for you. You point an MCP-compatible client at a URL on your workspace, authenticate with workspace OAuth, and get a set of tools that are governed by Unity Catalog.

The endpoints are exposed under your workspace host at /api/2.0/mcp/… — same hostname and auth surface as the rest of the Databricks REST API. You don't deploy, version, or scale anything. The tradeoff: you lose the per-request control that a custom MCP server gives you (warehouse pinning, custom result shaping, additional tools). For most agent-to-data-and-tools wiring, that's a fair trade.

What you get out of the box

Four server types, each with its own URL pattern and OAuth scope. Pick whichever matches the data or tool surface your agent needs. You can wire several into the same MCP client; tool names get prefixed by server name, so they don't collide.

Two things to know about authorization

• Unity Catalog permissions are enforced server-side. The token's user (or service principal) must have the relevant grants on the underlying tables, functions, or indexes. The MCP layer doesn't elevate or bypass anything.
• OAuth scopes are server-typed. When connecting via the standard MCP OAuth flow (not the CLI-proxy shortcut), the OAuth app must include the scope for each server type your agent uses — vector-search, genie, sql, or unity-catalog. The CLI proxy path sidesteps this by reusing your existing CLI token.

04How the proxy works

Three boxes, two arrows, one auth round-trip. Walk through one request from the moment the agent calls a tool to the moment the result lands back in the client.

Trace through a single tool call

POST /api/2.0/mcp/sql HTTP/1.1
Host: <workspace-host>.cloud.databricks.com
Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer dapi…
Mcp-Session-Id: 7c1f…

{"jsonrpc":"2.0","method":"tools/call","params":{…},"id":1}

06Wiring it into your MCP client

Add server entries to .mcp.json (project-level) or ~/.claude/.mcp.json (global), then restart your MCP client — servers only load at startup. The full template lives in .mcp.json.example in this repo; below are the four canonical patterns.

Prerequisite — authenticate the CLI once

Both proxy variants reuse the OAuth token cached by the Databricks CLI. If you haven't authenticated against the workspace yet, do it now:

databricks auth login --host https://<workspace-host>.cloud.databricks.com --profile <your-profile>

This kicks off a browser flow, mints a token, and caches it at ~/.databricks/token-cache.json keyed on the profile name. From then on the proxy can mint Bearer tokens silently. The token auto-refreshes; you don't need to redo this until the refresh token expires.

Wire Vector Search

"vs-customer-support": {
  "command": "uv",
  "args": [
    "run", "./mcp_proxy.py",
    "--path",
    "/api/2.0/mcp/vector-search/prod/support",
    "--profile", "<your-profile>"
  ]
}

"vs-customer-support": {
  "type": "stdio",
  "command": "uvx",
  "args": [
    "uc-mcp-proxy",
    "--url", "https://<host>/api/2.0/mcp/vector-search/prod/support",
    "--auth-type", "databricks-cli",
    "--profile", "<your-profile>"
  ]
}

Wire a Genie space

"genie-billing": {
  "command": "uv",
  "args": [
    "run", "./mcp_proxy.py",
    "--path",
    "/api/2.0/mcp/genie/<genie-space-id>",
    "--profile", "<your-profile>"
  ]
}

"genie-billing": {
  "type": "stdio",
  "command": "uvx",
  "args": [
    "uc-mcp-proxy",
    "--url", "https://<host>/api/2.0/mcp/genie/<genie-space-id>",
    "--auth-type", "databricks-cli",
    "--profile", "<your-profile>"
  ]
}

Wire DBSQL

"dbsql": {
  "command": "uv",
  "args": [
    "run", "./mcp_proxy.py",
    "--path", "/api/2.0/mcp/sql",
    "--profile", "<your-profile>"
  ]
}

"dbsql": {
  "type": "stdio",
  "command": "uvx",
  "args": [
    "uc-mcp-proxy",
    "--url", "https://<host>/api/2.0/mcp/sql",
    "--auth-type", "databricks-cli",
    "--profile", "<your-profile>"
  ]
}

Wire UC Functions

"ucfunc-retail": {
  "command": "uv",
  "args": [
    "run", "./mcp_proxy.py",
    "--path",
    "/api/2.0/mcp/functions/prod/retail",
    "--profile", "<your-profile>"
  ]
}

"ucfunc-retail": {
  "type": "stdio",
  "command": "uvx",
  "args": [
    "uc-mcp-proxy",
    "--url", "https://<host>/api/2.0/mcp/functions/prod/retail",
    "--auth-type", "databricks-cli",
    "--profile", "<your-profile>"
  ]
}

08Verifying the wiring

After editing .mcp.json, restart your MCP client. The new tools should appear in the tool list, prefixed by the server name you gave them. Three quick checks turn up most wiring problems.

Check 1 — CLI auth is alive

Confirms the proxy will be able to mint a token. If this fails, fix the profile first; everything downstream depends on it.

databricks current-user me --profile <your-profile>
# expect: JSON with your userName, emails, id

Check 2 — the endpoint reaches your network

An unauthenticated curl should hit the endpoint and come back with a 401 Unauthorized. That's the signal that DNS, TLS, and the workspace are reachable; the server simply rejected the request because it had no Bearer token.

curl -i https://<workspace-host>.cloud.databricks.com/api/2.0/mcp/sql \
  -X POST -H "Content-Type: application/json" -d '{}'
# expect: HTTP/2 401 with a www-authenticate header

If you get 403, the workspace's IP allowlist is blocking you. If the request hangs or TLS fails, the workspace URL or your DNS is wrong.

Check 3 — the proxy starts cleanly

Run the proxy command directly, send a JSON-RPC initialize on stdin, and confirm a well-formed response comes back on stdout. This is the same call your MCP client makes at startup.

echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"manual","version":"1"}},"id":1}' \
  | uv run ./mcp_proxy.py --path /api/2.0/mcp/sql --profile <your-profile>
# expect: one JSON-RPC response with serverInfo and capabilities