# Частые вопросы о dbt MCP и устранение неполадок

Здесь вы найдёте ответы на частые вопросы о сервере dbt Model Context Protocol (MCP) и способы устранения распространённых проблем с настройкой. Инструкции для конкретных клиентов см. в разделах об устранении неполадок на страницах [Начало работы](https://docs.getdbt.tech/docs/dbt-ai/mcp-quickstart-oauth.md) и [Установка и настройка](https://docs.getdbt.tech/docs/dbt-ai/setup-local-mcp.md).

## Частые вопросы

Инструмент `execute_sql` на сервере dbt MCP позволяет вашему ИИ-ассистенту выполнять SQL-запросы в вашем хранилище данных. В этом разделе описано, как он работает и какие у него есть ограничения.

 Что делает execute\_sql?

`execute_sql` позволяет вашему ИИ-ассистенту выполнить SQL-запрос к вашему хранилищу данных и прочитать результаты. Он входит в набор инструментов SQL и работает на dbt platform, поэтому устанавливать dbt локально не нужно.

Вот что происходит, когда ассистент вызывает этот инструмент:

1. Ассистент составляет SQL-запрос и вызывает `execute_sql`.
2. Сервер dbt MCP передаёт запрос в dbt platform вместе с вашим токеном, ID среды разработки и ID пользователя.
3. dbt platform компилирует SQL (включая конструкции Jinja, например `ref()`) и выполняет его в вашем хранилище данных, используя ваши учётные данные для разработки.
4. Результаты возвращаются ассистенту в виде таблицы.

[![ИИ-ассистент вызывает execute\_sql. Сервер dbt MCP передаёт запрос в dbt platform, которая компилирует SQL, выполняет его в хранилище данных с вашими учётными данными для разработки и возвращает результаты ассистенту.](/img/docs/dbt-ai/mcp-execute-sql-flow.svg?v=2 "ИИ-ассистент вызывает execute_sql. Сервер dbt MCP передаёт запрос в dbt platform, которая компилирует SQL, выполняет его в хранилище данных с вашими учётными данными для разработки и возвращает результаты ассистенту.")](#)ИИ-ассистент вызывает execute\_sql. Сервер dbt MCP передаёт запрос в dbt platform, которая компилирует SQL, выполняет его в хранилище данных с вашими учётными данными для разработки и возвращает результаты ассистенту.

 execute\_sql — это то же самое, что dbt show?

Нет. `dbt show` выполняется через инструменты CLI dbt platform и позволяет предварительно просмотреть результат модели во время разработки. `execute_sql` отправляет SQL в dbt platform, которая выполняет его в вашем хранилище данных.

 Чьи учётные данные для хранилища данных использует execute\_sql?

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

Если подходящие учётные данные не настроены, запрос завершится ошибкой. Подробности настройки см. в разделе [Пользователи с доступом только для чтения и учётные данные хранилища данных](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md#read-only-users-and-warehouse-credentials).

 Работает ли execute\_sql только в режиме чтения?

Нет. `execute_sql` не блокирует операторы записи. Возможности запроса зависят от разрешений учётных данных хранилища, с которыми он выполняется. Если эти учётные данные позволяют создавать или удалять таблицы, ваш ассистент тоже сможет это делать.

Для безопасной работы:

* **Используйте роли хранилища данных с минимальными привилегиями.** Предоставьте учётным данным для разработки каждого пользователя доступ только для чтения к данным, аналогичным производственным, а доступ на запись — только к его собственной схеме разработки.
* **Не отключайте запросы подтверждения вызовов инструментов.** Тогда ассистент будет запрашивать разрешение перед выполнением SQL, и вы сможете сначала проверить запрос.
* **Не полагайтесь на отключение инструмента как на меру безопасности.** Вы можете отключить `execute_sql` с помощью заголовка `x-dbt-disable-tools`, но его задаёт тот, кто настраивает MCP-клиент, поэтому администраторы не могут принудительно обеспечить его использование. Надёжный механизм контроля — разрешения в хранилище данных.

 Кто может использовать execute\_sql?

Любой пользователь с лицензией разработчика или лицензией только для чтения, если он подключается через OAuth или с помощью [персонального токена доступа (PAT)](https://docs.getdbt.tech/docs/dbt-apis/user-tokens.md). Сервисные токены не подходят, поскольку учётные данные для разработки принадлежат конкретному пользователю.

Пользователи с лицензией только для чтения могут выполнять обычный SQL. Для SQL с конструкциями Jinja, такими как `ref()` или `source()`, нужна лицензия разработчика.

Подробности настройки см. в разделе [Настройка удалённого MCP](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md).

 Почему ref() не ссылается на мои таблицы разработки?

Хотя запрос выполняется с вашими учётными данными для разработки, `ref('model')` разрешается в объект производственной среды. Эта функция не может ссылаться на таблицу, которую вы создали в собственной схеме разработки.

Чтобы запросить данные из таблицы разработки, укажите её полное имя, например `my_dev_schema.my_model`. Также избегайте `source()` и используйте полные имена таблиц или `ref()`.

 Есть ли ограничения на объём запроса или время выполнения?

Да. Длительные запросы прерываются по тайм-ауту, а dbt ограничивает размер больших наборов результатов. Добавляйте фильтры и предложения `limit`, чтобы запросы оставались небольшими и выполнялись быстро.

 Можно ли просматривать результаты в виде диаграммы или таблицы?

Да! Ваш ИИ-инструмент может запросить отображение результатов в виде диаграммы или таблицы в интерфейсе. В противном случае результаты видит только ассистент.

 Когда стоит использовать что-то другое вместо execute\_sql?

| Если вы хотите...                                                  | Используйте                                                                                                                         |
| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| Задавать бизнес-вопросы на основе согласованных определений метрик | [Инструменты Semantic Layer](https://docs.getdbt.tech/docs/dbt-ai/mcp-available-tools.md#semantic-layer), например `query_metrics` |
| Предварительно просматривать результат модели во время разработки  | Инструменты CLI dbt platform, например `show`, `build` и `run`                                                                      |
| Преобразовать вопрос в SQL, не выполняя его                        | `text_to_sql`                                                                                                                       |

## Устранение неполадок

 Почему я могу подключиться к удалённому MCP, но вызов инструмента отклоняется?

Удалённый MCP проверяет разрешения для ресурса, к которому обращается каждый инструмент. Успешное подключение или наличие инструмента в списке не гарантирует доступ ко всем проектам, средам, заданиям или запускам.

1. Убедитесь, что запрашиваемый ресурс принадлежит аккаунту, к которому вы подключились.
2. Попросите администратора проверить [необходимые разрешения](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md#permissions) пользователя или сервисного токена для этого ресурса. PAT наследуют разрешения своего пользователя.
3. При использовании OAuth также проверьте области доступа и проекты, одобренные при предоставлении согласия. Если необходимый доступ не был включён, подключитесь заново и обновите своё согласие.
4. Для `execute_sql` даже обычный SQL требует наличия среды разработки и учётных данных хранилища. Для SQL с конструкциями dbt Jinja также нужны права на разработку; для перенаправления ссылок на производственную среду необходим доступ на чтение метаданных.

 Почему удалённый MCP отклоняет выбранный проект или среду?

Используйте положительные числовые ID, а не URL. Убедитесь, что заголовки среды разработки и производственной среды указывают на среды соответствующих типов и что эти среды принадлежат одному проекту. Аргументы инструмента должны соответствовать настроенной целевой среде, за исключением явно указанного `project_id` для `list_jobs`, который переопределяет настроенный фильтр по среде.

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

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

Не удаётся найти исполняемый файл uvx

**Симптомы:** В вашем MCP-клиенте появляются сообщения об ошибках, такие как `Could not connect to MCP server dbt-mcp`, `Error: spawn uvx ENOENT` или `spawn uvx ENOENT`.

**Причина:** Ваш MCP-клиент (например, настольное приложение Claude) не может найти `uvx` в переменной PATH, поскольку запускается с ограниченным набором переменных окружения.

**Решение:** Укажите полный путь к `uvx` в конфигурации.

1. Найдите полный путь:

   * macOS/Linux: Выполните `which uvx` в терминале.
   * Windows: Выполните `where uvx` в командной строке или PowerShell.

2. Замените `"command": "uvx"` на вариант с полным путём:

```json
{
  "mcpServers": {
    "dbt": {
      "command": "/full/path/to/uvx",
      "args": ["dbt-mcp"],
      "env": { }
    }
  }
}
```

Пример для macOS с Homebrew: `"command": "/opt/homebrew/bin/uvx"`

Для VS Code (`mcp.json`) применяется то же решение — замените `uvx` полным путём к нему в поле `command`.

Вход через OAuth не запускается

**Симптомы:** Окно браузера для входа через OAuth не открывается или процесс аутентификации зависает.

**Причина:** dbt MCP использует файл блокировки, чтобы избежать повторной аутентификации. Если после предыдущего сеанса остался файл блокировки, он может блокировать новые попытки аутентификации.

**Решение:**

1. Закройте клиент MCP (Claude Desktop, Cursor, VS Code и т. д.).

2. Удалите файлы конфигурации локально развернутого dbt MCP:

   * macOS/Linux: `rm -f ~/.dbt/mcp.yml ~/.dbt/mcp.lock`
   * Windows: `Remove-Item -Force $env:USERPROFILE\.dbt\mcp.yml, $env:USERPROFILE\.dbt\mcp.lock`

3. Перезапустите клиент и попробуйте подключиться снова.

Если эти действия не помогли устранить проблему, убедитесь, что для вашего аккаунта включены функции ИИ. Администратор аккаунта может включить их в разделе **Account settings** → **Edit** → включить переключатель **Enable account access to dbt Wizard features**. См. [Включение dbt Wizard](https://docs.getdbt.tech/docs/platform/manage-dbt-ai.md).

Сервер не запускается

**Симптомы:** MCP-сервер отображается в вашем клиенте как отключённый или недоступный.

**Диагностика:** Проверьте журналы сервера:

* **VS Code:** Откройте палитру команд (`Ctrl/Cmd + Shift + P`) → `MCP: List Servers` → нажмите на сервер dbt, чтобы просмотреть подробные журналы.
* **Claude Desktop:** Проверьте `~/Library/Logs/Claude` (macOS) или `%APPDATA%\Claude\logs` (Windows).
* **Все клиенты:** Задайте `DBT_MCP_LOG_LEVEL=DEBUG` в переменных окружения, чтобы получать более подробный вывод.

**Распространённые причины:**

* Отсутствующее или некорректное значение (Версии dbt: v1.11 и новее) `DBT_ENGINE_PROJECT_DIR` или `DBT_PATH` — убедитесь, что указанные пути существуют и являются абсолютными.
* Недействительные токены аутентификации или токены с истёкшим сроком действия — создайте новый токен и обновите конфигурацию.
* Отсутствие обязательных переменных окружения для набора инструментов, который вы пытаетесь использовать — см. [Требования инструментов](https://docs.getdbt.tech/docs/dbt-ai/setup-local-mcp.md#tool-requirements-at-a-glance).

Конфигурация не работает в WSL (VS Code)

**Симптомы:** Конфигурация MCP в VS Code работает на других компьютерах или непосредственно в Windows, но не в WSL.

**Причина:** Локальные пользовательские настройки не применяются в средах WSL.

**Решение:**

Настройте MCP в параметрах для WSL, а не в локальных пользовательских настройках:

1. Откройте палитру команд → **Preferences: Open Remote Settings**.
2. Или выберите вкладку **Remote** в редакторе настроек.
3. Добавьте туда конфигурацию вашего MCP-сервера.

Инструмент execute\_sql не работает

**Симптомы:** Инструмент `execute_sql` возвращает ошибку аутентификации или недоступен.

**Причина:** Способ устранения проблемы зависит от того, как вы подключились:

* **Удалённый MCP с OAuth:** Войдите в систему через свой MCP-клиент, когда появится соответствующий запрос. Персональный токен доступа не требуется.
* **Удалённый MCP с аутентификацией по токену:** Вам нужен [персональный токен доступа (PAT)](https://docs.getdbt.tech/docs/dbt-apis/user-tokens.md). Сервисные токены не подойдут. Также необходимы заголовки `x-dbt-dev-environment-id` и `x-dbt-user-id`. Идентификатор пользователя должен соответствовать пользователю, создавшему PAT.
* **Локальный MCP:** Задайте для `DBT_TOKEN` значение персонального токена доступа (PAT). Сервисные токены не подойдут.

**Решение:**

1. Если вы используете OAuth для удалённого MCP, убедитесь, что вы выполнили вход и предоставили согласие в своём MCP-клиенте.
2. Если вы используете аутентификацию по токену или локальный MCP, создайте [персональный токен доступа (PAT)](https://docs.getdbt.tech/docs/dbt-apis/user-tokens.md) в разделе **Account settings** → **API tokens** → **Personal tokens**.
3. Для удалённого MCP с аутентификацией по токену добавьте PAT в заголовок `Authorization` в виде `Token YOUR_PAT`. Для локального MCP задайте PAT в качестве значения `DBT_TOKEN`.
4. Также убедитесь, что заданы `DBT_DEV_ENV_ID` и `DBT_USER_ID` (для локального MCP) или заголовки `x-dbt-dev-environment-id` и `x-dbt-user-id` (для удалённого MCP). Подробности см. в разделе [Поиск идентификаторов](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md).

Набор инструментов недоступен или отображается как отключённый

**Симптомы:** Набор инструментов (Semantic Layer, Discovery, Admin API) недоступен в вашем ИИ-клиенте, хотя учётные данные настроены.

**Причина:** Отсутствуют обязательные переменные либо набор инструментов явно отключён.

**Решение:**

1. Проверьте, что все обязательные переменные для набора инструментов заданы — см. [Требования к инструментам](https://docs.getdbt.tech/docs/dbt-ai/setup-local-mcp.md#tool-requirements-at-a-glance).
2. Проверьте, нет ли у вас переменных `DISABLE_*` со значением `true`, которые могут отключать набор инструментов.
3. Если вы используете режим явного включения (`DBT_MCP_ENABLE_*`), убедитесь, что нужный набор инструментов указан среди включённых.
4. Задайте `DBT_MCP_LOG_LEVEL=DEBUG`, чтобы увидеть, какие наборы инструментов активны при запуске.

Вставка полных URL вместо идентификаторов

**Симптомы:** Ошибки аутентификации, непредвиденное поведение или невозможность подключения сервера к нужной среде.

**Причина:** Переменные среды, такие как `DBT_PROD_ENV_ID`, `DBT_USER_ID` и `DBT_ACCOUNT_ID`, принимают целые числа, а не полные URL из браузера.

**Решение:**

```bash
# ✅ Правильно
DBT_HOST=cloud.getdbt.com            # https://cloud.getdbt.com тоже работает
DBT_PROD_ENV_ID=54321
DBT_USER_ID=123

# ❌ Неправильно — идентификаторы должны быть числами, а не полными URL
DBT_PROD_ENV_ID=https://cloud.getdbt.com/deploy/12345/projects/67890/environments/54321
DBT_USER_ID=https://cloud.getdbt.com/settings/profile
```

Пошаговые инструкции приведены в разделе [Как найти свои идентификаторы](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md).

Проблемы с подключением к аккаунту в multi-cell или со статическим поддоменом

**Симптомы:** Ошибки подключения, когда URL вашего аккаунта содержит префикс (например, `abc123.us1.dbt.com`).

**Решение (начиная с v1.14.0):** Задайте для `DBT_HOST` полное имя хоста, включая префикс. Если вы используете аутентификацию на основе PAT, также задайте `DBT_ACCOUNT_ID`.

```bash
# ✅ Правильно
DBT_HOST=abc123.us1.dbt.com
DBT_ACCOUNT_ID=12345  # требуется для аутентификации на основе PAT
```

Больше не нужно задавать `MULTICELL_ACCOUNT_PREFIX` или `DBT_HOST_PREFIX`. Если эти переменные заданы в вашей старой конфигурации, удалите их.

Ошибки Claude Desktop

Claude Desktop может возвращать такие ошибки, как `Error: spawn uvx ENOENT`, `Error: spawn npx ENOENT`, `Could not connect to MCP server dbt-mcp` или `Server disconnected`. Для установок на собственной инфраструктуре замените значение `command` полным путём к `uvx`: выполните `which uvx` в Unix-системах или `where uvx` в Windows и вставьте полный путь в JSON (например, `"command": "/the/full/path/to/uvx"`). Для удалённых подключений через `mcp-remote` с аутентификацией по токену аналогичным образом укажите полный путь к `npx`.

Если Claude сообщает, что записи в `claude_desktop_config.json` недопустимы и были пропущены, убедитесь, что в этом файле не используется `"type": "http"`. Вместо этого используйте [конфигурацию `mcp-remote` с аутентификацией по токену](https://docs.getdbt.tech/docs/dbt-ai/integrate-mcp-claude.md#desktop-remote).

Для удалённых подключений ещё раз проверьте, что URL-адрес MCP заканчивается на `/api/ai/v1/mcp/` (включая завершающий слеш), а значение заголовка `Authorization` — `Token YOUR_DBT_ACCESS_TOKEN` или `Bearer YOUR_DBT_ACCESS_TOKEN`.

Логи находятся в `~/Library/Logs/Claude` (macOS) или `%APPDATA%\Claude\logs` (Windows).

Claude Code не может подключиться к серверу dbt MCP

Если подключение к серверу dbt MCP не устанавливается, убедитесь, что файл `.mcp.json` находится в *корне проекта*, а блок `dbt` соответствует одному из примеров на [странице настройки Claude](https://docs.getdbt.tech/docs/dbt-ai/integrate-mcp-claude.md#claude-code). Для самостоятельно размещённых установок аналогичным образом укажите полный путь к `uvx` (а также полные пути в `--env-file`). При удалённом подключении проверьте URL и заголовки, а затем для сравнения попробуйте эквивалентную команду `claude mcp add --transport http`.

Коннектор не проходит авторизацию или процесс OAuth завершается с ошибкой

* Убедитесь, что у вашей учетной записи есть [статический поддомен](https://docs.getdbt.tech/docs/platform/about-platform/access-regions-ip-addresses.md). Он необходим для OAuth с MCP.
* Убедитесь, что хост в `API_ALLOWED_PREFIXES`, `OAUTH_TOKEN_ENDPOINT`, `OAUTH_AUTHORIZATION_ENDPOINT` и `OAUTH_RESOURCE_URL` в точности совпадает с хостом вашего URL MCP, а для интеграции задано `ENABLED = TRUE`.
* Функции ИИ включены по умолчанию, и администраторы могут [отключить или снова включить их в любое время](https://docs.getdbt.tech/docs/platform/manage-dbt-ai.md).
* Убедитесь, что OAuth для удаленного MCP доступен в тарифном плане вашей учетной записи.

Агент не возвращает метрики или возвращает пустые результаты

* Убедитесь, что в проекте, к которому вы предоставили доступ, настроен [Semantic Layer](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/dbt-sl.md) с метриками и измерениями.
* Проверьте, что у подключившегося пользователя есть как минимум доступ на чтение к этому проекту — агент видит только то, что доступно пользователю.
* Если вы ограничили OAuth-подключение одним проектом, убедитесь, что именно в этом проекте находятся ваши метрики.

Ошибки прав доступа при создании интеграции или MCP-сервера

Для выполнения `CREATE API INTEGRATION` и `CREATE EXTERNAL MCP SERVER` требуется роль `ACCOUNTADMIN` (или роль с привилегией `CREATE INTEGRATION` на уровне аккаунта). Выполните шаги 1–2 с ролью `ACCOUNTADMIN`, затем предоставьте привилегию `USAGE` на MCP-сервер и интеграцию роли, от имени которой запускается агент (шаг 3).