🧭 dbt MCPでBI数字不整合を追う意味層・検証層アーキテクチャ

起点: dbt Labs ブログ「How MCP connects your AI agent to dbt and Databricks」(Databricks Data + AI Summit 2026 発表、Integral Ad Science 事例)。
dbt MCP サーバがエージェントに dbt の意味層・リネージ・compiled SQL を渡し、Databricks を統制されたクエリ実行基盤、Looker などの BI をエントリポイントとして、三層で BI 数字不整合を解析する運用パターンを扱います。
検証日: 2026-07-09 / dbt-mcp PyPI 最新版: 1.21.2（本文中のバージョン確認時点）

対象読者

この記事は、dbt と Databricks を使い、BI ダッシュボードの数字不整合を AI エージェントに調査させたいデータエンジニア・Analytics Engineer 向けです。

読み終えると、次の判断材料を得られます。

• dbt MCP が AI エージェントへ渡す意味層・リネージ・compiled SQL の範囲
• Databricks SQL / Unity Catalog を検証層に置く理由
• 生データ直叩き型 text-to-SQL と比べたときの権限・監査・保守性の違い
• ローカル / リモート MCP サーバの最小設定と運用上の注意点

概要

dbt MCP サーバとは

dbt MCP サーバは、AI アプリケーションと dbt が管理するデータ資産をつなぐ標準化されたフレームワークです。

• モデル定義・メトリクス・リネージ・データ鮮度への一貫したアクセスを、クライアントを問わず提供します。
• MCP (Model Context Protocol) は、エージェントがツールの内部 API を知らなくてもツールと対話できる共通プロトコルです。
• エージェント側のコードは、接続先ツール (dbt / Databricks / Looker) が入れ替わっても変更不要です。

なぜ「AI にデータの意味を渡す」ために MCP を使うか

BI ダッシュボードの数字が食い違ったとき、原因究明には「どのモデルがどう定義され、どこから来た値か」という意味情報が要ります。この意味情報は、dbt のモデル定義・テスト・リネージグラフにすでに存在します。

課題は、この情報を AI エージェントへ安全かつ動的に渡す手段でした。MCP は、意味情報を API クライアントの自作なしにエージェントへ渡す標準経路になります。dbt Labs のブログ (Databricks Data + AI Summit 2026 発表) は、Integral Ad Science (IAS) の事例で次のように説明しています。

• 課題: あるモデルが人気飲料を food カテゴリに誤分類していました。IAS のエージェントは BI ダッシュボードの数字から source table まで遡り、原因を特定しました。
• 主張: 「upstream の列を変えると、エージェントは downstream で何が壊れるかを教えられます。各 downstream モデルのロジックを読むため、構造的な影響だけでなく意味的な影響も推論できます」。
• 主張: 「エージェントはグラフを一から再構築しません。ドキュメントが実態に追いつくことも期待しません。dbt のテスト済み・バージョン管理されたグラフと、compiled SQL そのものを読みます」。

MCP サーバはツール露出を絞り込むことで、権限範囲の限定・監査・生 API 資格情報の非開示を実現します。

三層構成: 意味層・検証層・エントリポイント

IAS の実装は、役割の異なる MCP サーバを組み合わせます。

dbt が意味とリネージを提供し、Databricks が検証済みの実行基盤を提供します。エージェントは両方を往復し、ダッシュボードのタイル 1 つから source table まで数字を追跡し、その過程で見つけた値を信頼できます。

新しい接続先を追加する場合も、カスタム API クライアントを書く代わりに新しい MCP サーバを指すだけで済みます。dbt Labs のブログは、これによって接続追加が「days not weeks」、問題解決が「hours to minutes」に短縮されたと述べています。

特徴

• テスト済み・バージョン管理された lineage グラフを読む: エージェントはドキュメントの陳腐化を前提とせず、dbt が保守する実際のデータフローグラフを参照します。
• compiled SQL を直接読む: リネージが「どこを見るか」を示し、compiled SQL が「そこで何が起きているか」を示します。両方が揃って初めて、構造的な影響と意味的な影響の両方を推論できます。
• read-only 検証と生データ丸投げの違い: 検証層はガバナンスされた read-only 実行に閉じます。エージェントに生の DB 資格情報や無制限のクエリ権限を渡しません。
• truth layer を権限分離して引かせる: dbt MCP サーバは公開ツール数を絞り込み、ツール露出そのものを権限境界として扱います。エージェントの行動範囲を、意味層を経由する読み取りに限定します。
• Unity Catalog 権限をそのまま継承する: Databricks 管理の MCP サーバは Unity Catalog の権限設定を尊重します。エージェントは利用者本人がアクセスできるテーブルのみ参照でき、マスク済み列はマスクされたままです。
• 接続追加がプラガブル: 新しいデータソースや BI ツールを増やすとき、カスタムクライアントの実装ではなく MCP サーバの追加で対応できます。エージェント側のコードは変更不要です。
• 共有コンテキスト基盤による context drift の抑制: すべてのエージェントが同じ意味層に MCP 経由で問い合わせるため、エージェントごとに定義がずれる「コンテキストのずれ」を、事後検知ではなく構造として防げます。

