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

Платформа dbt

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

[![Архитектура удалённого MCP-сервера dbt](/img/mcp/remote-dbt-mcp.jpg?v=2 "Архитектура удалённого MCP-сервера dbt")](#)Архитектура удалённого 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-сервер в собственной инфраструктуре](https://docs.getdbt.tech/docs/dbt-ai/setup-local-mcp.md).

Удалённый 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 продолжат работать. Если вам нужна помощь, обратитесь к менеджеру вашего аккаунта.

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

| Если вам нужно...                                                                                                           | Используйте...                                                                                                                                           |
| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Максимально быстрая первоначальная настройка, а ваш MCP-клиент поддерживает OAuth для HTTP-серверов (включая `execute_sql`) | **[OAuth (удалённый MCP)](#oauth-remote-mcp)**<br />Доступно в рамках публичного бета-тестирования для учётных записей Starter, Enterprise и Enterprise+ |
| `execute_sql` с аутентификацией по токену, автоматизация, общая конфигурация или клиенты без поддержки OAuth                | **Аутентификацию по токену** с [персональным токеном доступа (PAT)](https://docs.getdbt.tech/docs/dbt-apis/user-tokens.md)                              |
| Общая или командная конфигурация                                                                                            | **Сервисный токен** (аутентификация по токену)                                                                                                           |
| CI или автоматизация                                                                                                        | **Сервисный токен** (аутентификация по токену)                                                                                                           |

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

Если вы подключаетесь с помощью токена, а не OAuth, `execute_sql` работает только с [персональным токеном доступа (PAT)](https://docs.getdbt.tech/docs/dbt-apis/user-tokens.md). Сервисные токены не подойдут. Чтобы выполнять SQL без создания PAT, используйте [OAuth (удалённый MCP)](#oauth-remote-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](https://docs.getdbt.tech/docs/platform/manage-access/enterprise-permissions.md) и [Сервисные токены](https://docs.getdbt.tech/docs/dbt-apis/service-tokens.md#permissions-for-service-account-tokens). PAT наследует права создавшего его пользователя. OAuth дополнительно ограничивает доступ согласованными областями и проектами.

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

## OAuth (remote MCP) [Бета-версия](https://docs.getdbt.tech/docs/dbt-versions/product-lifecycles "Подробнее о статусе или тарифе")[Starter](https://www.getdbt.com/pricing "Подробнее о статусе или тарифе")[Enterprise](https://www.getdbt.com/pricing "Подробнее о статусе или тарифе")[Enterprise +](https://www.getdbt.com/pricing "Подробнее о статусе или тарифе")

Если 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-url).

Функции ИИ включены по умолчанию. Администраторы могут [отключать и снова включать их](https://docs.getdbt.tech/docs/platform/manage-dbt-ai.md). При отключении удалённый MCP остаётся доступным, но инструмент [`text_to_sql`](https://docs.getdbt.tech/docs/dbt-ai/mcp-available-tools.md#tools-that-require-ai-features) скрывается.

### 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-адреса](https://docs.getdbt.tech/docs/platform/about-platform/access-regions-ip-addresses.md).

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

1. Откройте настройки коннекторов или интеграций MCP-клиента и добавьте свой [URL MCP](#mcp-url). Например, для Claude или ChatGPT:

   * **Claude (web)**: **Customize** → **Connectors** → **+** → **Add custom connector**
   * **ChatGPT**: **Settings** → **Apps** → **Create App**
   * Для Claude Desktop и Claude Code см. [Интеграция Claude с dbt MCP](https://docs.getdbt.tech/docs/dbt-ai/integrate-mcp-claude.md).

2. Когда клиент предложит войти, завершите вход в браузере и подтвердите запрошенные области доступа на экране согласия.

3. Вернитесь в MCP-клиент. Последующие запросы будут использовать сеанс OAuth в соответствии с настройками клиента.

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

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

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

* **Динамическая регистрация (по умолчанию)** — клиенты с поддержкой [Dynamic Client Registration (RFC 7591)](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md#dynamic-registration) регистрируются при первом подключении без участия администратора. Этот способ поддерживают многие современные MCP-клиенты, включая Claude Desktop, Claude Code, Cursor и VS Code.
* **Ручная регистрация** — если клиент не поддерживает динамическую регистрацию, администратор аккаунта добавляет его в **Account settings → Integrations → App integrations**. Вручную зарегистрированные клиенты используют [PKCE (RFC 7636)](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md#manual-registration) вместо секрета клиента. См. [Ручная регистрация](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md#manual-registration).

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

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

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

Полный список областей доступа и их описание см. в разделе [Области доступа и согласие](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md#scopes-and-consent). Информацию о сеансах, токенах обновления, отзыве доступа и журнале аудита см. в разделе [Подключение приложений через OAuth](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md).

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

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

* **Общие учётные данные для аналитики (рекомендуется):** администратор настраивает [учётные данные для аналитики](https://docs.getdbt.tech/docs/platform/wizard-read-only-users.md#set-up-analytics-credentials) для подключения. Пользователи с доступом на чтение без личных учётных данных используют их автоматически, поэтому им не нужно входить в dbt platform.
* **Личные учётные данные:** пользователи с набором разрешений [Analyst read](https://docs.getdbt.tech/docs/platform/manage-access/enterprise-permissions.md#analyst-read) могут добавить свои данные в **Your profile** → **Credentials**. Если личные данные настроены, они имеют приоритет.

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

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

* Удалённый MCP не поддерживает локальные команды dbt CLI, включая `dbt run`, `dbt build` и `dbt test`, и не имеет доступа к локальному проекту. Для такой работы используйте [локальный MCP-сервер](https://docs.getdbt.tech/docs/dbt-ai/setup-local-mcp.md).

Инструкции для конкретных клиентов см. в разделах [Claude](https://docs.getdbt.tech/docs/dbt-ai/integrate-mcp-claude.md), [Cursor](https://docs.getdbt.tech/docs/dbt-ai/integrate-mcp-cursor.md), [Snowflake Cortex](https://docs.getdbt.tech/docs/dbt-ai/integrate-mcp-snowflake-cortex.md) и [VS Code](https://docs.getdbt.tech/docs/dbt-ai/integrate-mcp-vscode.md).

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

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

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

### Настройка

Функции ИИ включены по умолчанию. Администраторы могут [отключать и снова включать их](https://docs.getdbt.tech/docs/platform/manage-dbt-ai.md). При отключении удалённый MCP остаётся доступным, но инструмент [`text_to_sql`](https://docs.getdbt.tech/docs/dbt-ai/mcp-available-tools.md#tools-that-require-ai-features) скрывается.

1. Получите в 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-адреса](https://docs.getdbt.tech/docs/platform/about-platform/access-regions-ip-addresses.md).
* **ID производственной среды**: найдите его в **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) или сервисный токен с [правами для нужных инструментов и ресурсов](#permissions). Для сервисного токена назначьте подходящие наборы разрешений. PAT наследует права создавшего его пользователя.
* Для `execute_sql` нужен [персональный токен доступа (PAT)](https://docs.getdbt.tech/docs/dbt-apis/user-tokens.md). Сервисный токен для этого инструмента не подходит. PAT также нужен для других инструментов, которые требуют `x-dbt-user-id`.

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

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

| Заголовок                 | Обязательный? | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization             | Да            | Ваш [персональный токен доступа (PAT)](https://docs.getdbt.tech/docs/dbt-apis/user-tokens.md) или [сервисный токен](https://docs.getdbt.tech/docs/dbt-apis/service-tokens.md) из dbt platform с [необходимыми разрешениями](#permissions). При использовании Semantic Layer рекомендуем использовать PAT.<br /><br />Значение должно быть в формате `Token YOUR_DBT_ACCESS_TOKEN` или `Bearer YOUR_DBT_ACCESS_TOKEN`, где `YOUR_DBT_ACCESS_TOKEN` необходимо заменить вашим фактическим токеном. |
| x-dbt-prod-environment-id | Да            | Идентификатор вашей производственной среды в dbt platform. Пошаговые инструкции см. в разделе [Как найти идентификаторы dbt MCP](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md#dbt-prod-env-id).                                                                                                                                                                                                                                                                                           |

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

| Заголовок                | Обязательный                 | Описание                                                                                                                                                                                          |
| ------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| x-dbt-dev-environment-id | Обязателен для `execute_sql` | Идентификатор вашей среды разработки в dbt platform. Пошаговые инструкции см. в разделе [Как найти идентификаторы dbt MCP](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md#dbt-dev-env-id). |
| x-dbt-user-id            | Обязателен для `execute_sql` | Идентификатор вашего пользователя в dbt platform. Подробнее см. в разделе [Где найти идентификатор пользователя?](https://docs.getdbt.tech/faqs/Accounts/find-user-id.md).                       |

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

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

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

| Заголовок                  | Обязательный?  | Описание                                                                                                                                                                                                                                                      |
| -------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| x-dbt-dev-environment-id   | Обязательный   | ID вашей среды разработки dbt platform. Пошаговые инструкции см. в разделе [Как найти ID для dbt MCP](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md#dbt-dev-env-id).                                                                                  |
| x-dbt-user-id              | Обязательный   | Ваш ID пользователя dbt platform. Подробнее см. в разделе [Где найти мой ID пользователя?](https://docs.getdbt.tech/faqs/Accounts/find-user-id.md).                                                                                                          |
| 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`     |

3. Определив, какие заголовки вам нужны, вы можете воспользоваться [примерами](https://github.com/dbt-labs/dbt-mcp/tree/main/examples), чтобы создать собственного агента.

## Примеры

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

### OAuth

### Claude Code

```json
{
  "mcpServers": {
    "dbt": {
      "type": "http",
      "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/"
    }
  }
}
```

### Cursor

```json
{
  "mcpServers": {
    "dbt": {
      "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/"
    }
  }
}
```

### Token-based

### 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"
      }
    }
  }
}
```

### Gemini

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

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

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

```bash
# ✅ 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 настраивается через переменные окружения. См. [Справочник по переменным окружения](https://docs.getdbt.tech/docs/dbt-ai/mcp-environment-variables.md).

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

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

* [Интеграция Cursor с MCP](https://docs.getdbt.tech/docs/dbt-ai/integrate-mcp-cursor.md)
* [Интеграция VS Code с MCP](https://docs.getdbt.tech/docs/dbt-ai/integrate-mcp-vscode.md)
* [Интеграция Claude с MCP](https://docs.getdbt.tech/docs/dbt-ai/integrate-mcp-claude.md)
* [Интеграция Snowflake Cortex с MCP](https://docs.getdbt.tech/docs/dbt-ai/integrate-mcp-snowflake-cortex.md)