dbt MCP Server: Tools, Setup, and How to Give Agents Metadata Safely

What the dbt MCP server is

The dbt MCP server is a remote MCP server operated by dbt Labs as part of dbt Cloud. Model Context Protocol is the open standard that lets an agent discover and call tools on an external system, and dbt’s implementation exposes your dbt Cloud project as callable tools. Per TrueFoundry’s docs, it can query metrics through the Semantic Layer, inspect model metadata, and run SQL.

Most data MCP servers give an agent data — Snowflake gives rows, Postgres gives rows. The dbt MCP server gives the map: which models exist, what they are built from, what each column means, which tests guard them, and how your organization defines a metric.

An honesty note: the docs describe capability areas, not a function list, and name one tool, execute_sql. Read anything beyond the families above off the Tools tab. [VERIFY] The docs page does not describe job-triggering or run-orchestration tools, so we have not claimed any.

Why metadata is the whole point

Here is the failure mode every analytics team recognizes. Someone asks an agent “what was net revenue retention last quarter.” The agent has warehouse credentials. It sees fct_subscriptions, dim_customers, and forty columns named things like mrr_amt and mrr_amount_usd. So it writes a query. A number comes back. It is wrong, and nothing says so.

The agent did not fail at SQL. It failed at definition. It guessed which column meant what, how churn should be treated, whether to include downgrades, and produced a confident answer built on four guesses. The dbt MCP server removes the guessing two ways.

Lineage and column context. An agent can ask what fct_subscriptions is built from, what each column means, and which tests pass on it — the context a human analyst has and a raw warehouse connection does not.

Named metrics. If net revenue retention is defined in the Semantic Layer, the agent does not compose it at all. It calls the metric by name with a grain and a dimension, and dbt compiles the SQL. The definition lives in version control, reviewed by its owners. That is why semantic layer MCP is its own search term: it separates an agent that writes queries from one that reads your agreed answers.

Which is the argument for connecting dbt before a warehouse. A text-to-SQL agent with no semantic layer is a hallucination machine with query permissions. With dbt in front of it, it has a dictionary.

What agents actually do with it

The useful workflows chain tools rather than calling one:

• Answer a business question correctly. List metrics, find the one matching the question, query it by name at the right grain, return the number plus its definition.
• Impact analysis before a change. Before an engineer alters a staging model, the agent walks lineage downstream and lists what would break.
• Explain a number that moved. Fetch the metric definition, walk up to the source models, check whether a failing test is the cause.
• Onboard someone new. Ask what models exist in a domain and how they connect, without a wiki that goes stale.

Three of those four need only metadata, which is why this integration is easy to make safe.

Where the real risk sits

We will be narrower here than for a warehouse server; inflating the risk would be dishonest.

Reading metadata is low-risk. Model names, column descriptions, lineage edges and test results are not customer data. Nothing leaks and nothing costs money.

execute_sql is where consequences start. The docs are explicit: disable it unless agents need direct SQL execution. It requires a development environment ID and a user ID to work at all, which is itself a signal. An agent looping on it against a large table is a warehouse bill, and depending on token reach, an egress path.

Semantic Layer queries are the second area. Safer than raw SQL because the definition is fixed, but not free. A metric query compiles to warehouse work, and an agent fanning one across every dimension over three years of daily grain generates an expensive scan.

Token scope multiplies both. A Personal Access Token inherits the user’s permissions; a service token uses assigned permission sets. A PAT belonging to an Account Admin, pasted into an agent config, gives that agent admin reach. The docs point at a service token for shared read access, the right default for anything unattended. And three headers plus a token, copied onto every analyst’s laptop, is unauditable at fifteen people.

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

Want to try it on your own project?

Register the dbt MCP server on TrueFoundry, leave metadata tools on, and turn execute_sql off in the same sitting.

Get started free

Connecting the dbt MCP server through TrueFoundry

dbt is not a one-click pick from the Managed MCPs catalogue. It goes in through Connect any Remote MCP Server, because it needs a token you create and headers only you know.

Prerequisites: a dbt Cloud account on Starter, Team or Enterprise; Account Admin access; a production environment, plus a development environment for execute_sql; dbt AI features enabled.