情報源の渡し方の比較

BI 数字の不整合を調べる AI エージェントに、どう情報源を渡すかで 3 つのアプローチがあります。

筆者の見立てでは、BI 障害解析では「RAG で説明文を渡す」よりも「dbt のテスト済みグラフと compiled SQL を読ませる」方が再現性を出しやすいです。説明文は補助情報に留め、原因特定の正本を dbt の成果物へ寄せる構成を推奨します。

構造

dbt MCP を介した意味層と検証層をつなぐ BI 障害解析アーキテクチャを、C4 model の 3 段階で図解します。

システムコンテキスト図

調査対象システムを中心に、周囲のアクターと外部システムとの関係を示します。アクターは役割名で表現しています。

要素一覧

コンテナ図

調査対象システムをドリルダウンし、AI エージェントと dbt MCP サーバが、どの外部システムのどのコンテナと接続するかを示します。

調査対象システム エージェント側

dbt Platform

Databricks

BIツール

コンポーネント図

dbt MCP サーバ内部を構成するツール群コンポーネントの関係を示します。Transport 層がどの通信方式で呼び出しを受けるか、Config がどのツール群の有効・無効を切り替えるかを併せて表現します。

dbt MCPサーバ

Semantic Layer tools・Discovery tools・SQL tools の 3 コンポーネントは、調査の各ステップで直接使い分けるため、内部のツール構成をさらにドリルダウンします。

Semantic Layer tools のツール一覧

要素一覧

Discovery tools のツール一覧 (BI 障害解析で使う主要ツールの抜粋)

Discovery 系統は現行実装で 19 前後のツールを持ちます。ここでは BI 障害解析ワークフローで直接使う主要ツールを抜粋します。

要素一覧

上記以外にも get_all_sources / get_source_details / get_exposure_details / get_related_models / get_mart_models / search などがあります。網羅一覧は 公式 Available tools を参照してください。

補足: これらは MCP ツール呼び出し名です。Python クライアント (ModelsFetcher) のメソッド名とは一致しません (例: MCP ツール get_all_models は ModelsFetcher.fetch_models、get_model_parents は fetch_model_parents に対応)。呼び出し文脈が MCP ツールか Python クラスかで名称を使い分けます。

SQL tools のツール一覧

要素一覧

データ

概念モデル

dbt MCP が扱うエンティティは 4 つの層に分かれます。MCP Server は複数の MCP Tool を所有します。dbt Semantic Layer は Metric・Dimension・Entity・SavedQuery を所有します。dbt Project Graph は Model・Lineage を所有します。Databricks は Warehouse・Table を所有します。SemanticLayerConfig・CompiledSQL・QueryResult は特定の層に属さない横断エンティティです。

MCP Server

dbt Semantic Layer

dbt Project Graph

Databricks

横断エンティティ

情報モデル

構築方法

dbt MCP サーバ (dbt-mcp, PyPI: https://pypi.org/project/dbt-mcp/) は、意味層 (dbt Semantic Layer) と検証層 (Databricks SQL) を 1 つの MCP サーバ経由で AI エージェントに公開します。実行方式は 2 通りです。

• ローカル MCP サーバ: 手元のマシンで uvx dbt-mcp を起動し、stdio で MCP クライアントと接続します。dbt Core / dbt Fusion / dbt CLI ツールを使う場合はこちらが必須です。
• リモート MCP サーバ: dbt Platform がホストする HTTP エンドポイントに接続します。ローカルインストールが不要で、streamable HTTP transport を使います。

最小構成で試す quick start

まずローカルの stdio 方式で、Semantic Layer と Discovery だけを開ける構成から始めると安全です。SQL 実行は後から明示的に有効化します。

uvx dbt-mcp

MCP クライアントには、次の最小設定を渡します。トークンは実運用では .env やシークレットストアに分離します。

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "abc123.us1.dbt.com",
        "DBT_TOKEN": "dbtc_your_token",
        "DBT_PROD_ENV_ID": "12345",
        "DISABLE_SQL": "true",
        "DISABLE_ADMIN_API": "true",
        "DISABLE_DBT_CLI": "true"
      }
    }
  }
}

