Настройка удалённого MCP

Удалённый MCP-сервер использует HTTP-соединение и выполняет вызовы к dbt-mcp, размещённому на облачной платформе dbt platform. Для использования удалённого MCP-сервера не требуется самостоятельное развёртывание; этот вариант идеально подходит для сценариев потребления данных.

Архитектура удалённого MCP-сервера dbt

Когда использовать удалённый MCP

Удалённый MCP-сервер — идеальный выбор, если:

Вы не хотите или не можете устанавливать дополнительное программное обеспечение (uvx, dbt-mcp) в своей системе.
Ваш основной сценарий использования — получение данных: запросы метрик, изучение метаданных, просмотр происхождения данных.
Вам нужен доступ к API Semantic Layer, Administrative и Discovery без необходимости поддерживать локальный проект dbt.
Вам не требуется выполнять команды CLI. Удалённый MCP не поддерживает выполнение команд dbt CLI в собственной инфраструктуре (dbt run, dbt build, dbt test и других). Если вам нужно выполнять команды dbt, используйте MCP-сервер в собственной инфраструктуре.

Удалённый MCP не требует функций ИИ

Для использования удалённого MCP не требуется включать функции ИИ. Если администратор отключит функции ИИ, text_to_sql будет единственным скрытым инструментом, а все остальные инструменты продолжат работать.

text_to_sql — также единственный инструмент, который расходует выделенный вам лимит действий dbt Copilot. Другие инструменты MCP его не расходуют.

Если в вашем аккаунте исчерпан лимит действий dbt Copilot, text_to_sql не будет работать до сброса лимита. Другие инструменты удалённого MCP продолжат работать. Если вам нужна помощь, обратитесь к менеджеру вашего аккаунта.

Выберите способ аутентификации

Если вам нужно...	Используйте...
Максимально быстрая первоначальная настройка, а ваш MCP-клиент поддерживает OAuth для HTTP-серверов (включая `execute_sql`)	OAuth (удалённый MCP) Доступно в рамках публичного бета-тестирования для учётных записей Starter, Enterprise и Enterprise+
`execute_sql` с аутентификацией по токену, автоматизация, общая конфигурация или клиенты без поддержки OAuth	Аутентификацию по токену с персональным токеном доступа (PAT)
Общая или командная конфигурация	Сервисный токен (аутентификация по токену)
CI или автоматизация	Сервисный токен (аутентификация по токену)

Сервисные токены не работают с execute_sql

Если вы подключаетесь с помощью токена, а не OAuth, execute_sql работает только с персональным токеном доступа (PAT). Сервисные токены не подойдут. Чтобы выполнять SQL без создания PAT, используйте OAuth (удалённый MCP).

Разрешения для удалённого MCP

Удалённый MCP проверяет ваши права доступа при подключении, а затем при каждом вызове инструмента проверяет, разрешён ли вам доступ к целевому проекту, среде, заданию или запуску. Эти проверки применяются к OAuth, персональным токенам доступа (PAT) и сервисным токенам. Успешное подключение или отображение инструмента в клиенте не означает, что вы можете использовать этот инструмент для любого ресурса.

Для самого подключения набор разрешений Developer не требуется. Попросите администратора выдать права, необходимые для вашей работы:

Задача	Необходимые права
Изучать модели и граф зависимостей или генерировать SQL через `text_to_sql`	Право на чтение метаданных выбранного проекта. Для `text_to_sql` также должны быть включены функции ИИ.
Использовать инструменты семантического слоя	Право на чтение конфигурации семантического слоя в выбранном проекте.
Выполнять обычный SQL через `execute_sql`	Право на чтение конфигурации семантического слоя в проекте, среда разработки и учётные данные хранилища. Подключитесь через OAuth или PAT.
Выполнять SQL с выражениями Jinja dbt, например `ref()` или `source()`	Требования для обычного SQL и доступ к разработке. Чтобы разрешать ссылки по состоянию производственной среды, также нужно право на чтение метаданных.
Просматривать задания и запуски или управлять ими	Права на чтение или запись для нужного задания или запуска. Для списков без фильтра по проекту нужны соответствующие права на уровне аккаунта.

Доступные наборы разрешений описаны в разделах Разрешения Enterprise и Сервисные токены. PAT наследует права создавшего его пользователя. OAuth дополнительно ограничивает доступ согласованными областями и проектами.

Сервисный токен с правом чтения метаданных позволяет генерировать SQL через text_to_sql. Выполнять SQL через execute_sql с таким токеном нельзя.

