Blog

5 Steps to Deploy an Analytics Agent on dbt MCP to Your Whole Company

nao · March 3, 2026 · 6 min read

Originally published on the nao blog

Introduction

Last year at dbt Coalesce, the dbt MCP dominated discussions, yet few could explain proper installation, post-demo implementation, or company-wide deployment. This guide addresses that gap.

While the dbt MCP excels for local testing with tools like Cursor or Claude, this approach doesn’t scale across organizations. A better strategy involves establishing a single repository with your dbt MCP configuration, integrating it with an open source analytics agent, and deploying a browser-based chat interface for organization-wide data access.

This guide demonstrates this approach using nao, an open source analytics agent designed for agentic analytics and context engineering. The five-step process includes:

  1. Choose the right dbt MCP
  2. Initialize your nao project
  3. Configure the dbt MCP
  4. Test your analytics agent
  5. Deploy to the whole company

Step 1. Choose the right dbt MCP

Your first decision involves selecting which dbt MCP server and tool surface your agent will access.

Three Practical Setups

Are you on dbt Core?

Use the local MCP, which runs on your machine or container, pointing to your local dbt project. This offers maximum flexibility for agent inspection of models and query execution against your dbt project.

Benefits include:

  • Local execution against your dbt project
  • Access to CLI-style dbt tools
  • dbt show for query execution
  • No dbt Cloud license requirement

This setup suits flexible analytics agents working across dbt projects and the broader data stack.

Are you on dbt Cloud without a semantic layer?

Use the local MCP again, but configure it with your dbt Cloud API token instead of a local project path. The local dbt MCP server handles authentication and project settings from dbt Cloud.

Are you on dbt Cloud and only want to query the semantic layer?

Use the remote MCP, where dbt hosts the server. Point your client to a URL, pass auth headers, and access the Semantic Layer and Discovery APIs.

This model provides more governance but with constraints:

  • No CLI commands
  • No direct SQL execution
  • Difficulty extending beyond the semantic layer

Important note: Using the semantic layer MCP requires at least a Starter license; a Developer license is insufficient. The free path leads through dbt Core.

Step 2. Initialize your nao project

nao deploys an analytics agent using file-system context plus any chosen MCP. The approach is straightforward:

  • Commit a repository with your agent configuration
  • Connect your dbt MCP
  • Deploy a browser UI enabling organization-wide data conversations

Install nao-core:

pip install nao-core

Initialize a new project:

nao init

For minimal setup, provide a project name and add your dbt git repository as context. Separate database context isn’t necessary if your agent accesses data through the dbt MCP.

This creates the file-system structure your agent requires.

To sync the dbt repository into the nao project, run:

nao sync

Execute this from inside the new nao project folder.

If testing locally while already inside your dbt repository, skip the sync step initially.

This architectural approach distinguishes nao: your analytics agent receives not just tools, but a versioned context layer derived from your repository. This foundation makes agentic analytics viable beyond demonstrations and underscores the importance of adopting an open framework for context engineering.

Step 3. Configure the dbt MCP

Add an mcp.json file under your agent/mcp folder. Configuration depends on whether you use dbt Core or dbt Cloud. Both examples below employ the dbt local server.

dbt Core Configuration

{
  "mcpServers": {
    "dbt-mcp": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/path/to/your/dbt-project",
        "DBT_PROFILES_DIR": "/path/to/your/dbt-project",
        "DBT_PATH": "/path/to/venv/bin/dbt",
        "DBT_TARGET": "target_name",
        "DISABLE_SEMANTIC_LAYER": "true",
        "DISABLE_DISCOVERY": "true",
        "DISABLE_SQL": "true",
        "DISABLE_ADMIN_API": "true"
      }
    }
  }
}

dbt Cloud with Semantic Layer Configuration

