Интеграция VS Code с MCP

Microsoft Visual Studio Code (VS Code) — это мощная и популярная интегрированная среда разработки (IDE).

VS Code может подключаться как к самостоятельно размещённому серверу dbt MCP (работает на вашем компьютере, поддерживает команды CLI, такие как dbt run), так и к удалённому серверу dbt MCP (работает по HTTP, не требует установки, ориентирован на потребление данных). Перед началом убедитесь, что у вас есть:

• VS Code с установленными последними обновлениями.
• Для самостоятельно размещённого MCP: выполнена настройка самостоятельно размещённого MCP и настроены пути к вашему проекту dbt.
• Для удалённого MCP: ваш MCP URL из раздела Account settings → Access URLs → MCP Endpoint URL в dbt platform.

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

Настройка подключения к самостоятельно размещённому серверу dbt MCP

Чтобы начать, в VS Code:

1. Откройте меню Settings и выберите соответствующую вкладку в верхней части страницы в зависимости от вашего сценария:

   • Workspace: настраивает сервер в контексте текущего workspace
   • User: настраивает сервер в контексте пользователя
   
   

   Примечание для пользователей WSL: если вы используете VS Code с Windows Subsystem for Linux (WSL), необходимо настраивать параметры, специфичные для WSL. Выполните команду Preferences: Open Remote Settings из Command Palette (F1) или выберите вкладку Remote в редакторе Settings. Локальные пользовательские настройки используются и в WSL, но могут быть переопределены настройками для WSL. Настройка MCP-серверов в локальных пользовательских настройках не будет корректно работать в среде WSL.

2. Выберите Features --> Chat

3. Убедитесь, что MCP Enabled

mcp-vscode-settings

4. Откройте палитру команд Control/Command + Shift + P и выберите один из вариантов:

   • MCP: Open Workspace Folder MCP Configuration — если вы хотите установить MCP-сервер для данного workspace
   • MCP: Open User Configuration — если вы хотите установить MCP-сервер для пользователя

5. Добавьте конфигурацию сервера (dbt) в предоставленный файл mcp.json как один из серверов:

подсказка

Вам не нужно клонировать репозиторий dbt-mcp. Установите uv и выполните uvx dbt-mcp (или используйте конфигурацию ниже); клонирование требуется только для участия в разработке.

 Самостоятельно размещаемый MCP с OAuth платформы dbt

Самостоятельно размещаемый MCP с OAuth предназначен для пользователей, которым нужны возможности dbt platform.

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

Выберите конфигурацию в зависимости от вашего сценария использования:

dbt platform only

Этот вариант предназначен для пользователей, которым нужны только функции платформы dbt (Discovery API, Semantic Layer, управление заданиями) без самостоятельно размещаемых команд dbt platform CLI.

Если вы используете только dbt platform, инструменты CLI автоматически отключаются. Значение поля DBT_HOST можно найти в информации о вашей учетной записи dbt platform в разделе Access URLs.

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "YOUR-ACCESS-URL"
      }
    }
  }
}

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

Примечание: Замените YOUR-ACCESS-URL на имя хоста из вашего Access URL (например, abc123.us1.dbt.com). Допускаются оба варианта: abc123.us1.dbt.com и https://abc123.us1.dbt.com. Это позволяет использовать аутентификацию OAuth без необходимости самостоятельно размещать dbt.

dbt platform + CLI

Этот вариант предназначен для пользователей, которым нужны как команды dbt platform CLI, так и возможности платформы dbt (Discovery API, Semantic Layer, управление заданиями).

Для доступа к CLI обязательны поля DBT_PROJECT_DIR и DBT_PATH. Значение поля DBT_HOST можно найти в информации о вашей учетной записи dbt platform в разделе Access URLs.

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "YOUR-ACCESS-URL",
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/path/to/dbt/executable"
      }
    }
  }
}

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

Примечание: Замените YOUR-ACCESS-URL именем хоста из вашего Access URL (например, abc123.us1.dbt.com). Допускаются оба варианта: abc123.us1.dbt.com и https://abc123.us1.dbt.com. Это позволяет использовать аутентификацию OAuth.

 MCP с самостоятельным размещением (только CLI)

Для пользователей, которым нужно только выполнять команды dbt с dbt v1 или dbt v2

(Версии dbt: v1.11 и новее)

{
  "servers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_ENGINE_PROJECT_DIR": "/path/to/your/dbt/project",
        "DBT_PATH": "/path/to/your/dbt/executable"
      }
    }
  }
}

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

Как определить пути:

• (Версии dbt: v1.11 и новее) DBT_ENGINE_PROJECT_DIR: Полный путь к папке, содержащей файл dbt_project.yml
  • macOS/Linux: Выполните pwd из папки проекта.
  • Windows: Выполните cd из папки проекта в командной строке.
• DBT_PATH: Путь к исполняемому файлу dbt
  • macOS/Linux: Выполните which dbt.
  • Windows: Выполните where dbt.

 Самостоятельно размещённый MCP с .env

