Connect dbt Cloud to Claude Code
Inspect dbt Cloud projects, jobs, environments and runs, and trigger or cancel a run. Add Toolspoke to Claude Code once and it can use 10 dbt Cloud actions. Your dbt Cloud credential stays in Toolspoke, and you choose which actions Claude Code may call.
Set it up in Claude Code
Three steps, the first one once for every toolkit you will ever add.
Add Toolspoke to Claude Code
Run it in your project, then /mcp to sign in
claude mcp add --transport http toolspoke https://toolspoke.com/mcpThe sign-in opens in your browser, and Toolspoke asks you to approve it.
Install dbt Cloud and connect it
Add dbt Cloud to a project in your Toolspoke workspace.
Service token. You provide it once, when you install the connector. Toolspoke encrypts it at rest and decrypts it only for the length of a single call, and the gateway attaches it to the outbound request itself, so it is never part of the arguments an agent sends.
- Service token
- dbt Cloud → Account settings → API tokens → Service tokens. Give it the narrowest permission set that covers what you want: Metadata Only or Job Viewer for reads, Job Admin if you intend to trigger runs. dbt accepts this on the Authorization header as either Token or Bearer; this connector sends Bearer.
- Account ID
- The number in your dbt Cloud URL after /accounts/. Every route in this connector is scoped to it.
Choose what Claude Code may do
All 10 actions start on. Switch off any of the 2 actions that change something in dbt Cloud, and Claude Code gets a refusal if it tries.
What you can ask Claude Code for
A few of the dbt Cloud actions that only read, so they are safe to try first.
- List the projects in the account, with each one's id, name, repository, connection and state
- List runs, newest last unless you order otherwise
- Fetch one run by id, with its status, timings, the commit it ran and what triggered it
- List the environments in the account, with each one's id, name, type, dbt version, project and connection
What Claude Code can do in dbt Cloud
8 actions read and 2 delete or permanently change something.
Reads
List projects
List the projects in the account, with each one's id, name, repository, connection and state. This is the natural first call and the cheapest proof that the service token, the account id and the host all agree, which is why it is the connection test. The project id it returns is what list_jobs, list_runs and list_environments filter on.
List jobs
List the jobs defined in the account, with each one's id, name, schedule, environment, dbt version and the commands it runs. Narrow by project_id or environment_id, an account with several projects returns everything otherwise. The job id here is what get_job and trigger_job_run take, and what list_runs filters on as job_definition_id. Note that a job's definition is what it is configured to do; whether it last succeeded is a question for list_runs.
Get job
Fetch one job by id, with its full definition: the steps it executes, its schedule, its environment, its threads and timeout, and its triggers. Ids come from list_jobs. Pass include_related with "most_recent_run" to get the job's definition and its last run in one call, which is usually what you actually wanted.
List runs
List runs, newest last unless you order otherwise. This is where "did the nightly job work" is answered. `status` is a number, not a word: 1 queued, 2 starting, 3 running, 10 success, 20 error, 30 cancelled. Narrow with job_definition_id for one job's history, or project_id for one project's. Pass order_by "-id" with a small limit to get the most recent runs first. Note that include_related here is narrower than on get_run and does not accept run_steps.
Get run
Fetch one run by id, with its status, timings, the commit it ran and what triggered it. Ids come from list_runs, or from the run trigger_job_run returned. include_related accepts trigger, job, environment, repository, run_steps, run_retries, used_repo_cache, repo_cache_restore, audit and debug_logs. For the per-command breakdown of a failure use get_run_steps, which asks for run_steps for you.
Get run steps
Fetch one run with its steps expanded: every dbt command the run executed, in order, with each one's status, timing and log output. This is the operation to reach for when a run failed and the question is which model broke. dbt has no route that lists a run's steps on their own, the only way to get them is GET on the run itself with run_steps requested, which is exactly what this does, so use it rather than trying to construct a steps URL. Its response is kept out of the audit log because dbt's step logs are raw stdout and routinely quote query text and error rows from the warehouse.
List run artifacts
List the artifact paths a completed run produced, manifest.json, catalog.json, run_results.json and the compiled and run SQL for each model. dbt answers with an array of file paths, not the files themselves. Use it to find out what a run left behind and whether docs were generated. Only completed runs have artifacts.
List environments
List the environments in the account, with each one's id, name, type, dbt version, project and connection. Environments are where jobs run, so this is how you tell a production environment's id from a staging one before filtering jobs or runs by it. This is the v2 account-wide listing; dbt's v3 API lists environments per project instead and returns more fields, which this connector does not use because everything else here is v2.
Deletes or permanently changes
Trigger job run
Start a run of a job. Classified destructive, and out of reach of a read-only or a write grant, for two reasons that both hold on every call: the run consumes billable compute from the moment dbt accepts it, and it executes the job's models against a real warehouse, which creates and replaces tables there. It is not undone by cancelling, cancel_run stops it part-way and leaves whatever it already built. `cause` is required by dbt and is written into the run's history as the reason it started, so put something a person reading the run list will understand. The overrides change what this one run does without editing the job: steps_override replaces the job's commands entirely, and schema_override sends the output somewhere other than the job's usual schema. dbt answers with the created run; watch it with get_run.
Cancel run
Stop a run that is queued or in progress. Classified destructive, and refused to a read-only or a write grant, because of what it leaves behind: dbt stops between commands rather than rolling anything back, so a cancelled build can end with some models rebuilt against fresh data and others still holding the previous run's, which is a harder state to reason about than either a finished run or a failed one. The compute already spent is not returned either. Check with get_run first that the run is actually the one you mean and is actually still going; dbt answers with the run object.
dbt Cloud in Claude Code: questions
Does Claude Code see my dbt Cloud credential?
No. The credential is stored encrypted in Toolspoke, and the gateway adds it to each call. Claude Code only ever talks to Toolspoke, and the dashboard shows the last four characters of the credential and nothing more.
Can I stop Claude Code from changing things in dbt Cloud?
Yes. Each of the 10 actions can be switched off for a project. Turn off the 2 that change something and Claude Code can only read.
Will 10 actions crowd Claude Code's context?
No. Toolspoke shows Claude Code five bridge tools, plus a guide where a toolkit has one, and Claude Code searches for the dbt Cloud action it needs when it needs it. Adding more toolkits does not add more tools to its list.
Can I add it once for every project?
Yes. Add --scope user to the command and Claude Code keeps Toolspoke in every project on this machine. Without it, the server is added to the project you ran the command in.
What does it cost?
Tool calls are free on every plan, and a dbt Cloud call does not run in a sandbox, so it bills nothing.
dbt Cloud in your other apps
Try dbt Cloud in Claude Code
Free to start, and tool calls cost nothing on any plan.