OAuth (remote MCP) Бета-версия Starter Enterprise Enterprise +

Если MCP-клиент поддерживает OAuth для серверов по HTTP, через OAuth можно подключиться к удалённому MCP-серверу без копирования токенов API в клиент.

Предварительные требования

Аккаунт на тарифе Starter, Enterprise или Enterprise+.
MCP-клиент с поддержкой OAuth для удалённых MCP-серверов по HTTP.
URL MCP из раздела Account settings → Access URLs → MCP Endpoint URL в dbt platform. Подробнее см. URL MCP.

Функции ИИ включены по умолчанию. Администраторы могут отключать и снова включать их. При отключении удалённый MCP остаётся доступным, но инструмент text_to_sql скрывается.

MCP URL

Вы можете скопировать полный MCP URL в разделе Account settings → Access URLs → MCP Endpoint URL в dbt platform и вставить его непосредственно в свой ИИ-инструмент.

Составьте собственный MCP URL

Рекомендуем использовать MCP URL из раздела Account settings → Access URLs → MCP Endpoint URL в dbt platform. Однако, если вы хотите составить собственный MCP URL, используйте свой Access URL из раздела Account settings в dbt platform. Удаленная конечная точка MCP — https://YOUR_DBT_HOST_URL/api/ai/v1/mcp. Замените YOUR_DBT_HOST_URL только именем хоста (без https://).

Информацию о хостах по умолчанию, аккаунтах multi-cell и регионах см. в разделе Доступ, регионы и IP-адреса.

Как это работает

Откройте настройки коннекторов или интеграций MCP-клиента и добавьте свой URL MCP. Например, для Claude или ChatGPT:
- Claude (web): Customize → Connectors → + → Add custom connector
- ChatGPT: Settings → Apps → Create App
- Для Claude Desktop и Claude Code см. Интеграция Claude с dbt MCP.
Когда клиент предложит войти, завершите вход в браузере и подтвердите запрошенные области доступа на экране согласия.
Вернитесь в MCP-клиент. Последующие запросы будут использовать сеанс OAuth в соответствии с настройками клиента.

execute_sql поддерживает OAuth. Добавьте URL MCP в клиент и войдите по его запросу. Персональный токен доступа и дополнительные заголовки не нужны.

Регистрация MCP-клиента

Для OAuth каждый клиент нужно зарегистрировать в dbt platform. Это можно сделать двумя способами:

Динамическая регистрация (по умолчанию) — клиенты с поддержкой Dynamic Client Registration (RFC 7591) регистрируются при первом подключении без участия администратора. Этот способ поддерживают многие современные MCP-клиенты, включая Claude Desktop, Claude Code, Cursor и VS Code.
Ручная регистрация — если клиент не поддерживает динамическую регистрацию, администратор аккаунта добавляет его в Account settings → Integrations → App integrations. Вручную зарегистрированные клиенты используют PKCE (RFC 7636) вместо секрета клиента. См. Ручная регистрация.

Клиенты, зарегистрированные обоими способами, отображаются в разделе App integrations в dbt platform. Администраторы могут просматривать и проверять подключённые клиенты.

При первом подключении dbt показывает экран согласия со списком областей доступа, которые запрашивает клиент. Эти области ограничивают уже выданные разрешения и не предоставляют новых прав. Можно разрешить клиенту доступ ко всем проектам или только к выбранным.

Полный список областей доступа и их описание см. в разделе Области доступа и согласие. Информацию о сеансах, токенах обновления, отзыве доступа и журнале аудита см. в разделе Подключение приложений через OAuth.

Пользователи с доступом на чтение и учётные данные хранилища

Пользователям с доступом на чтение для запросов через удалённый MCP, например через query_metrics, нужны учётные данные хранилища. Есть два варианта:

Общие учётные данные для аналитики (рекомендуется): администратор настраивает учётные данные для аналитики для подключения. Пользователи с доступом на чтение без личных учётных данных используют их автоматически, поэтому им не нужно входить в dbt platform.
Личные учётные данные: пользователи с набором разрешений Analyst read могут добавить свои данные в Your profile → Credentials. Если личные данные настроены, они имеют приоритет.

Если ни один вариант не настроен, запрос завершится ошибкой и предложит настроить учётные данные или обратиться к администратору.

Ограничения

Удалённый MCP не поддерживает локальные команды dbt CLI, включая dbt run, dbt build и dbt test, и не имеет доступа к локальному проекту. Для такой работы используйте локальный MCP-сервер.

