Connect Databricks
Connecting Databricks puts the agents on your real workspace: Unity Catalog discovery and lineage, quality scoring on your tables, schema-change analysis, and cost and usage questions. Databricks is a full control-plane integration — with write-scoped credentials the agents can also perform governed catalog writes, access grants, policy attachment, and credential vending. Until verified, Databricks stays in 🟡 Evaluation on sample data.
Prerequisites
Section titled “Prerequisites”- Data Workers installed and registered with your coding agent (install guide)
- A Databricks workspace with Unity Catalog enabled
- Permission to create a service principal (or a personal access token for a trial run)
Step 1 — Create a least-privilege credential
Section titled “Step 1 — Create a least-privilege credential”Create a dedicated service principal and issue it a token. Grant read-only Unity Catalog access on the catalogs in scope — read agents can never mutate your systems, so this is enough to start:
GRANT USE CATALOG ON CATALOG <catalog> TO `<service-principal>`;GRANT USE SCHEMA ON CATALOG <catalog> TO `<service-principal>`;GRANT SELECT ON CATALOG <catalog> TO `<service-principal>`;Start with one catalog, verify, then widen scope. Write behavior uses a separate, explicitly enabled, write-scoped credential — never widen this one (least-privilege guidance).
Checkpoint: a service-principal token exists whose only grants are the three above.
Step 2 — Set the environment variables
Section titled “Step 2 — Set the environment variables”Set these in the shell your coding agent launches from, then restart the coding agent so the MCP server picks them up. The token stays on your machine; nothing is sent to Data Workers.
export DATABRICKS_HOST="<https://your-workspace.cloud.databricks.com>"export DATABRICKS_TOKEN="<token>"Checkpoint: the variables are visible in the environment your coding agent starts from.
Step 3 — Verify
Section titled “Step 3 — Verify”Setting a credential is not the same as a working connection. Ask:
Test the connection to my Databricks catalog.
The agent makes a real call to your workspace. Databricks shows 🟢 Connected only after that live test passes; a failure reports 🔴 with the reason. Full model: Verify your setup.
Checkpoint: Databricks reports 🟢 Connected.
Supported operations
Section titled “Supported operations”| Operation | Status |
|---|---|
| Discovery (catalogs, schemas, tables) | Supported |
| Catalog writes (create/update/drop objects) | Supported — write-scoped credential required |
| RBAC (role-based access enforcement) | Supported |
| Policy attachment and enforcement | Supported |
| Credential vending (scoped, time-bound tokens) | Supported |
Databricks (Unity Catalog) is one of the full control-plane connectors. Anything a credential doesn’t permit still fails with a clear error — never a pretend success.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
| Still answering from sample data | Variables set in a different shell, or agent not restarted | Set them in the shell your coding agent launches from, restart it |
| 🔴 with an auth error | Token expired or revoked | Issue a new token for the service principal and update DATABRICKS_TOKEN |
| 🔴 with a permission error | Service principal lacks USE CATALOG/SELECT on the target catalog | Re-check the Step 1 grants |
| 🔴 with a network/timeout error | Host can’t reach the workspace URL (VPN, IP access list) | Run the agents from a host with network access, or allowlist it |