Databricks MCP Server: Tools, Setup, and Governing Agent Access

What the Databricks MCP server is

The Databricks MCP server is not a single server. Databricks exposes a set of managed MCP endpoints from a workspace, each with its own URL. Model Context Protocol is the open standard that lets an agent discover and call tools on an external system, and Databricks publishes its surface as several narrow servers rather than one wide one.

In Databricks the URLs live under Agents > MCP Servers. Five shapes:

Each path sits under https://<workspace-hostname>. Notice how much the URL fixes: a functions endpoint is pinned to one catalog and schema, vector search to one index, Genie to one space. It is the cheapest scoping you will get, applied before any tool list is negotiated — registering analytics.reporting gives an agent no path to finance.raw.

The two endpoints without that boundary are /mcp/sql and /mcp/functions/system/ai: workspace-wide, and both execute. Most of this post is downstream of that.

What agents actually do with it

The useful patterns chain endpoints together.

• Self-serve analytics. An agent routes a question to a Genie space carrying the data team’s semantics, and answers without writing SQL.
• Retrieval over internal docs. A support agent queries a vector index for runbook chunks, then a UC function for the customer’s plan.
• Pipeline triage. A dashboard looks wrong. The agent compares row counts across partitions, then checks the last load timestamp.
• Feature lookup mid-turn. A UC function wrapping a feature table gives an agent a reviewed interface to a model input, not a guessed join.

The read-versus-write split is sharp, and the docs are explicit. Genie endpoints are read-only. Databricks SQL can execute writes depending on permissions. Vector search and UC functions sit in between: a registered function can mutate state if someone wrote it that way. So two endpoints are safe by construction, two only if the underlying objects are, and one executes anything.

Why connecting it raw breaks at team scale

One analyst on a Genie space is fine. A team wiring SQL into every agent is not.

Compute cost has no natural ceiling. Jobs, clusters, and warehouses bill for the time they run, and an agent that can call the SQL endpoint can trigger a scan across a large table, then do it again in a retry loop when the first attempt times out. A misjudged SELECT * against a wide Delta table is not a bug you catch in review; it is a line item you notice at month end. Of every MCP server a platform team might connect, this is the strongest argument for approval gates.

Blast radius extends into production data. The endpoint that answers a question can, with the wrong grants behind it, run a DELETE or an INSERT. The agent authenticates as a Databricks identity, so whatever that identity may do, the agent may do — including rights a service principal picked up years ago for a migration.

Shared PATs erase the governance model. Every request arrives as one identity, so row filters, column masks, and catalog grants stop tracking the human behind it.

Nobody can reconstruct what ran. Databricks logs the query, not the fact that your triage agent issued it from a prompt pasted into a Slack thread. When a warehouse spikes at 3am, query history tells you what executed, not why.

None of this argues against connecting Databricks. It argues for a control plane in front of it, which is what an MCP gateway is for.

Want to see this in practice?

Register a Genie space as a read-only MCP server and hand your team a governed analytics agent in one sitting.

Get started free

Connecting the Databricks MCP server through TrueFoundry

Databricks is not provisioned from the TrueFoundry managed catalogue. You register it through Connect any Remote MCP Server using an OAuth app you create yourself — more work than a one-click managed server, and the reason you keep full control over scopes. You will need a workspace with managed MCP servers enabled.

Step 1 — Create the OAuth app. In the Databricks account console, go to Settings > App Connections and register a confidential client. Choose your scopes — the docs name all-apis, genie, and unity-catalog — copy the Client ID and Client Secret, and set the redirect URI to:

https://<tfy-control-plane-base-url>/api/svc/v1/llm-gateway/mcp-servers/oauth2/callback

That is the self-registered callback, not the one managed catalogue servers use, so do not copy a value from another guide. Pick scopes narrowly: if the agent only needs Genie, genie is enough.

Step 2 — Open the picker. Go to MCP Gateway, click Add Server, and choose Connect any Remote MCP Server.

Step 3 — Fill in the server. Give it a lowercase, hyphenated Name — for the endpoint, not the vendor, since databricks-genie-revenue says more than databricks — then paste the MCP URL.