Step 1 — Create a dbt token. Use a Personal Access Token for individual access or when you need execute_sql; a service token for shared read access. Copy it immediately.

Step 2 — Collect the numeric IDs, from dbt Cloud URLs:

Step 3 — Open the picker. In MCP Gateway, click Add Server and choose Connect any Remote MCP Server.

Step 4 — Fill in the server. Supply a Name, Description, URL, Collaborators and Auth Data. The URL is the standard dbt MCP endpoint:

https://cloud.getdbt.com/api/ai/v1/mcp/

For multi-cell accounts, use your cell hostname, for example https://abc123.us1.dbt.com/api/ai/v1/mcp/.

Step 5 — Configure auth and headers. Add bearer-token authentication, configure the dbt token, and set the x-dbt-* headers. To hide risky tools at the connection itself, add x-dbt-disable-toolsets or x-dbt-disable-tools — two independent places to remove a tool, which is defense in depth.

How authentication actually works

TrueFoundry separates inbound auth, how a client proves itself to the gateway, from outbound, how the gateway proves itself to dbt.

Inbound supports TrueFoundry API keys, Virtual Account tokens for service-to-service callers, Identity Provider tokens for JWTs from your own IdP (Okta, Entra, Auth0, Cognito), and TrueFoundry OAuth for IDE tools. One caveat: Virtual Account tokens give every request identical access, so they cannot express per-user reach.

Outbound for dbt is the API Key type, with two credential modes.

Shared Credentials means one key for everyone: configure the header name and value once. This is the mode for a service token scoped to read-only metadata.

Individual Credentials means each user supplies their own key: configure the header with a placeholder such as Bearer {{API_KEY}}, and each person adds their token through the Auth Overrides tab.

The mapping is direct: Shared Credentials pairs with a service token; Individual Credentials pairs with PATs, and is what you want if execute_sql is enabled at all, since it keeps SQL execution scoped to the person who ran it.

Because dbt uses bearer-token auth, there is no OAuth consent screen or redirect URI here. If you configure OAuth2 on a self-registered remote server, the redirect URI is your control-plane callback, https://<tfy-control-plane-base-url>/api/svc/v1/llm-gateway/mcp-servers/oauth2/callback, not the auth.truefoundry.com callback used by Managed MCPs.

Scoping tools before you ship

The Tools tab is where you decide what agents can do — for dbt, the highest-value five minutes of the setup.

Per-tool toggles. Turn a tool off and it is omitted from tools/list entirely; clients never see it and it cannot be invoked. This is not prompt-layer filtering. The recommended dbt configuration is trivial: leave metadata and discovery tools on, turn execute_sql off unless a specific agent needs it. An agent that cannot call execute_sql cannot be talked into a runaway query.

Enable new tools by default. Left on, new upstream tools appear automatically. Turned off, only tools you enabled are available, so a future dbt release cannot quietly widen what agents can do.

Bulk Action. Switches each row to a checkbox so you can flip many tools at once.

Click the pencil on a tool to override how it is presented to the model:

The Description override, up to 20,000 characters, steers tool selection. Rewrite a metric-query tool to say “always call this instead of composing SQL for a known metric” and you nudge the model toward the definition you own. MCP Tool Annotations mark a tool Read-only or Destructive, setting readOnlyHint or destructiveHint.

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 inside a server it invokes.

So the platform team owns which dbt tools exist and other teams consume them — the same MCP access control model applied across your registry.

Ready to scope your first data server?

Connect dbt, keep lineage open, and hold SQL execution behind a human.

Start free on TrueFoundry

Human approval for the two risky tools

Disabling execute_sql is the blunt instrument. Sometimes you do want an agent to run SQL or fan out an expensive metric query, just not unattended. That is what tool approval policies are for, and they fit dbt because the gated set is small.

When a gated tool is called, the call is held, a request is created, and approvers are notified. After approval, calls succeed for a configurable window, then a fresh approval is required.

Create a policy under AI Gateway → Policies → MCP Tool Approval, currently marked Beta:

