Skip to main content

Use dbt MCP with zero local install

The remote MCP server connects to dbt platform using HTTP. No local installation is required — you configure your MCP client with a URL and headers instead of running uvx dbt-mcp.

When to use remote MCP​

Remote MCP is a good fit when:

  • You don't want to or can't install software (uvx, dbt-mcp) on your machine.
  • Your use case is consumption-based: querying metrics, exploring metadata, viewing lineage, or running SQL via the platform.
  • You need Semantic Layer and Discovery API access without a local dbt project.
Local development requires local MCP

Local development and agentic workflows (for example, running dbt commands like dbt run or dbt build from your AI assistant) require the local MCP server. Remote MCP does not support the dbt CLI or local project access. Use Connect to dbt platform or Run dbt locally for those workflows.

Set up remote MCP​

Follow these steps to set up the remote MCP server:

1. Enable AI features​

In dbt platform, ensure that you have AI features turned on.

2. Get your credentials​

Obtain the following information from dbt platform:

  • dbt platform host: Form the URL as https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/ (for example, https://cloud.getdbt.com/api/ai/v1/mcp/). For multi-cell accounts, the host is in the format ACCOUNT_PREFIX.us1.dbt.com. See Access, Regions, & IP addresses.

  • Production environment ID: From Orchestration in dbt platform. You will use it as the x-dbt-prod-environment-id header.

  • Token — PAT or service token with Semantic Layer and Developer permissions.

  • If you use execute_sql: You must use a PAT, plus your development environment ID and user ID. See Finding your IDs.

    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.

3. Configure your MCP client​

In your MCP client config, set the server url to https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/ and add headers:

  • Required: Authorization (value Token YOUR_TOKEN or Bearer YOUR_TOKEN), x-dbt-prod-environment-id
  • For execute_sql or Fusion tools: Also add x-dbt-dev-environment-id and x-dbt-user-id
  • Use numeric IDs in headers, not full URLs copied from your browser.

For the complete list of headers, Cursor and other client examples, and optional headers, see Set up remote MCP. For local MCP, configuration uses environment variables; see the Environment variables reference.

Once you have configured your MCP client, you can test your setup by asking your AI assistant a data-related question (for example, "What models are in my dbt project?" or "What metrics are defined in my Semantic Layer?"). If dbt MCP is working, the response will use your dbt metadata.

Was this page helpful?

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

0
Loading