Step 4 — Configure OAuth2. Under Auth Data, select OAuth2 and the Authorization Code grant, then supply the Client ID, Client Secret, and Token URL.

Authorization Code is what makes per-user access work. Client Credentials is server-to-server, so every call lands as one identity — the same problem as a shared PAT. Store the secret in the TrueFoundry secrets store and reference its FQN.

Step 5 — Save, then connect. Open the server’s Tools section and click Connect Now. After OAuth succeeds, the Databricks tools appear.

Then repeat per endpoint. Two Genie spaces, one index, and SQL is four MCP servers — not overhead, but the governance boundary.

How authentication actually works

TrueFoundry separates inbound authentication, how a client proves itself to the gateway, from outbound, how the gateway reaches Databricks.

Inbound supports four methods:

Virtual Account tokens give every request identical access, so they cannot express per-user Databricks identity. Where grants differ by person, use a PAT or IdP token.

Outbound for Databricks is one of two options:

This is where the second thread lands. Unity Catalog permissions still apply to each Databricks identity. The gateway decides which tools exist; Unity Catalog decides which objects the authorizing identity may read or write. Choose Authorization Code and the two compose: an agent acting for an analyst inherits that analyst’s grants, row filters, and column masks — governance your data team already built, applied to agent traffic for free. Choose a shared PAT and the rules still apply, just to a principal unrelated to the asker.

Scoping tools before you ship

Once authorized, the Tools tab lists what the endpoint exposes.

Per-tool toggles. Turn a tool off and it is omitted from tools/list entirely — structural, not prompt-layer filtering. It is how you publish four reviewed functions out of thirty.

Enable new tools by default. Left on, upstream additions appear automatically. Turned off, only tools you enabled are available — clearly right for a UC functions endpoint, where a function an analyst registers should not silently become callable.

Bulk Action. Turns every row into a checkbox with Select all, so a schema full of functions becomes a short allowlist in one save.

Clicking the pencil opens Edit Tool:

The Description override takes up to 20,000 characters and steers tool selection when a name is opaque: get_cust_agg_v3 means nothing to a model, while one naming its grain and cost profile means a lot.

MCP Tool Annotations mark a tool Read-only or Destructive, setting readOnlyHint or destructiveHint. Mark Genie read-only and SQL and Python destructive, and the policies below gate a whole class without naming every tool.

Who can do what: collaborator roles

Access control attaches to users, teams, or virtual accounts on two dimensions: which servers an identity reaches, and which tools it can call.

Because each endpoint is its own server, these roles slice naturally. Give the analytics org User on the Genie servers; keep User on the SQL server to the few who should issue ad-hoc queries at all, and put a data platform engineer in the Approver seat there — the same MCP access control model as the rest of your registry.

Ready to split read from execute?

Register Genie as read-only, put SQL behind approval, and give each team exactly the endpoint it needs.

Start free on TrueFoundry

Human approval for destructive tools

Disabling the SQL endpoint outright is the blunt instrument. Sometimes you do want an agent able to run a query — just not unattended. Databricks is the clearest case for approval policies in any MCP estate, because what you gate costs money every second it runs.

When a gated tool is called, the gateway holds the call, raises a request, and notifies approvers; once a human approves, calls succeed for a configurable window. Create a policy under AI Gateway → Policies → MCP Tool Approval, marked Beta in the console:

Each policy names the servers it gates and picks an approval scope:

For SQL and Python, all is defensible — there is no harmless tool on a general execution surface. For UC functions, annotate the writers Destructive and use destructive. Overlaps resolve most-specific-first: named > destructive > all.

Validity is Once or time-based in minutes. For execution endpoints Once matches the risk: a thirty-minute window is thirty minutes in which a retry loop can rerun the same expensive query on one approval. The most restrictive policy wins. Approvers are notified over Email, Slack, PagerDuty, or MS Teams:

Each request shows the tool, the policy, the requester, and the actual tool arguments — so the approver sees the SQL text or Python body before it runs. That is the most valuable detail here: a reviewer spots an unbounded scan or a missing partition predicate in seconds, exactly what a model misses.

