# Подключение к удалённому серверу dbt MCP
Платформа dbt
Удалённый сервер 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](https://docs.getdbt.tech/docs/dbt-ai/mcp-quickstart-oauth.md) или [Запуск dbt в собственной среде](https://docs.getdbt.tech/docs/dbt-ai/mcp-quickstart-cli.md).
## Настройка удалённого MCP
Выполните следующие действия, чтобы настроить удалённый сервер MCP.
### 1. Управление функциями ИИ (необязательно)
Функции ИИ включены по умолчанию. Администраторы могут [отключать или включать их в любое время](https://docs.getdbt.tech/docs/platform/manage-dbt-ai.md).
Удалённый 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-адреса](https://docs.getdbt.tech/docs/platform/about-platform/access-regions-ip-addresses.md).
* **Идентификатор производственной среды**: находится в разделе **Orchestration** → **Environments** в dbt platform. Он используется в заголовке `x-dbt-prod-environment-id` (только при настройке с токеном). Пошаговые инструкции см. в разделе [Как найти идентификаторы dbt MCP](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md#dbt-prod-env-id).
* **Токен** — PAT или сервисный токен с разрешениями Semantic Layer и Developer (только при настройке с токеном).
* **Если вы используете `execute_sql` с аутентификацией по токену:** необходимо использовать PAT, а также идентификатор среды разработки и идентификатор пользователя. Подробнее см. в разделе [Как найти идентификаторы dbt MCP](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md). При использовании OAuth нужен только URL вашего MCP.
### 3. Выбор способа аутентификации: OAuth или токены
| Тип | Информация |
| --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[OAuth (удалённый)](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md#oauth-remote-mcp)** | Токены API в конфигурации клиента не требуются. Нужен MCP-клиент с поддержкой OAuth. Поддерживает `execute_sql`.
Доступен в общедоступной бета-версии для аккаунтов Starter, Enterprise и Enterprise+. |
| **По токену** | PAT или сервисный токен в заголовке `Authorization`. Работает с любым клиентом и требуется для общих конфигураций и CI. Для `execute_sql` необходимо использовать PAT (сервисные токены не подходят). |
к сведению
OAuth для удалённого MCP доступен в публичной бета-версии для учётных записей Starter, Enterprise и Enterprise+.
Пользователи с доступом только для чтения
Пользователи с доступом только для чтения могут запрашивать метрики через удалённый MCP, используя общие [учётные данные для аналитики](https://docs.getdbt.tech/docs/platform/wizard-read-only-users.md#set-up-analytics-credentials), без необходимости входить в dbt platform для настройки собственных учётных данных хранилища. См. [Пользователи с доступом только для чтения и учётные данные хранилища](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md#read-only-users-and-warehouse-credentials).
### 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-адреса](https://docs.getdbt.tech/docs/platform/about-platform/access-regions-ip-addresses.md).
В зависимости от способа аутентификации вам также могут понадобиться:
* **Идентификатор производственной среды**: находится в разделе **Orchestration** → **Environments** в dbt platform. Используется в заголовке `x-dbt-prod-environment-id` при настройке с токеном. Пошаговые инструкции см. в разделе [Как найти идентификаторы dbt MCP](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md#dbt-prod-env-id).
* **Токен** — PAT или сервисный токен с разрешениями Semantic Layer и Developer (только при настройке с токеном).
* **Если вы используете `execute_sql` с аутентификацией по токену:** необходимо использовать PAT, а также идентификатор среды разработки и идентификатор пользователя. Подробнее см. в разделе [Как найти идентификаторы dbt MCP](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md). При использовании OAuth нужен только URL вашего MCP.
Удалённый MCP не требует функций ИИ
Для использования удалённого MCP не требуется включать [функции ИИ](https://docs.getdbt.tech/docs/platform/manage-dbt-ai.md). Если администратор отключит функции ИИ, [`text_to_sql`](https://docs.getdbt.tech/docs/dbt-ai/mcp-available-tools.md#tools-that-require-ai-features) будет единственным скрытым инструментом, а все остальные инструменты продолжат работать.
`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. Если такой поддержки нет, используйте [аутентификацию на основе токенов](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md#token-based-authentication).
* При первом подключении клиент открывает браузер для входа в систему. Затем dbt показывает экран согласия с запрашиваемыми областями доступа (конкретными разрешениями, которые клиенту будет позволено использовать) — описание каждой области доступа см. в разделе [Области доступа и согласие](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md#scopes-and-consent).
* Большинство современных MCP-клиентов регистрируются самостоятельно при первом подключении с помощью [динамической регистрации (RFC 7591)](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md#dynamic-registration). Клиенты, которые её не поддерживают, администратор должен зарегистрировать в разделе **Account settings → Integrations → App integrations**. См. раздел [Ручная регистрация](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md#manual-registration).
Полное описание процесса, сеансов и ограничений см. в разделе [OAuth (удалённый MCP)](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md#oauth-remote-mcp).
Настройте клиент, указав URL MCP из предыдущего шага. При первом подключении клиент откроет браузер для входа и предоставления согласия. Для использования `execute_sql` не нужны персональный токен доступа или дополнительные заголовки.
Некоторые инструменты (например, Claude Desktop) позволяют добавить dbt как пользовательский коннектор через интерфейс вместо редактирования файла конфигурации:
Ниже описано, как подключить dbt в качестве пользовательского коннектора в Claude Desktop. Интерфейс зависит от инструмента, но порядок действий одинаков: добавьте пользовательский коннектор с вашим MCP URL, пройдите процедуру предоставления согласия OAuth, затем подключитесь.
1. В вашем ИИ-инструменте перейдите в настройки коннекторов и выберите добавление пользовательского коннектора (в Claude Desktop перейдите в **Chat → Customize → Connectors**, затем нажмите **Add custom connector**).
2. Введите имя (например, `dbt`) и вставьте MCP URL вашей dbt platform (например, `https://abc123.us1.dbt.com/api/ai/v1/mcp`), затем нажмите **Add**.
[](#)Диалог добавления пользовательского коннектора с MCP URL dbt
3. Нажмите **Connect**. Инструмент перенаправит вас в dbt для прохождения процедуры предоставления согласия OAuth, где вы сможете разрешить или отклонить отдельные [области доступа](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md#scopes-and-consent).
[](#)Экран согласия OAuth с запрашиваемыми областями доступа и доступом к проектам
4. После вашего согласия коннектор будет добавлен в таблицу **Custom connectors** и будет отображаться как подключённый.
[](#)Добавление пользовательского коннектора dbt в настройках коннекторов ИИ-инструмента
5. Готово 🎉! Задайте инструменту вопрос о данных, например *«Какова общая выручка за последние 30 дней?»*, чтобы проверить подключение.
Для инструментов, настраиваемых с помощью JSON-файла, выберите вкладку, соответствующую вашему клиенту:
### Claude Code
Добавьте следующий код в `.mcp.json` в корне проекта:
```json
{
"mcpServers": {
"dbt": {
"type": "http",
"url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/"
}
}
}
```
### Cursor
Добавьте следующий код в `.cursor/mcp.json` (или воспользуйтесь прямой ссылкой Cursor в разделе [Интеграция Cursor с MCP](https://docs.getdbt.tech/docs/dbt-ai/integrate-mcp-cursor.md#set-up-with-remote-dbt-mcp-server)):
```json
{
"mcpServers": {
"dbt": {
"url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/"
}
}
}
```
### VS Code
Добавьте следующий код в `mcp.json` (выполните команду **MCP: Open Workspace Folder MCP Configuration** в палитре команд). VS Code использует ключ `servers`, а не `mcpServers`:
```json
{
"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
```json
{
"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"
}
}
}
}
```
### Cursor
```json
{
"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
VS Code использует ключ `servers`, а не `mcpServers`:
```json
{
"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
Gemini использует ключ `httpUrl` вместо `url`:
```json
{
"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](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md).
* Самостоятельно развёрнутый MCP настраивается с помощью переменных окружения; дополнительную информацию см. в [Справочнике переменных окружения](https://docs.getdbt.tech/docs/dbt-ai/mcp-environment-variables.md).
После настройки MCP-клиента вы можете проверить подключение, задав ИИ-ассистенту вопрос о данных (например, *«Какие модели есть в моём проекте dbt?»* или *«Какие метрики определены в моём Semantic Layer?»*). Если dbt MCP работает, ответ будет основан на ваших метаданных dbt.