Инструкции для конкретных клиентов см. в разделах Claude, Cursor, Snowflake Cortex и VS Code.

Аутентификация по токену

Чтобы подключиться к удалённому MCP без OAuth, укажите PAT или сервисный токен в конфигурации MCP-клиента. Это подходит для клиентов без поддержки OAuth, а также для общих конфигураций и CI. Для вызова execute_sql при аутентификации по токену используйте PAT.

Для каждого вызова инструмента нужно иметь разрешения на целевой ресурс. При подключении по токену в списке могут отображаться инструменты, недоступные этому токену. Их вызовы завершаются ошибкой по отдельности. OAuth также может фильтровать список инструментов по выданным разрешениям.

Настройка

Получите в dbt platform следующие данные:

Хост dbt platform: используйте его для полного URL. Например, подставьте адрес вместо YOUR_DBT_HOST_URL в https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/. Пример: https://cloud.getdbt.com/api/ai/v1/mcp/. Для аккаунта с несколькими ячейками хост имеет формат ACCOUNT_PREFIX.us1.dbt.com. Подробнее см. Доступ, регионы и IP-адреса.
ID производственной среды: найдите его в Orchestration → Environments в dbt platform и укажите в заголовке x-dbt-prod-environment-id. См. Как найти идентификаторы dbt MCP.
Токен: создайте персональный токен доступа (PAT) или сервисный токен с правами для нужных инструментов и ресурсов. Для сервисного токена назначьте подходящие наборы разрешений. PAT наследует права создавшего его пользователя.
Для execute_sql нужен персональный токен доступа (PAT). Сервисный токен для этого инструмента не подходит. PAT также нужен для других инструментов, которые требуют x-dbt-user-id.

В конфигурации удалённого MCP укажите обязательные заголовки в JSON:

Конфигурация для API и SQL-инструментов

Заголовок	Обязательный?	Описание
Authorization	Да	Ваш персональный токен доступа (PAT) или сервисный токен из dbt platform с необходимыми разрешениями. При использовании Semantic Layer рекомендуем использовать PAT. Значение должно быть в формате `Token YOUR_DBT_ACCESS_TOKEN` или `Bearer YOUR_DBT_ACCESS_TOKEN`, где `YOUR_DBT_ACCESS_TOKEN` необходимо заменить вашим фактическим токеном.
x-dbt-prod-environment-id	Да	Идентификатор вашей производственной среды в dbt platform. Пошаговые инструкции см. в разделе Как найти идентификаторы dbt MCP.

Дополнительная настройка для инструментов SQL

Заголовок	Обязательный	Описание
x-dbt-dev-environment-id	Обязателен для `execute_sql`	Идентификатор вашей среды разработки в dbt platform. Пошаговые инструкции см. в разделе Как найти идентификаторы dbt MCP.
x-dbt-user-id	Обязателен для `execute_sql`	Идентификатор вашего пользователя в dbt platform. Подробнее см. в разделе Где найти идентификатор пользователя?.

Используйте положительные числовые идентификаторы в заголовках проекта и среды. Заголовки среды разработки и производственной среды должны указывать на среды соответствующего типа в одном и том же проекте. Если инструмент принимает аргумент проекта или среды, он должен соответствовать настроенному целевому объекту. list_jobs сохраняет прежнее поведение: явно заданный project_id переопределяет настроенный фильтр среды.

Дополнительная настройка для инструментов dbt v2

По умолчанию инструменты dbt v2 берут метаданные моделей и таблиц из среды, указанной в x-dbt-prod-environment-id.

Заголовок	Обязательный?	Описание
x-dbt-dev-environment-id	Обязательный	ID вашей среды разработки dbt platform. Пошаговые инструкции см. в разделе Как найти ID для dbt MCP.
x-dbt-user-id	Обязательный	Ваш ID пользователя dbt platform. Подробнее см. в разделе Где найти мой ID пользователя?.
x-dbt-fusion-disable-defer	Необязательный	По умолчанию: `false`. Если установлено значение `true`, инструменты dbt v2 не будут использовать отложенные ссылки на производственную среду, а вместо этого будут использовать модели и метаданные таблиц из среды разработки (`x-dbt-dev-environment-id`).

Настройка отключения инструментов

Заголовок	Обязательность	Описание
x-dbt-disable-tools	Необязательный	Список инструментов для отключения, разделённых запятыми. Например: `get_all_models,text_to_sql,list_entities`
x-dbt-disable-toolsets	Необязательный	Список наборов инструментов для отключения, разделённых запятыми. Например: `semantic_layer,sql,discovery`