While pending, the caller gets a JSON-RPC result carrying _meta.approval_status: "pending" rather than an error, so a well-behaved agent waits and retries. Grants are per requester, and a denial blocks nobody permanently — to block durably, disable the tool or remove the user.

Testing in the Tool Playground

Run the tools by hand first. Click Try next to any tool, fill in the parameters, and read the JSON response; Try is disabled for tools you turned off. This catches what is painful to debug later: a missing scope, a catalog the identity cannot see, a Genie space id from another workspace, or a mismatched index name.

Using it from your IDE

The How To Use tab carries your tenant-specific Gateway URL and ready-to-paste snippets.

It covers Claude Code, VS Code, Cursor, Windsurf, Codex, and the Python and TypeScript SDKs. Add MCP to Cursor writes the config; Show API Key reveals the token if a client needs one in a header. Take the URL from this tab rather than building it — a hand-built endpoint is the usual cause of a client that connects but lists no tools.

What you get once it is behind the gateway

Tool-level metrics. The MCP Metrics dashboard breaks down requests per second, latency at P50 through P99, failure rate by error type, and request count per tool.

Latency here is a proxy for cost: a tool whose P99 has quietly tripled is usually a query that outgrew its warehouse, and a dashboard is a better place to learn that than an invoice.

Full-request observability. Every call is traced with caller identity, tool name, inputs, and latency, exporting over OpenTelemetry. That closes the attribution gap: query history says a query ran; the trace says which agent, for which person, ran it. Pre-tool and post-tool guardrails also run policy on calls, catching PII in a result before it reaches the model.

Low overhead. The gateway adds roughly 3-4 ms of latency and handles 350+ RPS on a single vCPU — noise next to a warehouse round trip.

One registry. A Virtual MCP Server bundles tools from several servers behind one endpoint, so a reporting agent gets two Genie tools and one index, nothing else.

Revoking access

Tenant admins can wipe every stored credential from the three-dot menu next to Edit.

Revoke all tokens deletes every auth override and stored OAuth token for all users and virtual accounts on that server, takes effect on the next request, and is logged. It is irreversible; everyone re-runs consent.

One limit: it clears tokens at the gateway only, not the grant in Databricks. In a real incident, also revoke the app connection in the Databricks account console.

Gotchas worth knowing

Workspace IP restrictions will bite. If the workspace has IP access lists, allow egress from wherever the MCP Gateway connects. This is the most common reason a correct configuration returns nothing, and it looks like an auth failure when it is a network one.

The system AI Python endpoint is a code execution tool. /mcp/functions/system/ai sits alongside the data endpoints, which makes it easy to register casually. Treat it like shell access: separate server, tiny collaborator list, approval on everything. And where a Genie space can answer a question, route it there instead of SQL.

Scope creep at the OAuth app. all-apis is the easy answer when something breaks, and once set nobody narrows it. Start with genie or unity-catalog and widen only when a call fails. [VERIFY] The scope required per endpoint type is not enumerated in the TrueFoundry docs, so check Databricks’ own scope reference before locking a production app down.

Related reading

• What Is an MCP Gateway: Architecture and Use Cases — the primer behind this post
• MCP Access Control: Securing AI Agents with an MCP Gateway — permissions in practice
• MCP Authentication Explained — inbound and outbound auth
• Virtual MCP Server Explained — bundling tools from several servers
• MCP Server Security Best Practices — the hardening checklist

Conclusion

Most MCP servers give an agent information. The Databricks MCP server gives it a compute platform, and that changes what careful looks like. A poorly scoped issue tracker creates noise; a poorly scoped SQL endpoint creates spend, and maybe a mutation to production.

Both threads have one answer. Register each endpoint separately so the URL does most of your scoping. Use OAuth2 Authorization Code so Unity Catalog stays the authority on what an agent can read. Then gate the execution surfaces behind approval with Once validity, so a human sees the query before a warehouse spins up. TrueFoundry gives you all three without building anything.

Connect the Databricks MCP server on TrueFoundry

Free to start