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. The self-hosted installation is not required for remote MCP use 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, Administrative, and Discovery APIs without maintaining a local dbt project.
- You don't need to execute CLI commands. Remote MCP does not support self-hosted dbt CLI commands (
dbt run,dbt build,dbt test, and more). If you need to execute dbt commands, use the self-hosted MCP server instead.
You don't need AI features enabled to use remote MCP. If an admin turns AI features off, text_to_sql is the only tool hidden and every other tool keeps working.
Choose your auth method
| If you need... | Use... |
|---|---|
Fastest first-time setup and your MCP client supports OAuth for HTTP servers (including execute_sql) | OAuth (remote) Available in public beta for Starter, Enterprise, and Enterprise+ accounts |
execute_sql with token-based auth, automation, shared setup, or clients without OAuth | Token-based with a personal access token (PAT) |
| Shared or team setup | Service token (token-based) |
| CI or automation | Service token (token-based) |
execute_sqlIf you connect with a token instead of OAuth, execute_sql only works with a personal access token (PAT). Service tokens won't work. To run SQL without creating a PAT, use OAuth (remote MCP) instead.
Permissions for remote MCP
Remote MCP checks your access when you connect and authorizes each tool call against the project, environment, job, or run it targets. These checks apply to OAuth, personal access tokens (PATs), and service tokens. A successful connection or a tool appearing in your client doesn't mean you can use that tool on every resource.
You don't need the Developer permission set just to connect. Ask your admin to grant the permissions needed for your workflow:
| Workflow | Required access |
|---|---|
Explore models and lineage, or generate SQL with text_to_sql | Metadata read access on the selected project. text_to_sql also requires AI features to be enabled. |
| Use Semantic Layer tools | Semantic Layer configuration read access on the selected project. |
Run plain SQL with execute_sql | Semantic Layer configuration read access on the project, a development environment, and warehouse credentials. Connect with OAuth or a PAT. |
Run SQL containing dbt Jinja, such as ref() or source() | The requirements for plain SQL, plus develop access. Production deferral also requires metadata read access. |
| Read or manage jobs and runs | The corresponding jobs or runs read or write permission for the target resource. Unfiltered account-wide listings require account-wide access. |
For available permission sets, refer to Enterprise permissions and Service tokens. PATs inherit the permissions of the user who created them. OAuth also restricts access to the scopes and projects you consented to.
Service tokens with metadata read access can use text_to_sql to generate SQL. They can't use execute_sql to run it.
OAuth (remote MCP) BetaStarterEnterpriseEnterprise +
OAuth lets you connect to the remote MCP server without copying API tokens into your MCP client, when your client supports OAuth for HTTP-based MCP servers.
Prerequisites
- Starter, Enterprise, or Enterprise+ account
- An MCP client that supports OAuth for remote (HTTP) MCP servers.
- Your MCP URL from Account settings → Access URLs → MCP Endpoint URL in dbt platform. Check out the next section MCP URL for more information.
AI features are enabled by default. Admins can turn them off or back on anytime. Turning them off doesn't disable remote MCP — it only hides the text_to_sql tool.
MCP URL
You can copy your full MCP URL from Account settings → Access URLs → MCP Endpoint URL in dbt platform, and paste it directly into your AI tool.
How it works
- In your MCP client, navigate to the connector or integrations settings and add your MCP URL (refer to MCP URL). For example, if you used Claude or ChatGPT, you would go to:
- Claude (web): Customize → Connectors → + → Add custom connector
- ChatGPT: Settings → Apps → Create App
- For Claude Desktop and Claude Code, refer to Integrate Claude with dbt MCP.
- When prompted in your MCP client, complete sign-in in the browser and approve the requested scopes on the consent screen.
- Return to your MCP client; subsequent requests use the OAuth session according to your client's behavior.
You can use execute_sql with OAuth. Add your MCP URL to your client and sign in when your MCP client prompts you. You don't need a personal access token or extra headers.
Register your MCP client
OAuth requires every client to be registered with dbt platform. There are two paths:
- Dynamic registration (default) — Clients that implement Dynamic Client Registration (RFC 7591) self-register the first time a user connects. No admin action required. Most modern MCP clients (such as Claude Desktop, Claude Code, Cursor, and VS Code) support this.
- Manual registration — For clients that don't support dynamic registration, an account admin registers the client in Account settings → Integrations → App integrations. Manually registered clients use PKCE (RFC 7636) instead of a client secret. Refer to Manual registration for the admin walkthrough.
Both types appear in App integrations in dbt platform, where admins can review and audit each connected client.
Scopes you'll consent to
The first time you connect, dbt shows a consent screen listing the scopes (the specific permissions the client is allowed to use) the MCP client is requesting. Scopes act as a filter on your existing permissions — they don't grant new access. You can also choose whether the client gets access to all projects or only selected projects.
For the full list of scopes and what each one allows, refer to Scopes and consent. For sessions, refresh tokens, revoking access, and audit logging, refer to Connect apps with OAuth.
Read-only users and warehouse credentials
Read-only users need warehouse credentials to run queries, such as query_metrics, through remote MCP. They have two options:
- Analytics credential (recommended): An admin sets up one shared analytics credential on the connection. Read-only users who haven't set up personal credentials use it automatically, so they never need to log in to dbt platform.
- Personal credentials: Users with the Analyst read permission set can add their own on Your profile → Credentials. If they have personal credentials, those take priority.
If a user has neither, the query fails and asks them to set up credentials or contact an admin.
Limitations
- Remote MCP doesn't support self-hosted dbt CLI commands (like
dbt run,dbt build,dbt test, and more) or local project access; use the self-hosted MCP server for those workflows.
For client-specific steps, refer to Integrate Claude with MCP, Integrate Cursor with MCP, Integrate Snowflake Cortex with MCP, or Integrate VS Code with MCP.
Token-based authentication
Token-based authentication lets you connect to the remote MCP server without OAuth by passing a PAT or service token in your MCP client config. Use it when your client doesn't support OAuth for HTTP-based MCP servers or when you need a shared or CI setup. To use execute_sql with token-based authentication, use a PAT.
Each tool call must satisfy the permissions for its target. Token-based connections can show tools that your token can't use; those calls fail individually. OAuth can also filter the tool list based on its granted permissions.
Setup instructions
AI features are enabled by default. Admins can turn them off or back on anytime. Turning them off doesn't disable remote MCP — it only hides the text_to_sql tool.
- Obtain the following information from dbt platform:
- dbt platform host: Use this to form the full URL. For example, replace
YOUR_DBT_HOST_URLhere: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 theACCOUNT_PREFIX.us1.dbt.comformat. For more information, refer to Access, Regions, & IP addresses. - Production environment ID: From Orchestration → Environments in dbt platform. Use this to set an
x-dbt-prod-environment-idheader. Refer to How to find your dbt MCP IDs for step-by-step instructions. - Token: Generate either a personal access token (PAT) or a service token with the permissions for the tools and resources you need. For a service token, assign the appropriate permission sets. PATs inherit the permissions of the user who created them.
- 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 requirex-dbt-user-id, a PAT is also required.
- 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 with the required permissions. When using the Semantic Layer, we recommend using a PAT. 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. Refer to How to find your dbt MCP IDs for step-by-step instructions. |
Additional configuration for SQL tools
| Header | Required | Description |
|---|---|---|
| x-dbt-dev-environment-id | Required for execute_sql | Your dbt platform development environment ID. Refer to How to find your dbt MCP IDs for step-by-step instructions. |
| x-dbt-user-id | Required for execute_sql | Your dbt platform user ID. Refer to Where can I find my user ID? for details. |
Use positive numeric IDs in project and environment headers. Development and production environment headers must identify environments of the corresponding type in the same project. If a tool accepts a project or environment argument, it must agree with the configured target. list_jobs preserves its existing behavior: an explicit project_id overrides the configured environment filter.
Additional configuration for dbt v2 tools
By default, dbt v2 tools use the environment you set in 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. Refer to How to find your dbt MCP IDs for step-by-step instructions. |
| x-dbt-user-id | Required | Your dbt platform user ID. Refer to Where can I find my user ID? for details. |
| x-dbt-fusion-disable-defer | Optional | Default: false. When set to true, dbt v2 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
| 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 |
- After establishing which headers you need, you can follow the examples to create your own agent.
Examples
The MCP protocol is programming language and framework agnostic, so use whatever helps you build agents. If you use OAuth (remote MCP) in Beta, you only need your MCP URL. If you use token-based authentication, add the headers in the examples below. Configuration varies by client — select your tool in the following tabs and replace the placeholder values with your own:
- OAuth
- Token-based
- Claude Code
- Cursor
{
"mcpServers": {
"dbt": {
"type": "http",
"url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/"
}
}
}
{
"mcpServers": {
"dbt": {
"url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/"
}
}
}
- Claude Code
- Cursor
- Gemini
{
"mcpServers": {
"dbt": {
"type": "http",
"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"
}
}
}
}
{
"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"
}
}
}
}
{
"mcpServers": {
"dbt": {
"httpUrl": "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"
}
}
}
}
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"
For other MCP clients (Codex, Windsurf, and so on), refer to your client's MCP configuration docs for the correct key format.
For self-hosted MCP, use environment variables to configure your setup; refer to the Environment variables reference.
Related docs
Step-by-step client setup (including Cursor, VS Code, and Claude) is in:
- Integrate Cursor with MCP
- Integrate VS Code with MCP
- Integrate Claude with MCP
- Integrate Snowflake Cortex with MCP
Was this page helpful?
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.
