Set up remote MCP

The remote MCP server uses an HTTP connection and makes calls to dbt-mcp hosted on the cloud-based dbt platform. This setup requires no local installation and is ideal for data consumption use cases.

When to use remote MCP

The remote MCP server is the ideal choice when:

• You don't want to or are restricted from installing additional software (uvx, dbt-mcp) on your system.
• Your primary use case is consumption-based: querying metrics, exploring metadata, viewing lineage.
• You need access to Semantic Layer and Discovery APIs without maintaining a local dbt project.
• You don't need to execute CLI commands. Remote MCP does not support dbt CLI commands (dbt run, dbt build, dbt test, and more). If you need to execute dbt CLI commands, use the local MCP server instead.

info

Only text_to_sql consumes dbt Copilot credits. Other MCP tools do not.

When your account runs out of Copilot credits, the remote MCP server blocks all tools that run through it, even tools invoked from a local MCP server and proxied to remote MCP (like SQL and remote Fusion tools).

If you reach your dbt Copilot usage limit, all tools will be blocked until your Copilot credits reset. If you need help, please reach out to your account manager.

Choose your auth method

Use this table to choose the right token type before you start:

If you need...	Use...
Fastest first-time setup	OAuth (if supported by your client)
execute_sql tool	Personal Access Token (PAT). Service tokens do not work for execute_sql
Shared or team setup	Service token
CI or automation	Service token

Loading table...

execute_sql requires a PAT

The execute_sql tool does not work with service tokens. You must use a Personal Access Token (PAT) in the Authorization header when using this tool.

Setup instructions

1. Ensure that you have AI features turned on.
2. Obtain the following information from dbt platform:

• dbt platform host: Use this to form the full URL. For example, replace YOUR_DBT_HOST_URL here: https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/. It may look like: https://cloud.getdbt.com/api/ai/v1/mcp/. If you have a multi-cell account, the host URL will be in the ACCOUNT_PREFIX.us1.dbt.com format. For more information, refer to Access, Regions, & IP addresses.
• Production environment ID: You can find this on the Orchestration page in the dbt platform. Use this to set an x-dbt-prod-environment-id header.
• Token: Generate either a personal access token or a service token. To fully utilize remote MCP, the token must have Semantic Layer and Developer permissions.
• If you plan to use execute_sql, you must use a Personal Access Token (PAT). Service tokens do not work for this tool. For other tools that require x-dbt-user-id, a PAT is also required.

3. For the remote MCP, you will pass on headers through the JSON blob to configure required fields:

Configuration for APIs and SQL tools

Header	Required	Description
Authorization	Required	Your personal access token (PAT) or service token from the dbt platform. Note: When using the Semantic Layer, we recommended to use a PAT. If you're using a service token, make sure that it has at least Semantic Layer Only, Metadata Only, and Developer permissions. The value must be in the format Token YOUR_DBT_ACCESS_TOKEN or Bearer YOUR_DBT_ACCESS_TOKEN, replacing YOUR_DBT_ACCESS_TOKEN with your actual token.
x-dbt-prod-environment-id	Required	Your dbt platform production environment ID

Loading table...

Additional configuration for SQL tools

Header	Required	Description
x-dbt-dev-environment-id	Required for execute_sql	Your dbt platform development environment ID
x-dbt-user-id	Required for execute_sql	Your dbt platform user ID (see docs)

Loading table...

Additional configuration for Fusion tools

Fusion tools, by default, defer to the environment provided via x-dbt-prod-environment-id for model and table metadata.

Header	Required	Description
x-dbt-dev-environment-id	Required	Your dbt platform development environment ID
x-dbt-user-id	Required	Your dbt platform user ID (see docs)
x-dbt-fusion-disable-defer	Optional	Default: false. When set to true, Fusion tools will not defer to the production environment and use the models and table metadata from the development environment (x-dbt-dev-environment-id) instead.

Loading table...

Configuration to disable tools

Header	Required	Description
x-dbt-disable-tools	Optional	A comma-separated list of tools to disable. For instance: get_all_models,text_to_sql,list_entities
x-dbt-disable-toolsets	Optional	A comma-separated list of toolsets to disable. For instance: semantic_layer,sql,discovery

Loading table...

4. After establishing which headers you need, you can follow the examples to create your own agent.

The MCP protocol is programming language and framework agnostic, so use whatever helps you build agents. Alternatively, you can connect the remote dbt MCP server to MCP clients that support header-based authentication. You can use this example Cursor configuration, replacing YOUR_DBT_HOST_URL, YOUR_DBT_ACCESS_TOKEN, PROD-ID, USER-ID, and DEV-ID with your information:

Use numeric IDs, not full URLs

Header values like x-dbt-prod-environment-id and x-dbt-user-id expect numeric IDs, not full URLs. The host in the url field should include https://, but ID headers must be integers only:

# ✅ Correct
"url": "https://cloud.getdbt.com/api/ai/v1/mcp/"
"x-dbt-prod-environment-id": "54321"
"x-dbt-user-id": "123"

# ❌ Wrong — don't paste full URLs into ID headers
"x-dbt-prod-environment-id": "https://cloud.getdbt.com/deploy/12345/projects/67890/environments/54321"
"x-dbt-user-id": "https://cloud.getdbt.com/settings/profile"

Example configuration:

{
  "mcpServers": {
    "dbt": {
      "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/",
      "headers": {
       "Authorization": "Token YOUR_DBT_ACCESS_TOKEN",
        "x-dbt-prod-environment-id": "DBT_PROD_ENV_ID",
        "x-dbt-user-id": "DBT_USER_ID",
        "x-dbt-dev-environment-id": "DBT_DEV_ENV_ID"
      }
    }
  }
}

For local MCP, configuration is done via environment variables; see the Environment variables reference.

Was this page helpful?

Privacy policyCreate a GitHub issue

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.