Подключение к удалённому серверу dbt MCP

Удалённый сервер MCP подключается к dbt platform по HTTP. Самостоятельно развёртывать сервер не требуется — вместо запуска uvx dbt-mcp вы настраиваете MCP-клиент, указав URL и заголовки.

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

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

Удалённый MCP подходит, если:

Вы не хотите или не можете устанавливать программное обеспечение (uvx, dbt-mcp) на своём компьютере.
Ваш сценарий предполагает использование данных: запрос метрик, изучение метаданных, просмотр зависимостей данных или выполнение SQL на платформе.
Вам нужен доступ к API Semantic Layer, Administrative и Discovery без локального проекта dbt.

Разработка в собственной среде требует самостоятельно развёрнутого MCP

Разработка в собственной среде и рабочие процессы с ИИ-агентами (например, выполнение команд dbt, таких как dbt run или dbt build, из ИИ-ассистента) требуют самостоятельно развёрнутого сервера MCP. Удалённый MCP не поддерживает локально установленные CLI dbt v1 или dbt v2 и доступ к локальным проектам. Для таких рабочих процессов воспользуйтесь инструкциями Подключение к dbt platform или Запуск dbt в собственной среде.

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

Выполните следующие действия, чтобы настроить удалённый сервер MCP.

1. Управление функциями ИИ (необязательно)

Функции ИИ включены по умолчанию. Администраторы могут отключать или включать их в любое время.

Удалённый MCP работает и без включённых функций ИИ. Они нужны только для text_to_sql: когда функции ИИ отключены, этот инструмент скрыт, а все остальные инструменты работают как обычно.

2. Получение учётных данных

Получите следующую информацию в dbt platform:

