Databricks Unity Gateway: govern models, agents and MCP

A coding agent on a developer's laptop sends a prompt with a customer's card number pasted into it. On a Databricks workspace that runs its AI traffic through Unity Gateway, the number never reaches the model: a policy catches it on the way in and the agent gets a short reply that names the rule it broke. That one round trip shows what Unity Gateway is for. It is the single door that every model call, every MCPModel Context ProtocolAn open standard for connecting AI applications to tools and data. A system offered once as an MCP server works in any application that speaks MCP. tool call and every agent on Databricks goes through. At that door, access, content, rate, spend and routing are each decided once, for everyone.

Unity Gateway became generally available on 4 August 2026. It replaced the older AI Gateway, whose endpoints each belonged to one workspace. It is built on Unity CatalogUnity CatalogDatabricks' governance layer: one place that names every table, file volume, model and function as catalog.schema.object, decides who may use each, and records lineage and access., so a model or an MCP server is now a securable like a table, and you grant it the same way.

Follow one request through it

Pick a request and send it. Each box is a step the gateway can stop it at, and the line under the boxes is what the caller receives.

Try itSend one request through Unity Gateway

The request

·An ordinary prompt·A user with no grant·A card number in the prompt·The 61st request in a minute·A user past their budget·The first model is down·An unsafe reply

1. Sign-in1Who is calling: a user or a service principal
2. Grant2EXECUTE on the model service in Unity Catalog
3. Input policy3Service policies on the request (ON CALL)
4. Rate limit4Requests or tokens a minute, per user, group or service
5. Budget5Monthly spend, shared or per user
6. Route6Traffic split, then fallbacks on 429 or 5xx
7. Model7The destination model answers
8. Output policy8Service policies on the response (ON RESULT)
9. Logged9system.ai_gateway.usage and billing records

The caller gets:200, a turn naming the policy

Two details in there catch teams out. A guardrail that blocks a request does not return an error. It returns a normal HTTP 200 reply that names the policy, because chat clients resend the whole conversation and an error would break every turn after it. So if your code only checks the status code, it will treat a blocked request as a success. A Rate LimitRate LimitThe most an API lets you send in a period, counted in requests and tokens per minute. Past it, requests fail with a 429 error until capacity comes back, so code waits and retries., on the other hand, is a plain 429, and your client needs to retry it with exponential backoff.

The 3 things it governs

Databricks splits the job into 3 layers, and each one answers a different question.

An agent counts as an asset too. It is registered as a Unity Catalog model, and the tools it calls are registered as MCP services, functions and connections. So the question "what can this agent reach?" has the same answer as "what was it granted?". And because an agent usually acts as the person who started it, everything that person can reach is in its range. That is the reason the behaviour layer exists.

The default to change first

Out of the box, every account user has EXECUTE on the model services Databricks provides in system.ai. That is convenient on day one, but nothing is governed until you narrow it. To give only one group the right to call a service, remove the broad access to the system.ai schema, then grant EXECUTE service by service:

databricks grants update model_service main.default.my_model_service \
  --json '{"changes": [{"principal": "data-team", "add": ["EXECUTE"]}]}'

Every model service needs EXECUTE on the service itself, plus USE CATALOG and USE SCHEMA on the catalog and schema it lives in. A grant on the underlying model does not grant the service. If you used the earlier preview of foundation model permissions, check this first: the permissions you set on models there do not carry over to the services.

Then a workspace admin can turn on the Enforce Unity Gateway setting. It switches off the legacy pay-per-token endpoints (the databricks- models), so all pay-per-token traffic has to go through a model service. Anything still calling a legacy endpoint gets PERMISSION_DENIED, so move those callers before you flip it. The usage table system.serving.endpoint_usage shows which callers are left.

Guardrails: what the built-in policies catch

Service policies are in Beta, behind the Unity Ai Gateway Service Policies preview. The built-in ones cover the common risks:

