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

Здесь вы найдёте ответы на частые вопросы о сервере dbt Model Context Protocol (MCP) и способы устранения распространённых проблем с настройкой. Инструкции для конкретных клиентов см. в разделах об устранении неполадок на страницах Начало работы и Установка и настройка.

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

Инструмент 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, выполняет его в хранилище данных с вашими учётными данными для разработки и возвращает результаты ассистенту.

 execute_sql — это то же самое, что dbt show?

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

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

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

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

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

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

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

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

 Кто может использовать execute_sql?

Любой пользователь с лицензией разработчика или лицензией только для чтения, если он подключается через OAuth или с помощью персонального токена доступа (PAT). Сервисные токены не подходят, поскольку учётные данные для разработки принадлежат конкретному пользователю.

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

Подробности настройки см. в разделе Настройка удалённого MCP.

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

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

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

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

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

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

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

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

Если вы хотите...	Используйте
Задавать бизнес-вопросы на основе согласованных определений метрик	Инструменты Semantic Layer, например query_metrics
Предварительно просматривать результат модели во время разработки	Инструменты CLI dbt platform, например show, build и run
Преобразовать вопрос в SQL, не выполняя его	text_to_sql

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

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

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

1. Убедитесь, что запрашиваемый ресурс принадлежит аккаунту, к которому вы подключились.
2. Попросите администратора проверить необходимые разрешения пользователя или сервисного токена для этого ресурса. 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" на вариант с полным путём:

{
  "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.

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

Симптомы: 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 — убедитесь, что указанные пути существуют и являются абсолютными.
• Недействительные токены аутентификации или токены с истёкшим сроком действия — создайте новый токен и обновите конфигурацию.
• Отсутствие обязательных переменных окружения для набора инструментов, который вы пытаетесь использовать — см. Требования инструментов.

Конфигурация не работает в 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). Сервисные токены не подойдут. Также необходимы заголовки x-dbt-dev-environment-id и x-dbt-user-id. Идентификатор пользователя должен соответствовать пользователю, создавшему PAT.
• Локальный MCP: Задайте для DBT_TOKEN значение персонального токена доступа (PAT). Сервисные токены не подойдут.

Решение:

1. Если вы используете OAuth для удалённого MCP, убедитесь, что вы выполнили вход и предоставили согласие в своём MCP-клиенте.
2. Если вы используете аутентификацию по токену или локальный MCP, создайте персональный токен доступа (PAT) в разделе 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). Подробности см. в разделе Поиск идентификаторов.

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

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

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

Решение:

1. Проверьте, что все обязательные переменные для набора инструментов заданы — см. Требования к инструментам.
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 из браузера.

Решение:

# ✅ Правильно
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

Сообщить об ошибке в коде

Пошаговые инструкции приведены в разделе Как найти свои идентификаторы.

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

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

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

# ✅ Правильно
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 с аутентификацией по токену.

Для удалённых подключений ещё раз проверьте, что 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. Для самостоятельно размещённых установок аналогичным образом укажите полный путь к uvx (а также полные пути в --env-file). При удалённом подключении проверьте URL и заголовки, а затем для сравнения попробуйте эквивалентную команду claude mcp add --transport http.

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

• Убедитесь, что у вашей учетной записи есть статический поддомен. Он необходим для OAuth с MCP.
• Убедитесь, что хост в API_ALLOWED_PREFIXES, OAUTH_TOKEN_ENDPOINT, OAUTH_AUTHORIZATION_ENDPOINT и OAUTH_RESOURCE_URL в точности совпадает с хостом вашего URL MCP, а для интеграции задано ENABLED = TRUE.
• Функции ИИ включены по умолчанию, и администраторы могут отключить или снова включить их в любое время.
• Убедитесь, что OAuth для удаленного MCP доступен в тарифном плане вашей учетной записи.

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

• Убедитесь, что в проекте, к которому вы предоставили доступ, настроен Semantic Layer с метриками и измерениями.
• Проверьте, что у подключившегося пользователя есть как минимум доступ на чтение к этому проекту — агент видит только то, что доступно пользователю.
• Если вы ограничили OAuth-подключение одним проектом, убедитесь, что именно в этом проекте находятся ваши метрики.

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

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

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

Создать GitHub Issue