Определив, какие заголовки вам нужны, вы можете воспользоваться примерами, чтобы создать собственного агента.

Примеры

Протокол MCP не зависит от языка программирования и фреймворка, поэтому используйте любые средства, которые помогают вам создавать агентов. Если вы используете OAuth (удалённый MCP) в бета-версии, вам нужен только URL вашего MCP. Если вы используете аутентификацию на основе токенов, добавьте заголовки из примеров ниже. Конфигурация зависит от клиента — выберите свой инструмент на следующих вкладках и замените значения-заполнители своими:

OAuth
Token-based

Claude Code
Cursor

{
  "mcpServers": {
    "dbt": {
      "type": "http",
      "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/"
    }
  }
}
Сообщить об ошибке в коде

{
  "mcpServers": {
    "dbt": {
      "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/"
    }
  }
}
Сообщить об ошибке в коде

Claude Code
Cursor
Gemini

{
  "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"
      }
    }
  }
}
Сообщить об ошибке в коде

{
  "mcpServers": {
    "dbt": {
      "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"
      }
    }
  }
}
Сообщить об ошибке в коде

{
  "mcpServers": {
    "dbt": {
      "httpUrl": "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"
      }
    }
  }
}
Сообщить об ошибке в коде

Используйте числовые ID

Заголовки x-dbt-prod-environment-id и x-dbt-user-id принимают только целые числа. В поле url адрес хоста должен начинаться с https://:

# ✅ Correct
"url": "https://cloud.getdbt.com/api/ai/v1/mcp"
"x-dbt-prod-environment-id": "54321"
"x-dbt-user-id": "123"

# ❌ Wrong — don't paste full URLs into ID headers
"x-dbt-prod-environment-id": "https://cloud.getdbt.com/deploy/12345/projects/67890/environments/54321"
"x-dbt-user-id": "https://cloud.getdbt.com/settings/profile"
Сообщить об ошибке в коде

Для других MCP-клиентов, например Codex или Windsurf, формат ключа указан в документации клиента.

Локальный MCP настраивается через переменные окружения. См. Справочник по переменным окружения.

Пошаговые инструкции по настройке клиентов, включая Cursor, VS Code и Claude:

Нашли ошибку?

Создать GitHub Issue

Настройка удалённого MCP

Когда использовать удалённый MCP

Выберите способ аутентификации

Разрешения для удалённого MCP

OAuth (remote MCP) Бета-версия Starter Enterprise Enterprise +

Предварительные требования

MCP URL

Как это работает

Регистрация MCP-клиента

Пользователи с доступом на чтение и учётные данные хранилища

Ограничения

Аутентификация по токену

Настройка

Конфигурация для API и SQL-инструментов

Дополнительная настройка для инструментов SQL

Дополнительная настройка для инструментов dbt v2

Настройка отключения инструментов

Примеры

Нашли ошибку?

Начните работать с dbt.

Ресурсы dbt

Продукты

Сообщество

Поддержка

Наши соцсети

Когда использовать удалённый MCP​

Выберите способ аутентификации​

Разрешения для удалённого MCP​

OAuth (remote MCP) Бета-версияStarterEnterpriseEnterprise +​

Предварительные требования​

MCP URL​

Как это работает​

Регистрация MCP-клиента​

Области доступа, которые вы подтверждаете​

Пользователи с доступом на чтение и учётные данные хранилища​

Ограничения​

Аутентификация по токену​

Настройка​

Конфигурация для API и SQL-инструментов​

Дополнительная настройка для инструментов SQL​

Дополнительная настройка для инструментов dbt v2​

Настройка отключения инструментов​

Примеры​

Связанная документация​

Нашли ошибку?

Ресурсы dbt

Продукты

Сообщество

Поддержка

Наши соцсети

Когда использовать удалённый MCP

Выберите способ аутентификации

Разрешения для удалённого MCP

OAuth (remote MCP) Бета-версия Starter Enterprise Enterprise +

Предварительные требования

MCP URL

Как это работает

Регистрация MCP-клиента

Области доступа, которые вы подтверждаете

Пользователи с доступом на чтение и учётные данные хранилища

Ограничения

Аутентификация по токену

Настройка

Конфигурация для API и SQL-инструментов

Дополнительная настройка для инструментов SQL

Дополнительная настройка для инструментов dbt v2

Настройка отключения инструментов

Примеры

Связанная документация