{
  "mcpServers": {
    "dbt-mcp": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "us1.dbt.com",
        "MULTICELL_ACCOUNT_PREFIX": "your_prefix",
        "DBT_TOKEN": "${DBT_TOKEN}",
        "DBT_PROD_ENV_ID": "your_env_id",
        "DISABLE_SEMANTIC_LAYER": "false",
        "DISABLE_DISCOVERY": "true",
        "DISABLE_SQL": "true",
        "DISABLE_ADMIN_API": "true",
        "DISABLE_REMOTE": "false"
      }
    }
  }
}

The Tradeoff

  • dbt Core provides flexibility, allowing agents to inspect models and employ dbt show for SQL execution
  • dbt Cloud Semantic Layer enables stronger governance through metrics and dimensions instead of raw SQL

For a comprehensive chat-with-data assistant across your technical data stack, Core typically represents the easier starting point. For tighter control, the semantic layer proves more secure.

Step 4. Test your Analytics Agent

Once MCP configuration is complete, launch the chat UI from your nao project:

nao chat

Open the admin panel and navigate to Project > MCP Server.

This location confirms dbt MCP connection and displays active tools. You can toggle tools on and off here.

Expected Results

  • dbt Core: 11 tools active
  • dbt Cloud Semantic Layer: 6 tools active

Begin your first conversation in the UI.

If Using dbt Core

The agent employs dbt_show to query your models directly, enabling:

  • SQL generation
  • dbt project inspection
  • Broader project-wide operation

This approach is powerful but less governed.

If Using dbt Cloud Semantic Layer

The agent retrieves dimensions and metrics through the semantic layer, providing:

  • No direct SQL
  • No raw model access
  • Answers constrained to team-defined metrics

This approach is more reliable but limited.

This distinction significantly impacts agentic analytics: Core supports exploratory analytics agents, while the Semantic Layer functions as a governed business-facing interface. To formally validate this tradeoff, evaluate the analytics agent using nao test with real questions.

Step 5. Deploy to the Whole Company

Once local setup functions properly, deploy and self-host the nao agent organization-wide.

The pattern is straightforward:

  • One repository
  • One YAML or config-driven setup
  • One deployed UI
  • Organization-wide data conversation capabilities

For dbt Core MCP

Update the mcp.json paths to reference Docker locations:

{
  "mcpServers": {
    "dbt-mcp": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/app/project/repos/dbt",
        "DBT_PROFILES_DIR": "/run/secrets/dbt",
        "DBT_PATH": "/usr/local/bin/dbt",
        "DBT_TARGET": "target_name",
        "DISABLE_SEMANTIC_LAYER": "true",
        "DISABLE_DISCOVERY": "true",
        "DISABLE_SQL": "true",
        "DISABLE_ADMIN_API": "true"
      }
    }
  }
}

Install dbt within the container:

FROM getnao/nao:latest
ARG DBT_ADAPTER=dbt-bigquery

RUN python -m pip install --no-cache-dir --upgrade pip \
  && python -m pip install --no-cache-dir dbt-core ${DBT_ADAPTER} \
  && dbt --version

COPY . /app/project/
WORKDIR /app/project

Mount profiles.yml as a secret in your container configuration.

For dbt Cloud MCP

Pass MCP variables as environment variables in the container; no additional setup is required.

This deployment phase transforms the local dbt MCP experiment into a genuine organization-facing analytics agent.

What to Do After the MCP Works

Connecting the dbt MCP marks the beginning, not the conclusion.

Out-of-the-box, the dbt MCP equips your agent with tools but lacks sufficient knowledge for consistent reliability.

This is where context engineering becomes essential.

High-leverage subsequent investments typically include:

  • Adding supplementary context sources such as internal documentation, Notion pages, and metric definitions
  • Running nao test with 10-15 authentic questions to measure early reliability
  • Enhancing your dbt model documentation, column descriptions, and metric definitions

Many teams overlook this phase, emphasizing MCP connection while neglecting the context layer. However, developing a reliable open source analytics agent on dbt requires context as much as tooling. This principle aligns with benchmarking findings demonstrating context’s substantial impact on analytics agent performance.

The dbt MCP establishes connectivity. Context engineering delivers trustworthy answers.

This article was first published on the nao blog. Read it at the source for the latest version.