Skip to main content

Set up the dbt MCP server

dbt's remote MCP server gives AI clients access to your dbt Cloud project — querying metrics via the Semantic Layer, exploring model and lineage metadata, and running SQL against your warehouse. This guide covers enabling dbt AI features, generating an access token, collecting the required IDs, and connecting the server to MintMCP.

Prerequisites​

  • dbt Cloud account on the Starter, Team, or Enterprise plan
  • Account Admin role in dbt Cloud
  • At least one Production environment configured in your dbt Cloud project
  • AI features (dbt Copilot) enabled on the account

Enable dbt Copilot​

  1. Click your account name in the left navigation and select Account settings.
  2. Under Settings, click Edit in the top-right corner.
  3. Enable Enable account access to dbt Copilot features.
  4. Click Save.

Generate an access token​

Choose a token type based on how your team will use the server:

ScenarioToken type
Individual use or need execute_sqlPersonal Access Token (PAT)
Shared team or CI/automation setupService token

The execute_sql tool requires a PAT — service tokens cannot use it.

A PAT authenticates as you personally and is required if you need the execute_sql tool.

  1. Click your account name and select Account settings.
  2. In the left sidebar, expand API tokens and click Personal tokens.
  3. Click Create personal access token.
  4. Enter a descriptive name (e.g., MintMCP dbt MCP).
  5. Click Save.
  6. Copy the token immediately — it is shown only once.

Collect your environment IDs and user ID​

The dbt MCP server requires numeric IDs — not full URLs — for all ID headers.

Production environment ID​

  1. In dbt Cloud, go to Deploy → Environments.
  2. Click your Production environment.
  3. Copy the numeric ID from the page URL: …/environments/**54321**/…

Development environment ID (required for execute_sql and Fusion tools)​

  1. Go to Deploy → Environments.
  2. Click your Development environment.
  3. Copy the numeric ID from the URL.

User ID​

  1. Click your account name and select Account settings.
  2. Go to Access → Users and click your user.
  3. Copy the numeric ID from the page URL: …/users/**67891**

Determine your dbt host URL​

For standard dbt Cloud accounts, the MCP server URL is:

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

For multi-cell accounts (format abc123.us1.dbt.com), use:

https://abc123.us1.dbt.com/api/ai/v1/mcp/

Add dbt to MintMCP​

  1. In the MintMCP admin portal, go to your MCP store and click + Add Remote MCP.

  2. Enter the server URL for your account (see above).

  3. Set Connection type to Shared credentials.

  4. Set Auth method to Bearer token.

  5. Paste your PAT or service token as the Bearer token value.

  6. Add the following required request headers:

    HeaderValueNotes
    x-dbt-prod-environment-idYour production environment IDRequired for all tools
    x-dbt-dev-environment-idYour development environment IDRequired for execute_sql and Fusion tools
    x-dbt-user-idYour numeric user IDRequired for execute_sql and Fusion tools

    If your MintMCP plan supports optional tool filtering, you can also add:

    HeaderValueNotes
    x-dbt-disable-toolsetssql,fusion (example)Comma-separated toolset names to disable
    x-dbt-disable-toolsexecute_sql,text_to_sql (example)Comma-separated tool names to disable

  7. Click Save.

Security considerations​

  • Keep your PAT or service token secure — anyone with it can query your dbt Cloud project under your permissions.
  • PATs inherit the permissions of the user who created them. If that user's access changes, the token's effective access changes too.
  • Service tokens are scoped to the permission sets you assign and do not inherit user-level permissions — prefer them for shared deployments.
  • Only text_to_sql consumes dbt Copilot credits. If credits run out, all MCP tools are blocked until credits are replenished.
  • Rotate tokens regularly via Account settings → API tokens.