Для опытных пользователей, которым нужны пользовательские переменные окружения или аутентификация с помощью сервисного токена. Поместите файл .env в корневую папку проекта dbt (ту же папку, где находится dbt_project.yml) и укажите абсолютный путь с помощью --env-file. Полный список доступных переменных окружения для самостоятельно размещённого MCP-сервера приведён в справочнике переменных окружения.

Использование поля env (конфигурация в одном файле):

Идентификаторы — это целые числа, а не URL-адреса

DBT_PROD_ENV_ID, DBT_DEV_ENV_ID и DBT_USER_ID должны быть числовыми идентификаторами (например, 54321), а не полными URL-адресами, скопированными из браузера. DBT_HOST принимает как cloud.getdbt.com, так и https://cloud.getdbt.com.

(Версии dbt: v1.11 и новее)

{
  "servers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_ENGINE_HOST": "cloud.getdbt.com",
        "DBT_TOKEN": "your-token-here",
        "DBT_PROD_ENV_ID": "12345",
        "DBT_ENGINE_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/path/to/dbt"
      }
    }
  }
}

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

С использованием файла .env (альтернативный вариант — конфигурация из двух файлов):

{
  "servers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "--env-file",
        "/absolute/path/to/your-dbt-project/.env",
        "dbt-mcp"
      ]
    }
  }
}

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

6. Вы можете запускать, останавливать и настраивать MCP-серверы следующими способами:
   • Выполняя команду MCP: List Servers из Command Palette (Control/Command + Shift + P) и выбирая нужный сервер.
   • Используя ключевые слова inline непосредственно в файле mcp.json.

VS Code inline management

Теперь вы можете получать доступ к серверу dbt MCP в VS Code через такие интерфейсы, как GitHub Copilot.

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

Удалённый сервер dbt MCP работает в dbt platform — uvx и самостоятельная установка не требуются. VS Code подключается к нему по HTTP с помощью того же файла mcp.json, который используется для серверов, размещённых самостоятельно.

к сведению

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

1. Откройте палитру команд (Control/Command + Shift + P) и выберите один из вариантов:

   • MCP: Open Workspace Folder MCP Configuration — для этой рабочей области.
   • MCP: Open User Configuration — для вашего пользователя.

2. Получите 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-адреса.

3. Добавьте запись dbt в ключ верхнего уровня servers. (VS Code использует servers, а не mcpServers.) Выберите вкладку, соответствующую вашему способу аутентификации:

   OAuth (удалённый сервер)

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

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

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

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

   Добавьте следующий код в mcp.json. При первом подключении к серверу VS Code откроет браузер для входа и предоставления согласия.

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

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

   Замените YOUR_DBT_HOST_URL на имя вашего хоста (например, abc123.us1.dbt.com). URL-адрес можно найти в dbt platform в разделе Account settings → Access URLs → MCP Endpoint URL.

   На основе токена

   Используйте аутентификацию на основе токена, если ваш клиент ещё не поддерживает OAuth для HTTP-серверов MCP или если вам нужна общая конфигурация либо конфигурация для CI.

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

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

   Для удалённого MCP с аутентификацией по токену задайте следующие заголовки в конфигурации MCP вашего клиента:

   • Authorization (обязательный) — Token YOUR_DBT_ACCESS_TOKEN или Bearer YOUR_DBT_ACCESS_TOKEN. Используйте персональный токен доступа (PAT) или сервисный токен с правами Developer для проекта, которому принадлежит среда, указанная в x-dbt-prod-environment-id. Назначьте сервисным токенам набор разрешений Developer. PAT наследуют разрешения своих создателей. Без прав Developer подключение завершается ошибкой 401.
   • x-dbt-prod-environment-id (обязательный) — идентификатор вашей производственной среды dbt platform. Пошаговые инструкции см. в разделе Как найти идентификаторы dbt MCP.
   • x-dbt-dev-environment-id — обязателен для execute_sql и инструментов dbt v2. Пошаговые инструкции см. в разделе Как найти идентификаторы dbt MCP.
   • x-dbt-user-id — обязателен для execute_sql. Подробности см. в разделе Где найти мой идентификатор пользователя?.

   Используйте числовые идентификаторы, а не полные URL-адреса

   В заголовках x-dbt-prod-environment-id, x-dbt-dev-environment-id и x-dbt-user-id ожидаются числовые идентификаторы (например, 54321), а не полные URL-адреса, скопированные из браузера. URL-адрес хоста MCP должен содержать https:// независимо от того, задаёте ли вы его в поле url или передаёте как аргумент mcp-remote.

   При аутентификации по токену для execute_sql требуется персональный токен доступа (PAT). Сервисные токены не подойдут. Чтобы выполнять SQL без создания PAT, используйте подключение через OAuth (удалённый MCP). Полный список заголовков см. в разделе Настройка удалённого MCP.

4. Сохраните файл. Выполните команду MCP: List Servers из палитры команд, чтобы запустить сервер, а затем задайте в Copilot Chat вопрос о данных, чтобы проверить подключение.

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

В этом разделе приведены шаги по устранению ошибок, с которыми вы можете столкнуться при интеграции VS Code с MCP.

Не удаётся найти исполняемый файл 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.

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

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

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

Решение:

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

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

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

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

Ресурсы

• Документация Microsoft VS Code MCP

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

Создать GitHub Issue