Skip to main content

Connect to the remote dbt MCP server StarterEnterpriseEnterprise +

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.

Remote dbt MCP server architectureRemote dbt MCP server architecture

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, Administrative, and Discovery APIs 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 local dbt Core or Fusion 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. Refer to 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. Refer to Finding your IDs.

3. Choose authentication: OAuth or tokens​

  • OAuth (remote) — No API tokens in your client config. Requires an OAuth-capable MCP client. Available in private beta for Enterprise and Enterprise+ accounts.
  • Token-based — PAT or service token in the Authorization header. Works with any client and is required for shared/CI setups and for execute_sql (which needs a PAT).
info

Remote MCP OAuth is available for Enterprise and Enterprise+ accounts. Contact your account manager to join the private beta.

4. Get your MCP URL and IDs​

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.

 Build your own MCP URL

We recommend using the MCP URL from Account settings → Access URLs → MCP Endpoint URL in dbt platform. However, if you want to build your own MCP URL, use your Access URL from Account settings in dbt platform. The remote MCP endpoint is https://YOUR_DBT_HOST_URL/api/ai/v1/mcp. Replace YOUR_DBT_HOST_URL with your hostname only (no https://).

For default hosts, multi-cell accounts, and regions, see Access, Regions, & IP addresses.

Depending on your auth method, you may also need:

  • Production environment ID: From Orchestration in dbt platform. Used as the x-dbt-prod-environment-id header for token-based setup.
  • Token — PAT or service token with Semantic Layer and Developer permissions (token-based setup only).
  • If you use execute_sql: You must use a PAT, plus your development environment ID and user ID. Refer to 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.

5. Configure your MCP client​

Configure your MCP client with the MCP URL and headers from the previous step.

Before you connect

  • Your MCP client must support OAuth for HTTP-based MCP servers. If it doesn't, use token-based authentication instead.
  • On first connect, your client opens a browser for sign-in. dbt then shows a consent screen with the scopes (the specific permissions the client is allowed to use) it's requesting — see Scopes and consent for what each scope means.
  • Most modern MCP clients self-register on first connect via dynamic registration (RFC 7591). Clients that don't support it need an admin to register them in Account settings → Integrations → App integrations. See Manual registration.

For the full flow, sessions, and limitations, refer to OAuth (remote MCP).

Configure your client with the MCP URL from the previous step. On first connect, your client opens a browser for sign-in and consent.

Add this to .mcp.json at your project root:

{
  "mcpServers": {
    "dbt": {
      "type": "http",
      "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/"
    }
  }
}
  • For the complete list of headers, Cursor and other client examples, and optional headers, refer to Set up remote MCP.
  • For local MCP, configuration uses environment variables; check out the Environment variables reference for more information.

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