Skip to main content

Set up remote MCP StarterEnterpriseEnterprise +Beta

The remote server uses an HTTP connection and makes calls to dbt-mcp hosted on the cloud-based dbt platform.

info

Remote dbt MCP tools are dependent on available dbt Copilot credits. Note that the SQL and remote Fusion tools are in this category, even when they are used and proxied through the local dbt MCP server. Most MCP tools don't consume dbt Copilot credits. However, text_to_sql usage does count toward your dbt Copilot consumption.

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.

  1. Ensure that you have AI Features turned on.
  2. Obtain the following information from dbt Platform:
  • dbt Cloud host: Use this to form the full URL. For example, replace <host> here: https://<host>/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, check out our docs.
  • Production environment ID: This can be found on the Orchestration page of dbt Cloud. Use this to set an x-dbt-prod-environment-id header.
  • Token: Please generate either a personal access token or a service token. In terms of permissions, to fully utilize remote MCP, it must be configured with Semantic Layer and Developer permissions.
  1. For the remote MCP, you will pass on headers through the JSON blob to configure required fields:

Configuration for APIs and SQL tools

HeaderRequiredDescription
TokenRequiredYour personal access token or service token from the dbt platform.
Note: When using the Semantic Layer, it is recommended to use a personal access token. If you're using a service token, make sure that it has at least Semantic Layer Only, Metadata Only, and Developer permissions.
x-dbt-prod-environment-idRequiredYour dbt Cloud production environment ID

Additional configuration for SQL tools

HeaderRequiredDescription
x-dbt-dev-environment-idRequired for execute_sqlYour dbt Cloud development environment ID
x-dbt-user-idRequired for execute_sqlYour dbt Cloud user ID (docs)

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.

HeaderRequiredDescription
x-dbt-dev-environment-idRequiredYour dbt platform development environment ID
x-dbt-user-idRequiredYour dbt platform user ID (docs)
x-dbt-fusion-disable-deferOptionalDefault: 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.

Configuration to disable tools

HeaderRequiredDescription
x-dbt-disable-toolsOptionalA comma-separated list of tools to disable. For instance: get_all_models,text_to_sql,list_entities
x-dbt-disable-toolsetsOptionalA comma-separated list of toolsets to disable. For instance: semantic_layer,sql,discovery
  1. After establishing which headers you need, you can follow the examples here 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 <host>, <token>, <prod-id>, <user-id>, and <dev-id> with your information:

{
  "mcpServers": {
    "dbt": {
      "url": "https://<host>/api/ai/v1/mcp/",
      "headers": {
       "Authorization": "token <token>",
        "x-dbt-prod-environment-id": "<prod-id>",
        "x-dbt-user-id": "<user-id>",
        "x-dbt-dev-environment-id": "<dev-id>"
      }
    }
  }
}

Was this page helpful?

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

0