この状態で list_metrics、get_all_models、get_model_parents が使えることを確認します。BI 障害解析で実データ検証が必要になった段階で、開発環境 ID と個人 PAT を分けて execute_sql を有効化します。

前提条件

インストール

uvx はローカルにパッケージをインストールせずその場で実行するため、リポジトリの clone は不要です。

# 最新版をその場で起動 (推奨)
uvx dbt-mcp

# バージョンを固定して起動
uvx dbt-mcp==1.21.2

pip でインストールする場合です。

pip install dbt-mcp

コントリビュート目的でソースから動かす場合です。

git clone https://github.com/dbt-labs/dbt-mcp.git
cd dbt-mcp
uv sync
uv run dbt-mcp

MCP クライアント設定

stdio (ローカル MCP サーバ)

Claude Desktop や Cursor (~/.cursor/mcp_config.json)、VS Code (mcp.json) はいずれも同じ形式です。

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "abc123.us1.dbt.com",
        "DBT_TOKEN": "dbtc_your_token",
        "DBT_PROD_ENV_ID": "12345",
        "DBT_DEV_ENV_ID": "23456",
        "DBT_USER_ID": "34567",
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/opt/homebrew/bin/dbt"
      }
    }
  }
}

トークンなど秘匿情報を JSON に直書きしたくない場合は .env ファイルを分離し --env-file で渡します。

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["--env-file", "/absolute/path/to/your-dbt-project/.env", "dbt-mcp"]
    }
  }
}

uvx がパス解決できない場合 (Error: spawn uvx ENOENT) は、command に uvx のフルパスを指定します。

streamable HTTP (リモート MCP サーバ)

dbt Platform がホストする MCP エンドポイントに直接接続します。ローカルインストールが不要な分、DBT_DEV_ENV_ID / DBT_USER_ID は環境変数ではなく HTTP ヘッダーで渡します。

{
  "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"
      }
    }
  }
}

x-dbt-prod-environment-id などのヘッダー値は環境の URL 全体ではなく、数値 ID のみを渡します。

✅ 正しい: "x-dbt-prod-environment-id": "54321"
❌ 誤り  : "x-dbt-prod-environment-id": "https://cloud.getdbt.com/deploy/12345/projects/67890/environments/54321"

OpenAI Agents SDK から streamable HTTP に接続する場合の Python 例です (examples/openai_agent/main_streamable.py 抜粋)。

from agents.mcp.server import MCPServerStreamableHttp

async with MCPServerStreamableHttp(
    name="dbt",
    params={
        "url": f"https://{host}/api/ai/v1/mcp/",
        "headers": {
            "Authorization": f"token {token}",
            "x-dbt-prod-environment-id": prod_environment_id,
        },
    },
) as server:
    ...

ローカル MCP サーバ自体を HTTP で待ち受けさせたい場合 (デバッグ用途) は、環境変数 MCP_TRANSPORT=streamable-http を指定します (既定値は stdio)。

環境変数設定

主要な環境変数は次のとおりです。

環境変数は次の 3 通りで渡せます。用途に応じて選びます。

# 方式 1: .env ファイル + --env-file (推奨、秘匿情報を JSON から分離できる)
uvx --env-file /absolute/path/to/.env dbt-mcp

# 方式 2: シェル環境変数
export DBT_HOST=cloud.getdbt.com
export DBT_TOKEN=your-token-here
uvx dbt-mcp

# 方式 3: MCP クライアント設定 JSON の env フィールド (上記「MCP クライアント設定」を参照)

DBT_HOST / DBT_PROD_ENV_ID などは値のみを渡します。URL 全体を渡すと接続エラーになります。

✅ 正しい: DBT_HOST=cloud.getdbt.com
❌ 誤り  : DBT_PROD_ENV_ID=https://cloud.getdbt.com/deploy/12345/...

tool group の有効/無効

ツール群 (toolset) は semantic_layer / discovery / sql / admin_api / dbt_cli / dbt_codegen の主要 6 系統に加え、dbt_lsp (Fusion) / product_docs / mcp_server_metadata を含む単位で有効・無効を切り替えます。設計方針は denylist (原則: 既定で全許可) と allowlist (既定で全拒否) の 2 モードです。

重要な例外: SQL 系統 (execute_sql / text_to_sql) だけは DISABLE_SQL の既定が true で、denylist モードでも初期状態では無効です。本ドキュメントの検証ステップ (execute_sql) を使うには、DISABLE_SQL=false (denylist) または DBT_MCP_ENABLE_SQL=true (allowlist) を明示的に設定します。dbt_codegen / mcp_server_metadata も同様に既定で無効です。

