dbt Integration

SignalPilot integrates with dbt to bring your transformation layer context into data investigations. Access model lineage, documentation, test results, and column-level metadata without leaving your notebook.

What dbt Integration Provides

Context Type	What You Get	Example Use
Model Lineage	Upstream/downstream dependencies	”What feeds into this metric?”
Documentation	Model and column descriptions	”What does this column mean?”
Test Results	Data quality test status	”Are there any failing tests?”
Column Lineage	Field-level transformations	”Where does this field come from?”
Freshness	Source freshness status	”When was this data last updated?”

Supported dbt Versions

dbt Type	Version	Features
dbt Cloud	All tiers	Full API access, real-time sync
dbt Core	1.0+	Manifest/catalog file parsing

Setup: dbt Cloud

Get Your dbt Cloud API Token

Log in to dbt Cloud
Go to Account Settings → API Access
Generate a new Service Token with these permissions:
- Metadata API (required)
- Job triggers (optional, for freshness checks)
Copy the token

Use a service token, not a personal token. Service tokens don’t expire and aren’t tied to individual users.

Find Your Account and Project IDs

From your dbt Cloud URL: https://cloud.getdbt.com/deploy/{account_id}/projects/{project_id}

Configure SignalPilot

Add to your signalpilot.config.json:

{
  "mcp_servers": {
    "dbt": {
      "type": "dbt-cloud",
      "api_token": "${DBT_CLOUD_API_TOKEN}",
      "account_id": "12345",
      "project_id": "67890"
    }
  }
}

Use environment variables for sensitive values. SignalPilot will read ${VAR_NAME} from your environment.

Verify Connection

In a SignalPilot notebook, test with: @dbt show modelsYou should see a list of your dbt models.

Setup: dbt Core

For dbt Core, SignalPilot reads your manifest and catalog files directly.

Generate Manifest and Catalog

Run dbt to generate the required artifacts:

dbt docs generate

Configure SignalPilot

Add to your signalpilot.config.json:

{
  "mcp_servers": {
    "dbt": {
      "type": "dbt-core",
      "project_dir": "/path/to/your/dbt/project",
      "target_dir": "target"
    }
  }
}

Using dbt Context

Model Lineage

Ask about dependencies to understand data flow:

You: "What models feed into the revenue dashboard?"

SignalPilot: Looking at dbt lineage for revenue_dashboard...

Upstream models:
├── stg_orders (staging)
├── stg_customers (staging)
├── int_order_items (intermediate)
└── fct_revenue (fact)

Test Results

Check data quality before investigating:

You: "Are there any failing dbt tests?"

SignalPilot: Checking dbt test results...

⚠️ 2 tests failing:
1. unique_orders_order_id (FAIL) - Found 47 duplicate order_ids
2. not_null_customers_email (WARN) - Found 12 null emails

Column Lineage

Trace where data comes from:

You: "Where does the mrr column in fct_subscriptions come from?"

SignalPilot: Tracing column lineage...

fct_subscriptions.mrr
└── int_subscription_mrr.mrr_amount
    └── CASE statement combining:
        ├── stg_subscriptions.plan_amount
        ├── stg_discounts.discount_percent
        └── stg_credits.credit_amount

dbt Commands

Command	Description
`@dbt show models`	List all models
`@dbt lineage <model>`	Show upstream/downstream
`@dbt describe <model>`	Show model documentation
`@dbt tests`	Show test results
`@dbt freshness`	Check source freshness

Best Practices

Document Your Models

Well-documented dbt models make SignalPilot investigations faster. Include column descriptions, especially for business logic.

Run Tests Before Investigating

Check @dbt tests before deep investigations. Failing tests might explain data anomalies.

Use Lineage for Root Cause

When data looks wrong, trace lineage upstream. The issue often originates in staging or source models.

Context Aggregation

How dbt fits into the MCP architecture

Slack Integration

Combine dbt context with Slack discussions

Introduction

Getting Started

Integrations

Core Concepts

dbt Integration

dbt Integration

What dbt Integration Provides

Supported dbt Versions

Setup: dbt Cloud

Setup: dbt Core

Using dbt Context

Model Lineage

Test Results

Column Lineage

dbt Commands

Best Practices

Context Aggregation

Slack Integration

​dbt Integration

​What dbt Integration Provides

​Supported dbt Versions

​Setup: dbt Cloud

​Setup: dbt Core

​Using dbt Context

​Model Lineage

​Test Results

​Column Lineage

​dbt Commands

​Best Practices

​Related Resources

Context Aggregation

Slack Integration

dbt Integration

What dbt Integration Provides

Supported dbt Versions

Setup: dbt Cloud

Setup: dbt Core

Using dbt Context

Model Lineage

Test Results

Column Lineage

dbt Commands

Best Practices

Related Resources