Each policy names the servers it gates and picks an approval scope: named gates only the tools you list, destructive gates every tool marked destructiveHint: true, all gates everything. When scopes overlap the most specific wins: named > destructive > all. For dbt, named is usually the honest choice: two or three tool names cover the real exposure, and gating all would have approvers clicking through lineage reads.

Validity is either Once, a single execution, or time-based, a duration in minutes. When policies conflict the most restrictive wins: Once beats a 10-minute window beats a 30-minute window. Approvers are notified over Email, Slack, PagerDuty or MS Teams:

Each request shows the tool, policy, requester and the actual arguments, so an approver can read the SQL before waving it through. 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 scoped per requester, and a denial does not permanently block anyone — to do that, disable the tool or remove the user.

Testing in the Tool Playground

Test by hand first. On the server detail page click Try next to a tool, fill in the parameters and read the JSON; Try is disabled for tools you turned off. This catches the boring dbt failures early: a wrong environment ID, dbt AI features not enabled, or an expired token.

Using it from your IDE

Open the How To Use tab for your tenant-specific Gateway URL and snippets.

It covers Claude Code, VS Code, Claude Desktop, Cursor, Windsurf, Codex, and the Python and TypeScript MCP SDKs. Add MCP to Cursor writes the config; Show API Key reveals the token.

Take the URL from this tab rather than assembling it yourself — it is tenant-specific, and a hand-built endpoint is the most common cause of a client that connects but lists no tools. The side effect matters: analysts configure a TrueFoundry endpoint, so the dbt credential never reaches a laptop.

What you get once it is behind the gateway

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

For a data server that is cost control, not just a dashboard: it is how you find out an agent calls a metric query two hundred times per run.

Full-request observability. Every tool call is traced with caller identity, tool name, inputs and latency, exported over OpenTelemetry. “Which agent ran that query, for whom, with what arguments” becomes a lookup, not an investigation.

Guardrails. Pre-tool and post-tool guardrails run policy on MCP tool calls.

Low overhead. The gateway adds roughly 3-4 ms of latency and handles 350+ RPS on a single vCPU, alongside 1,000+ LLMs.

One registry. Once several servers are registered you can bundle a curated subset of tools behind one endpoint with a Virtual MCP Server — dbt’s metadata tools plus a warehouse read tool, nothing else. That is the shape of a trustworthy analytics agent: dbt supplies the definitions, the warehouse supplies the rows.

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 token for all users and virtual accounts on that server, takes effect on the next request, and is recorded in Activity Logs. It is irreversible, everyone re-supplies credentials afterward, and only tenant admins see it. One limit matters: it clears tokens at the gateway only, not in dbt Cloud, so during an incident rotate the dbt token there too.

Gotchas worth knowing

The headers are the setup. Most failed first attempts are a missing or wrong x-dbt-* ID, not an auth problem. The dev environment ID and user ID are only needed for SQL and Fusion tools, so a connection looks healthy until the first SQL call.

Account Admin is required to set it up, not to use it. You need Account Admin in dbt Cloud to create the token and read the IDs. That does not mean the agent should carry admin reach — create it as an admin, then hand the agent a scoped service token.

Metadata is only as good as your project. An agent reading lineage on an undocumented project gets a map with no labels.

Related reading

• What Is an MCP Gateway — the architectural primer
• MCP Access Control — tool- and server-level permissions
• Virtual MCP Server Explained — bundling dbt metadata with warehouse reads
• MCP Authentication — inbound and outbound auth
• MCP Server Security Best Practices — the hardening checklist

Conclusion

The dbt MCP server is the most under-rated integration in the data stack, precisely because it does not look impressive. It does not return data. It returns definitions, lineage and documentation — the context separating an agent that answers a business question correctly from one that writes plausible SQL against columns it guessed at.

It is also unusually easy to make safe. The risk concentrates in execute_sql and expensive Semantic Layer queries, and both are addressable in minutes: a scoped service token instead of an admin PAT, per-tool toggles that leave metadata open and SQL closed, approval gates, and a traced call log.

Connect the dbt MCP server on TrueFoundry

Free to start