BI 障害解析用途では、書き込み系ツールを持ち込ませないために dbt_cli / dbt_codegen / admin_api を明示的に無効化する運用が安全です。

denylist モード (デフォルト。個別ツールを無効化) です。

DISABLE_DBT_CLI=true          # dbt CLI (build/run など書き込み系) を無効化
DISABLE_DBT_CODEGEN=true      # 既定で無効
DISABLE_SEMANTIC_LAYER=false  # 意味層ツールは有効のまま
DISABLE_DISCOVERY=false       # discovery (lineage) ツールは有効のまま
DISABLE_SQL=false             # SQL は既定で無効。execute_sql を使うので明示的に有効化する
DISABLE_ADMIN_API=true        # job 起動などの Admin API を無効化
DISABLE_TOOLS="build,run,test"    # 個別ツール名を comma-separated で無効化

allowlist モード (必要なツールだけを明示的に許可) です。BI 障害解析ワークフローに限定するなら、次の toolset だけを有効化すれば十分です。

DBT_MCP_ENABLE_SEMANTIC_LAYER=true
DBT_MCP_ENABLE_DISCOVERY=true
DBT_MCP_ENABLE_SQL=true   # execute_sql を使うため SQL 系統を有効化 (既定は無効)
DBT_MCP_ENABLE_TOOLS="list_metrics,get_dimensions,query_metrics,get_metrics_compiled_sql,get_lineage,get_model_parents,execute_sql"

リモート MCP サーバ (HTTP) では、同じ制御を環境変数の代わりに HTTP ヘッダーで行います。

x-dbt-disable-tools: get_all_models,text_to_sql,get_entities
x-dbt-disable-toolsets: dbt_cli,admin_api

バージョン確認

# PyPI 公開バージョンを確認
pip index versions dbt-mcp

# uv でインストール済みバージョンを確認
uv tool list

# インストール済みパッケージのメタ情報
pip show dbt-mcp

2026-07-09 時点の PyPI 最新版は 1.21.2 です (requires-python: >=3.12,<3.14)。

利用方法

主要ツールと必須パラメータ

query_metrics はウェアハウスに問い合わせを発行しますが、ツール定義上は read_only_hint=True / destructive_hint=False です。データを書き換えないという意味での read-only であり、get_metrics_compiled_sql (SQL 文字列のみ返す・実行なし) とは区別します。

semantic layer: 自然言語から意味層クエリへ

意味層ツールは「メトリクス名を調べる → 使える軸 (dimension) を調べる → 実際にクエリする」の順で使うと迷いません。

1. list_metrics(search="revenue")
   → 定義済みの "revenue" 系メトリクス一覧 (名前・型・説明) を取得

2. get_dimensions(metrics=["revenue"])
   → "revenue" で group_by 可能なディメンション一覧を取得

3. query_metrics(
     metrics=["revenue"],
     group_by=[{"name": "metric_time", "grain": "day"}],
     limit=1000
   )
   → 実際に集計値を取得 (意味層が生成した SQL がウェアハウス上で実行される)

4. get_metrics_compiled_sql(
     metrics=["revenue"],
     group_by=[{"name": "metric_time", "grain": "day"}]
   )
   → 3 のクエリを実行せず、生成された compiled SQL 文字列だけを確認

query_metrics と get_metrics_compiled_sql は同じ引数 (metrics / group_by / order_by / where / limit) を受け取ります。障害解析では、まず get_metrics_compiled_sql で SQL を確認してから query_metrics で実データを取得する順序が安全です。

discovery: lineage 遡上でモデルの系譜を追う

Discovery ツールは dbt プロジェクトのグラフ (依存関係) を、実際にビルドされた成果物 (manifest) から返します。ドキュメントの追いつき待ちが不要です。

1. get_all_models(search="orders")
   → モデル名・説明の一覧から対象モデルを特定

2. get_model_parents(model_name="fct_orders")
   → fct_orders の直接の上流依存 (親モデル) を取得

3. get_lineage(model_name="fct_orders", types=["ancestors"], depth=5)
   → 5 階層分の上流をまとめて遡上 (親の親まで一括取得)

4. get_model_details(model_name="stg_products")
   → 疑わしいモデルの compiled SQL・列定義・マテリアライズ種別を確認

get_model_children は逆方向 (下流の影響範囲) の調査に使います。「このソース列を変えたら、どの mart / dashboard が壊れるか」を確認する際に有効です。

SQL: Databricks 上で read-only 検証する

execute_sql は dbt Platform 経由で Databricks SQL ウェアハウスにクエリを発行します。意味層のクエリ結果と、Databricks 上の生データを突き合わせて検証する用途に使います。

