Connect dbt

Connecting dbt gives the agents your transformation layer: model discovery, lineage from your dbt graph, test results as a policy signal, and job awareness for pipeline and incident work. There are two paths — dbt Cloud (API token + account ID) and dbt Core (point the agents at your local project). Until verified, dbt stays in 🟡 Evaluation on sample data.

Prerequisites

• Data Workers installed and registered with your coding agent (install guide)
• dbt Cloud: permission to create an API token and your account ID (visible in the dbt Cloud URL)
• dbt Core: a local project that has been compiled at least once (dbt compile or dbt run), so target/manifest.json exists

Step 1 — Create a least-privilege credential (dbt Cloud)

In dbt Cloud, create a read-only service token scoped to your account — metadata and read access is enough for discovery, lineage, and test results. Don’t reuse a personal token with admin rights, and never widen this token later; write behavior uses a separate credential (least-privilege guidance).

dbt Core has no credential: the agents read your project files locally.

Checkpoint: (Cloud) a read-only token exists, scoped to one account.

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.

# dbt Cloud
export DBT_CLOUD_API_TOKEN="<token>"
export DBT_CLOUD_ACCOUNT_ID="<account-id>"

For dbt Core, skip the token and point the agents at the project directory instead — tell your coding agent: “Connect my dbt Core project at <path-to-project>” (the directory containing dbt_project.yml). The agents read the compiled manifest.json from that project’s target/ directory.

Checkpoint: (Cloud) the variables are visible in the environment your coding agent starts from; (Core) the project path resolves and contains dbt_project.yml.

Step 3 — Verify

Setting a credential is not the same as a working connection. Ask:

Test the connection to my dbt catalog.

The agent makes a real call to dbt Cloud (or reads your local project). dbt shows 🟢 Connected only after that live test passes; a failure reports 🔴 with the reason. Full model: Verify your setup.

Checkpoint: dbt reports 🟢 Connected.

Supported operations

Operation	Status
Discovery (models, sources, lineage)	Supported
Catalog writes	Supported — write-scoped credential required
Policy (via dbt tests as the policy layer)	Supported
RBAC (role-based access enforcement)	Not supported
Credential vending (scoped, time-bound tokens)	Not supported

Unsupported operations return a clear error naming the connectors that do support them — never a pretend success.

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 (Cloud)	Token revoked, or wrong account ID	Re-check both values; the account ID is in your dbt Cloud URL
Lineage empty (Core)	Project never compiled, so no target/manifest.json	Run dbt compile in the project, then re-verify
Job questions fail (Core)	Jobs are a dbt Cloud feature	Expected — connect dbt Cloud for job awareness