Хост dbt platform: составьте URL в формате https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/ (например, https://cloud.getdbt.com/api/ai/v1/mcp/). Для аккаунтов multi-cell хост имеет формат ACCOUNT_PREFIX.us1.dbt.com. См. Доступ, регионы и IP-адреса.
Идентификатор производственной среды: находится в разделе Orchestration → Environments в dbt platform. Он используется в заголовке x-dbt-prod-environment-id (только при настройке с токеном). Пошаговые инструкции см. в разделе Как найти идентификаторы dbt MCP.
Токен — PAT или сервисный токен с разрешениями Semantic Layer и Developer (только при настройке с токеном).
Если вы используете execute_sql с аутентификацией по токену: необходимо использовать PAT, а также идентификатор среды разработки и идентификатор пользователя. Подробнее см. в разделе Как найти идентификаторы dbt MCP. При использовании OAuth нужен только URL вашего MCP.

3. Выбор способа аутентификации: OAuth или токены

Тип	Информация
OAuth (удалённый)	Токены API в конфигурации клиента не требуются. Нужен MCP-клиент с поддержкой OAuth. Поддерживает `execute_sql`. Доступен в общедоступной бета-версии для аккаунтов Starter, Enterprise и Enterprise+.
По токену	PAT или сервисный токен в заголовке `Authorization`. Работает с любым клиентом и требуется для общих конфигураций и CI. Для `execute_sql` необходимо использовать PAT (сервисные токены не подходят).

к сведению

OAuth для удалённого MCP доступен в публичной бета-версии для учётных записей Starter, Enterprise и Enterprise+.

Пользователи с доступом только для чтения

Пользователи с доступом только для чтения могут запрашивать метрики через удалённый MCP, используя общие учётные данные для аналитики, без необходимости входить в dbt platform для настройки собственных учётных данных хранилища. См. Пользователи с доступом только для чтения и учётные данные хранилища.

4. Получение URL MCP и идентификаторов

Вы можете скопировать полный 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-адреса.

В зависимости от способа аутентификации вам также могут понадобиться:

Идентификатор производственной среды: находится в разделе Orchestration → Environments в dbt platform. Используется в заголовке x-dbt-prod-environment-id при настройке с токеном. Пошаговые инструкции см. в разделе Как найти идентификаторы dbt MCP.
Токен — PAT или сервисный токен с разрешениями Semantic Layer и Developer (только при настройке с токеном).
Если вы используете execute_sql с аутентификацией по токену: необходимо использовать PAT, а также идентификатор среды разработки и идентификатор пользователя. Подробнее см. в разделе Как найти идентификаторы dbt MCP. При использовании OAuth нужен только URL вашего MCP.

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

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

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

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

5. Настройка MCP-клиента

Настройте MCP-клиент, указав URL MCP из предыдущего шага. Если вы используете аутентификацию по токену, также добавьте необходимые заголовки.

OAuth
По токену

Доступно для аккаунтов Starter, Enterprise и Enterprise+

Перед подключением

Ваш MCP-клиент должен поддерживать OAuth для MCP-серверов, работающих по HTTP. Если такой поддержки нет, используйте аутентификацию на основе токенов.
При первом подключении клиент открывает браузер для входа в систему. Затем dbt показывает экран согласия с запрашиваемыми областями доступа (конкретными разрешениями, которые клиенту будет позволено использовать) — описание каждой области доступа см. в разделе Области доступа и согласие.
Большинство современных MCP-клиентов регистрируются самостоятельно при первом подключении с помощью динамической регистрации (RFC 7591). Клиенты, которые её не поддерживают, администратор должен зарегистрировать в разделе Account settings → Integrations → App integrations. См. раздел Ручная регистрация.

Полное описание процесса, сеансов и ограничений см. в разделе OAuth (удалённый MCP).

Настройте клиент, указав URL MCP из предыдущего шага. При первом подключении клиент откроет браузер для входа и предоставления согласия. Для использования execute_sql не нужны персональный токен доступа или дополнительные заголовки.

Некоторые инструменты (например, Claude Desktop) позволяют добавить dbt как пользовательский коннектор через интерфейс вместо редактирования файла конфигурации:

Ниже описано, как подключить dbt в качестве пользовательского коннектора в Claude Desktop. Интерфейс зависит от инструмента, но порядок действий одинаков: добавьте пользовательский коннектор с вашим MCP URL, пройдите процедуру предоставления согласия OAuth, затем подключитесь.

В вашем ИИ-инструменте перейдите в настройки коннекторов и выберите добавление пользовательского коннектора (в Claude Desktop перейдите в Chat → Customize → Connectors, затем нажмите Add custom connector).
Введите имя (например, dbt) и вставьте MCP URL вашей dbt platform (например, https://abc123.us1.dbt.com/api/ai/v1/mcp), затем нажмите Add.
Диалог добавления пользовательского коннектора с MCP URL dbt
Нажмите Connect. Инструмент перенаправит вас в dbt для прохождения процедуры предоставления согласия OAuth, где вы сможете разрешить или отклонить отдельные области доступа.
Экран согласия OAuth с запрашиваемыми областями доступа и доступом к проектам
После вашего согласия коннектор будет добавлен в таблицу Custom connectors и будет отображаться как подключённый.
Добавление пользовательского коннектора dbt в настройках коннекторов ИИ-инструмента
Готово 🎉! Задайте инструменту вопрос о данных, например «Какова общая выручка за последние 30 дней?», чтобы проверить подключение.

Для инструментов, настраиваемых с помощью JSON-файла, выберите вкладку, соответствующую вашему клиенту:

Claude Code
Cursor
VS Code

Добавьте следующий код в .mcp.json в корне проекта:

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

Добавьте следующий код в .cursor/mcp.json (или воспользуйтесь прямой ссылкой Cursor в разделе Интеграция Cursor с MCP):

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

Добавьте следующий код в mcp.json (выполните команду MCP: Open Workspace Folder MCP Configuration в палитре команд). VS Code использует ключ servers, а не mcpServers:

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

Установите для параметра сервера url значение https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/ и добавьте необходимые заголовки:

Обязательные: Authorization (значение Token YOUR_TOKEN или Bearer YOUR_TOKEN), x-dbt-prod-environment-id
Для execute_sql с аутентификацией по токену или инструментов dbt v2: также добавьте x-dbt-dev-environment-id и x-dbt-user-id
Используйте в заголовках числовые идентификаторы, а не полные URL, скопированные из браузера.

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

VS Code использует ключ servers, а не mcpServers:

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

Gemini использует ключ httpUrl вместо url:

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

Полный список заголовков, примеры для Cursor и других клиентов, а также необязательные заголовки см. в разделе Настройка удалённого MCP.
Самостоятельно развёрнутый MCP настраивается с помощью переменных окружения; дополнительную информацию см. в Справочнике переменных окружения.

После настройки MCP-клиента вы можете проверить подключение, задав ИИ-ассистенту вопрос о данных (например, «Какие модели есть в моём проекте dbt?» или «Какие метрики определены в моём Semantic Layer?»). Если dbt MCP работает, ответ будет основан на ваших метаданных dbt.

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

Создать GitHub Issue

Подключение к удалённому серверу dbt MCP

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

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

1. Управление функциями ИИ (необязательно)

2. Получение учётных данных

3. Выбор способа аутентификации: OAuth или токены

4. Получение URL MCP и идентификаторов

5. Настройка MCP-клиента

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

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

Ресурсы dbt

Продукты

Сообщество

Поддержка

Наши соцсети

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

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

1. Управление функциями ИИ (необязательно)​

2. Получение учётных данных​

3. Выбор способа аутентификации: OAuth или токены​

4. Получение URL MCP и идентификаторов​

5. Настройка MCP-клиента​

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

Ресурсы dbt

Продукты

Сообщество

Поддержка

Наши соцсети

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

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

1. Управление функциями ИИ (необязательно)

2. Получение учётных данных

3. Выбор способа аутентификации: OAuth или токены

4. Получение URL MCP и идентификаторов

5. Настройка MCP-клиента