SELECT category, COUNT(*) AS row_count
FROM raw.products
WHERE category = 'food'
GROUP BY category

execute_sql は DDL/DML の発行も技術的には可能なため、障害解析用途では次のいずれかで書き込みを防ぎます。

• Databricks 側で読み取り専用ロールのトークンを使う
• DBT_DEV_ENV_ID に検証専用の開発環境 (本番と分離) を割り当てる
• text_to_sql で SELECT 文だけを生成させ、execute_sql に渡す前に人間 (またはエージェントの別ステップ) がレビューする

text_to_sql は SQL を生成するだけで実行しません。自然言語の質問から dbt プロジェクトの文脈 (モデル名・列名) を踏まえた SQL 文字列を作りたいときに使います。

BI 障害解析の具体的ワークフロー

起点ブログが挙げる事例 (ある BI ダッシュボードで、飲料が food カテゴリに誤分類されて集計が狂う) を題材に、dbt MCP でどう遡るかを示します。

各ステップの具体化です。

1. 異常の把握: 「食品カテゴリの売上が急増している」など、BI 上の異常な数字を起点にします。
2. 意味層の定義確認: list_metrics(search="revenue_by_category") で、対象メトリクスがどの意味モデル・どの列を参照しているかを確認します。
3. compiled SQL の確認: get_metrics_compiled_sql(metrics=["revenue_by_category"], group_by=[{"name": "product_category"}]) で、意味層が実際に発行している SQL (どのテーブル・どの JOIN・どの CASE 文でカテゴリ分類しているか) を確認します。
4. lineage 遡上: compiled SQL に登場するモデル (例 dim_products) に対して get_model_parents(model_name="dim_products") を呼び、カテゴリ分類ロジックを持つ上流モデル (例 stg_products の CASE WHEN 分類) まで遡ります。get_model_details で該当モデルの compiled SQL を読み、「飲料が food に分類されるルール」がどこに書かれているかを特定します。
5. 実データの read-only 検証: execute_sql で Databricks 上の元テーブル (raw.products 等) に対して検証クエリ (例 SELECT category, product_name FROM raw.products WHERE category = 'food' AND product_name ILIKE '%juice%') を実行し、ソースデータの時点で誤分類が起きているのか、dbt モデルの変換ロジックで起きているのかを切り分けます。
6. 原因未特定なら 4 に戻る: 上流にさらにモデルがあれば get_model_parents を繰り返し、ソーステーブルまで遡上します。
7. root cause の報告: 「stg_products の CASE WHEN category_raw = 'beverage' THEN 'food' という分類ロジックが誤り」のように、モデル名・行レベルまで特定した状態で報告します。実際の修正 (dbt モデルの書き換え) は別プロセスに委ねます。

この一連の流れにより、エージェントはドキュメントの追随を待たずに、テスト済み・バージョン管理された dbt のグラフと compiled SQL そのものを読んで意味的な影響まで推論できます。

Python client のコード例

MCP サーバを介さず、Python から直接 Semantic Layer / Discovery の fetcher クラスを呼ぶこともできます。MCP ツール名 (query_metrics 等) と Python クラスのメソッド名は必ずしも一致しない点に注意します (例: MCP ツール get_all_models は ModelsFetcher.fetch_models、get_model_parents は fetch_model_parents に対応します)。

以下は概念を示す擬似コードです。実際の Config は接続設定を provider 経由で解決します (config.semantic_layer_config_provider.get_config() / config.discovery_config_provider.get_config() を await して SemanticLayerConfig / DiscoveryConfig を得ます)。属性を直接参照する形ではない点に注意してください。

import asyncio
from dbt_mcp.config.config import load_config
from dbt_mcp.semantic_layer.client import SemanticLayerFetcher
from dbt_mcp.discovery.client import ModelsFetcher

async def main():
    config = load_config()

    # 接続設定は provider 経由で解決する (擬似コード)
    sl_config = await config.semantic_layer_config_provider.get_config()
    disc_config = await config.discovery_config_provider.get_config()

    # 意味層: メトリクス一覧とクエリ
    sl_fetcher = SemanticLayerFetcher(client_provider)
    metrics = await sl_fetcher.list_metrics(config=sl_config)
    result = await sl_fetcher.query_metrics(
        config=sl_config,
        metrics=["revenue"],
        group_by=[{"name": "metric_time", "grain": "day"}],
        limit=1000,
    )

    # discovery: lineage 遡上
    models_fetcher = ModelsFetcher(paginator=paginator)
    parents = await models_fetcher.fetch_model_parents(
        model_name="dim_products",
        config=disc_config,
    )

