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.

  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)

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