• Sensitive data. detect_sensitive_data finds card numbers, Social Security numbers and similar patterns. It either blocks the request or redacts the digits and lets the rest through, and it is pattern-based, so it adds no model call.
• Jailbreaks and Prompt InjectionPrompt InjectionAn attack that hides instructions in text a model reads, such as a web page, an email or a file, so the model follows the attacker instead of you.. block_jailbreak reads the model's input. On an MCP service it can also read the tool call, the tool's result, or both. That matters because injected instructions can arrive inside a tool result, not only in the user's prompt.
• Unsafe content and hallucination. block_unsafe_content and block_hallucination are model-backed checks. Several of them at the same rank run side by side, so stacking them costs the latency of the slowest one, not the sum of all of them.

The fourth decision only exists on MCP services: ASK. It pauses a tool call, such as a push to a Git repository, until the user approves it. Approval is the Human in the LoopHuman in the LoopA person approves, corrects or stops an AI system at set points, such as before an agent sends, pays or deletes something. step agents need for actions that cannot be undone, and here it is enforced by the gateway rather than trusted to the agent's prompt.

Put a coding agent behind it

Claude Code, Codex, Gemini CLI and OpenCode can all go through the gateway, using the Unity Gateway CLI:

uv tool install git+https://github.com/databricks/unity-gateway
ug claude        # or: ug codex, ug gemini, ug opencode, ug copilot, ug pi
ug mcp add       # pick from the MCP servers you were granted

The agent looks the same to the developer, and /model switches between the models the organisation allows. The difference is that its models, its MCP servers and its token spend now sit under the same grants, limits, budgets and billing records as the rest of your AI use. Our guide to Claude Code's permissions covers the other half: what the agent may do on the laptop itself.

What it costs: the logs, not the gateway

Governing models and MCP servers through Unity Gateway is free. The only paid parts are the 2 logs, and you pay for each one only when it is switched on:

Each payload is counted in 1 KB steps. Take an agent that makes 200,000 calls a month, where each logged request and response together come to about 30 KB. With inference tables on, that is about 6 GB, or roughly $0.60 a month. The logs are rarely what you notice on the bill. The tokens are: Databricks-hosted models are billed at their usual rates, and an external provider bills you directly. Our cost calculator prices the tokens for any model.

Budgets block, but they are not a cap

A budget scoped to Unity Gateway can send an alert, block usage, or both, for everyone together or for each user. It covers pay-per-token models, ai_query, Genie and, in Beta, external providers. It does not cover provisioned throughput or traffic that bypasses the gateway. A block takes effect within moments.

It works from an estimate, though. A user may be blocked a little before the threshold or spend a little past it, and a request that is already running is not cut off. Databricks says plainly not to treat a budget as an absolute cap. Set thresholds with some headroom, and use the billing table to check the real figure:

SELECT identity_metadata.run_by AS caller,
       usage_metadata.ai_gateway.destination_model AS model,
       SUM(usage_quantity) AS dbus
FROM system.billing.usage
WHERE usage_metadata.ai_gateway.endpoint_name IS NOT NULL
  AND usage_date >= current_date() - INTERVAL 30 DAYS
GROUP BY ALL
ORDER BY dbus DESC;

system.billing.usage updates every few hours, so it can show less than a budget alert you just received. The two catch up with each other.

Where to start

If your workspace calls more than one model, or has any agent with tools, start with 3 changes:

1. Tighten the grants on system.ai.
2. Set a default per-user rate limit on each model service.
3. Add one per-user budget with an alert set below the block.

Turn on guardrails service by service: a support chatbot needs different rules from a coding agent. When you split traffic between 2 models, Unity Gateway keeps each session on one of them, so Prompt CachingPrompt CachingLetting the API keep the processed start of a prompt for a few minutes, so later requests that begin the same way are cheaper and quicker. keeps working. How to choose the models in that split is in model routing.