asyncio.run(main())

MCP サーバ自体をコードから起動する場合の最小構成です。

import asyncio
from dbt_mcp.config.config import load_config
from dbt_mcp.mcp.server import create_dbt_mcp

async def setup_server():
    config = load_config()
    server = await create_dbt_mcp(config)
    server.run(transport="stdio")

asyncio.run(setup_server())

運用

サーバの起動・停止・状態確認

dbt MCP サーバは「ローカル (stdio)」と「リモート (dbt Platform ホスト型)」の 2 系統で稼働します。稼働確認はクライアント側から行うのが基本です。

• VS Code: コマンドパレットで MCP: List Servers を実行し、稼働中サーバの一覧と状態を確認します。

• Claude Desktop: ログファイルを確認します。

  # macOS
  tail -f ~/Library/Logs/Claude/mcp*.log
  # Windows は %APPDATA%\Claude\logs を確認
  

• 詳細ログが欲しいときは、起動前に DBT_MCP_LOG_LEVEL=DEBUG を設定します。アクティブなツールセットがログに出力されます。

  export DBT_MCP_LOG_LEVEL=DEBUG
  uvx dbt-mcp
  

• 停止は、ローカル (stdio) の場合はクライアントプロセスの終了に追従します。リモートの場合は dbt Platform 側のサービスなので、クライアント側の接続設定 (URL / トークン) を外すことが実質的な停止操作です。

transport 選択

dbt MCP は MCP 仕様の 2 トランスポートに対応します。用途に応じて選びます。

• ローカルサーバはマルチテナント運用や複数ユーザーへのホスティングに向きません。複数ユーザーに使わせるアプリケーションを作る場合はリモート (streamable HTTP) を選びます。
• ローカルデバッグ目的で stdio の代わりに HTTP を使いたい場合は、環境変数 MCP_TRANSPORT=streamable-http を設定します。

監査・ロギング

• DO_NOT_TRACK に true を設定すると、dbt MCP の利用トラッキング (テレメトリ) を無効化できます。社内ポリシーでテレメトリ送信を止めたい場合に使います。
• dbt MCP サーバ自体は本番データを保持・保存しません。監査の主眼は「エージェントが何を引いたか」の記録であり、これは実行基盤側 (dbt Platform / Databricks) のログに委ねます。
• リモート MCP 経由の execute_sql / query_metrics は dbt Platform infra を通るため、dbt Platform の実行ログが「誰が・いつ・どの metric / SQL を引いたか」の中央記録になります。Databricks 側は Unity Catalog の監査ログと突き合わせることで、意味層からの発行クエリと実データアクセスを二重に追跡できます。
• 障害解析の再現性を担保するため、get_metrics_compiled_sql (実行せずコンパイル済み SQL のみ返す) を先に呼び、実際に execute_sql を叩く前にログへ残すフローを徹底します。

環境分離

• DBT_PROD_ENV_ID は本番環境 ID で、意味層の read (list_metrics / query_metrics など) や discovery 系ツールが参照します。

• DBT_DEV_ENV_ID は開発環境 ID で、execute_sql はこちらを使います。execute_sql には合わせて DBT_USER_ID の設定も必須です。

• execute_sql は Personal Access Token (PAT) が前提で、Service Token では動作しません。本番の read 専用ツールとは認証方式ごと分離する設計になっています。

• つまり「本番の意味層は read-only で広く共有」「execute_sql による生 SQL 実行は開発環境 + 個人 PAT に限定」という二重の分離が既定の設計です。

  export DBT_HOST=cloud.getdbt.com
  export DBT_PROD_ENV_ID=54321   # 意味層 read 用 (数値 ID、URL 貼り付け不可)
  export DBT_DEV_ENV_ID=98765    # execute_sql 用
  export DBT_USER_ID=123
  export DBT_TOKEN=<PAT>         # execute_sql は PAT 必須、Service Token 不可
  

意味層応答のサイズ制御

意味層のレスポンスが大きくなりすぎると、エージェントのコンテキストを圧迫したり応答が途中で切れたりします。2 つの環境変数で制御します。

# 大規模な意味層モデルでレスポンス欠落が疑われる場合、上限を引き上げて様子を見る
export DBT_MCP_SL_MAX_RESPONSE_CHARS=32000
export DBT_MCP_SL_METRICS_RELATED_MAX=20

上限を上げるとコンテキスト消費が増えます。まずは query_metrics の group_by / limit を絞る、get_dimension_values はスコープを metrics で限定する、といったクエリ側の粒度調整を優先し、それでも足りない場合にのみ上限を調整します。

ベストプラクティス

最小権限 / truth layer 分離

dbt MCP の設計論の核心は「エージェントにどの truth layer を、どの権限で開けるか」を明示的に決めることです。

• dbt MCP のツール群は系統 (semantic layer / discovery / SQL / admin API / dbt CLI) に分かれ、系統ごとに有効・無効を切り替えられます。まず必要な系統だけを開けます。

  # semantic layer と discovery だけを許可し、それ以外は無効化する例
  export DISABLE_SEMANTIC_LAYER=false
  export DISABLE_DISCOVERY=false
  export DISABLE_ADMIN_API=true
  export DISABLE_DBT_CLI=true
  export DISABLE_DBT_CODEGEN=true    # 既定で無効
  

• allowlist 方式に倒す場合は DBT_MCP_ENABLE_* 系を使い、個別ツール単位まで絞り込みます。

  export DBT_MCP_ENABLE_SEMANTIC_LAYER=true
  export DBT_MCP_ENABLE_DISCOVERY=true
  export DBT_MCP_ENABLE_TOOLS=list_metrics,query_metrics,get_dimensions,get_model_parents
  

• BI 障害解析用のエージェントには、既定で read-only な semantic layer と discovery のみを開け、execute_sql や admin API は allowlist から外すことを起点にします。生 SQL 実行が必要になった場合のみ、開発環境 (DBT_DEV_ENV_ID) 限定・個人 PAT 限定で個別に許可します。

• MCP クライアント側でも「ツール呼び出しは既定で拒否し、許可されたツールだけ明示的に許可する」姿勢を徹底します。サーバ側の allowlist とクライアント側の承認フローの二段構えにすることで、単一障害点を避けられます。

生データ丸投げの回避

• text-to-SQL をエージェントに直叩きさせる構成は、幻覚 SQL (存在しない列・誤った JOIN)、全表スキャンによる高コストクエリ、PII を含む列の意図しない取得、といったリスクを内包します。読み取り専用のクエリであっても、PII 露出やテナント境界の越境、フィールドレベルのポリシー違反は起こり得ます。
• dbt MCP の query_metrics / get_metrics_compiled_sql は、意味層で定義済みの metric・dimension のみを組み合わせる形に閉じているため、エージェントが任意のテーブル・列を自由に組み立てる余地がありません。これが「生データ丸投げ」との本質的な違いです。
• text_to_sql ツールや execute_sql を使う場合も、コンパイル済み SQL を必ず人間または上位エージェントがレビューしてから実行する運用 (get_metrics_compiled_sql で先に中身を確認する等) を挟み、生成された SQL を無条件に実行しないようにします。
• スキーマ情報が古いままだと、エージェントは古いテーブル名・列名をもとに幻覚 SQL を生成しやすくなります。dbt プロジェクトのドキュメント (discovery ツールが返す情報) を最新に保つことが、幻覚対策として直接効きます。

意味層 = 契約

• dbt Semantic Layer は metric 定義をバージョン管理された YAML として一元化し、BI ツール・ノートブック・AI エージェントのすべてが同じ定義を参照する single source of truth にします。
• エージェントには「定義された意味」だけを引かせ、生テーブルへの直接アクセスは検証層 (Databricks SQL) に限定します。これにより、同じ指標名が経路ごとに違う計算式で出る「意味的ドリフト」を防ぎます。
• 意味層は AI エージェントに対するガードレールでもあり、承認済み・統制された・文脈化された metric のみをクエリさせる強制力を持ちます。エージェントが自由にロジックを組み立てるのではなく、既存の契約 (metric 定義) の範囲内でしか動けない状態を作ります。
• 障害解析の起点は常に「意味層で定義された metric のズレ」から入り、必要な場合のみ検証層 (Databricks SQL) に降りて実データを確認する順序を固定します。逆順 (生データから先に当たる) は truth layer の分離を無意味にします。

Databricks 側ガバナンス

• Unity Catalog は列レベルマスキング・行レベルフィルタリング・きめ細かいアクセス制御・自動監査ログ・エンドツーエンドのリネージを提供し、最小権限のデータアクセスポリシーを実装する基盤になります。
• エージェントが呼び出す SQL Warehouse は read-only 設定にし、DDL/DML (CREATE/DROP/INSERT/UPDATE/DELETE) を実行できないロールに紐付けます。execute_sql 相当のツールを開ける場合でも、接続先ウェアハウスの権限そのものを read-only に倒しておくことで、二重の防御線になります。
• Databricks のエージェント基盤はデフォルトでシステムサービスプリンシパルに read-only 権限を割り当てます。マルチユーザー用途では、共有サービスアカウントでなく on-behalf-of (OBO) 認可で「問い合わせたユーザーの権限」をそのままエージェントに伝播させる構成が推奨されます。
• コスト境界の管理として、SQL Warehouse に自動停止 (auto-stop) とクラスタサイズ上限を設定し、意味層を経由しない大規模スキャンクエリが誤って高コストを生まないようにします。PII を含む列は Unity Catalog のカラムマスキングやビュー越しの公開に留め、エージェントが直接 PII 列に触れない設計にします。

監査証跡

• BI 障害解析は「誰が・いつ・どの metric / SQL を・どの権限で引いたか」を再現できて初めて成立します。dbt Platform 側の実行ログと Databricks Unity Catalog の監査ログを突き合わせる前提で運用します。
• dbt MCP 側のログ (DBT_MCP_LOG_LEVEL=DEBUG 時のツール呼び出し履歴) と Unity Catalog の監査ログを組み合わせることで、「エージェントが意味層のどの metric を引き、その裏で Databricks のどのテーブルに到達したか」を追跡できます。
• 障害解析ワークフローの各ステップ (metric 確認 → lineage 遡上 → compiled SQL 確認 → 実データ検証) をログとして残すことで、同じ障害が再発したときに手順を再利用できる資産になります。

CI/CD・マルチ環境・セキュリティ

• 環境変数 (トークン・env ID) は CI/CD のシークレットストアで管理し、リポジトリや Flow 定義に平文で残しません。
• 本番・開発・CI の 3 環境で DBT_PROD_ENV_ID / DBT_DEV_ENV_ID / トークンの組を明確に分け、CI では admin API・dbt CLI 系ツールをデフォルトで無効化しておきます。
• MCP サーバをローカル (stdio) で複数エージェントに配布する場合は、コンテナやサンドボックスに隔離し、各ツールに明示的なアウトバウンド allowlist (接続先ドメイン/IP) を設定して、意図しない外部通信を遮断します。
• リモート MCP サーバ (streamable HTTP) を使う場合は TLS を必須にし、トークンは定期ローテーションします。新トークンを発行してシステムに反映してから旧トークンを削除する順序を守り、サービス断を避けます。

導入前チェックリスト

このチェックリストを先に埋めると、MCP サーバの接続確認だけで導入を終えず、権限・監査・コスト境界まで含めた運用設計として着地できます。

トラブルシューティング

まとめ

dbt MCP は、AI エージェントに dbt の意味層・リネージ・compiled SQL を渡し、Databricks を検証層として組み合わせることで、BI の数字不整合を安全に追跡するための接続面になります。導入時は、Semantic Layer と Discovery を正本にし、SQL 実行を read-only・開発環境・監査可能な経路に限定すると、生データ丸投げ型の text-to-SQL よりも運用しやすい障害解析フローを作れます。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• 公式ドキュメント・一次ソース
  • How MCP connects your AI agent to dbt and Databricks | dbt Labs (起点ブログ)
  • About dbt Model Context Protocol (MCP) server | dbt Developer Hub
  • Available tools | dbt Developer Hub
  • Set up local MCP | dbt Developer Hub
  • Set up remote MCP | dbt Developer Hub
  • MCP environment variables reference | dbt Developer Hub
  • MCP troubleshooting | dbt Developer Hub
  • Building the Remote dbt MCP Server | dbt Developer Blog
  • dbt Semantic Layer | dbt Developer Hub
• GitHub・パッケージ
  • dbt-labs/dbt-mcp | GitHub
  • dbt-mcp | PyPI
  • dbt-mcp deepwiki
  • OpenAI Agents SDK 連携例 (streamable HTTP / stdio)
  • [Bug]: Personal Access Token not working with remote MCP server · Issue #379
  • dbt_mcp/config/settings.py (DbtMcpSettings)
  • dbt_mcp/semantic_layer/types.py
  • dbt_mcp/discovery/client.py
• 公式記事・ガバナンス背景
  • Unify metrics and accelerate analytics with dbt Semantic Layer | dbt Labs
  • Why metric definitions matter for reliable AI agents | dbt Labs
  • How a semantic layer prevents AI hallucinations in analytics | dbt Labs
  • Governing AI agents at scale with Unity Catalog | Databricks Blog
  • Data and AI governance with Unity Catalog | Databricks
• セキュリティ関連記事
  • Safe Text-to-SQL: Giving an Agent Database Access Without Dropping Tables or Leaking PII
  • Text-to-SQL Security: 10 Risks Before Production Deployment
  • MCP Security - OWASP Cheat Sheet Series
  • Security Best Practices - Model Context Protocol