Подключение из Claude Code, Cursor, VS Code и других клиентов

AI-клиенты для разработчиков (Claude Code, Cursor, VS Code с GitHub Copilot и другие) подключаются к MCP-серверу BLACKBOX командой или через файл настроек, в котором указываются адрес сервера и ваш API-токен. Токен создаётся на странице «Токены доступа (API)» (blackbox.md/ru/account/api-tokens, «Личный кабинет» → «API-токены»). Пример настройки также опубликован на blackbox.md/ru/info/mcp, в блоке «Пример конфигурации».

Доступно: любому клиенту, вошедшему на blackbox.md и создавшему API-токен. Создание токена бесплатное.

Параметры подключения

Они одинаковы для всех клиентов, различается только формат записи.

Между Bearer и токеном ставится ровно один пробел. Токен показывается один раз — при создании, в карточке «Ваш новый токен». Под ним блок «Подключение AI-клиента» повторяет «URL сервера» и «Заголовок авторизации» с уже подставленным токеном. Как создавать и отзывать токены: API-токены: создание, копирование и отзыв.

Что сможет делать ассистент, зависит от разрешений токена: Разрешения токенов (scopes). Создавайте отдельный токен для каждого клиента и устройства с понятным названием, например «Claude Code (ноутбук)»: так его можно отозвать, не затрагивая остальные.

Альтернативные заголовки (x-api-key и другие) нужны для приложения Claude, где Authorization заполнить нельзя: Подключение в приложении Claude (пользовательский коннектор). В клиентах из этой статьи используйте Authorization: Bearer.

Безопасность Не записывайте токен в файлы, которые попадают в git: .mcp.json, .cursor/mcp.json или .vscode/mcp.json в проекте. В них используйте переменную окружения или поле ввода пароля самого клиента, как в примерах ниже. Если токен всё же оказался в репозитории, сразу отзовите его и создайте новый.

Claude Code

1. Создайте токен и скопируйте его.

2. Добавьте сервер в терминале, заменив bbx_pat_… своим токеном:

   claude mcp add --transport http --scope user blackbox https://api.app.blackbox.md/mcp --header "Authorization: Bearer bbx_pat_…"

3. Проверьте подключение. Сервер blackbox должен отображаться как подключённый:

   claude mcp list

4. В сессии Claude Code состояние сервера и его инструменты показывает команда:

   /mcp

Параметр --scope (коротко -s) определяет, где сохраняется сервер:

При user и local токен остаётся в вашем личном файле настроек, вне проекта.

Для проекта (.mcp.json)

Файл .mcp.json обычно добавляют в git, поэтому токен в него не пишут. Используйте переменную окружения BBX_PAT:

1. Создайте в корне проекта файл .mcp.json:

   {
     "mcpServers": {
       "blackbox": {
         "type": "http",
         "url": "https://api.app.blackbox.md/mcp",
         "headers": {
           "Authorization": "Bearer ${BBX_PAT}"
         }
       }
     }
   }

   Такую же запись создаёт и команда ниже. Одинарные кавычки сохраняют текст ${BBX_PAT} без изменений в bash, zsh и PowerShell:

   claude mcp add --transport http --scope project blackbox https://api.app.blackbox.md/mcp --header 'Authorization: Bearer ${BBX_PAT}'

2. Задайте переменную на каждом компьютере, где вы работаете с проектом. В macOS и Linux добавьте строку в ~/.bashrc или ~/.zshrc и откройте новый терминал:

   export BBX_PAT="bbx_pat_…"

   В Windows выполните команду в PowerShell и откройте новое окно:

   setx BBX_PAT "bbx_pat_…"

3. Запустите Claude Code в проекте. При первом использовании он попросит одобрить серверы из .mcp.json — одобрите blackbox. Если переменная BBX_PAT не задана, Claude Code не сможет прочитать настройки.

Cursor

Cursor берёт MCP-серверы из двух файлов:

1. Откройте или создайте глобальный файл ~/.cursor/mcp.json. Его можно открыть и из «Cursor Settings», в разделе, посвящённом MCP.

2. Добавьте настройку (это пример со страницы blackbox.md/ru/info/mcp):

   {
     "mcpServers": {
       "blackbox": {
         "url": "https://api.app.blackbox.md/mcp",
         "headers": {
           "Authorization": "Bearer bbx_pat_…"
         }
       }
     }
   }

   Если в файле уже есть другие серверы, добавьте только блок "blackbox" внутрь "mcpServers".

3. Сохраните файл. Если сервер не появился, перезапустите Cursor.

4. В разделе MCP в «Cursor Settings» сервер blackbox должен быть включён и показывать свои инструменты. Инструментами пользуется чат в режиме «Agent».

Для проекта (.cursor/mcp.json)

В файл проекта токен не записывайте. Cursor подставляет вместо ${env:BBX_PAT} значение переменной окружения BBX_PAT:

{
  "mcpServers": {
    "blackbox": {
      "url": "https://api.app.blackbox.md/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BBX_PAT}"
      }
    }
  }
}

Задайте переменную так же, как для Claude Code (раздел выше), и перезапустите Cursor, чтобы он её увидел.

VS Code (GitHub Copilot, режим агента)

У VS Code свой формат: ключ servers (а не mcpServers), тип http и список inputs. Через inputs VS Code запрашивает токен при первом запуске и хранит его отдельно, в своём защищённом хранилище, а не в файле.

1. Создайте в проекте файл .vscode/mcp.json:

   {
     "servers": {
       "blackbox": {
         "type": "http",
         "url": "https://api.app.blackbox.md/mcp",
         "headers": {
           "Authorization": "Bearer ${input:bbx-token}"
         }
       }
     },
     "inputs": [
       {
         "type": "promptString",
         "id": "bbx-token",
         "description": "API-токен BLACKBOX",
         "password": true
       }
     ]
   }

2. Запустите сервер: нажмите «Start» над записью blackbox в файле или выполните команду «MCP: List Servers» из палитры команд (Ctrl+Shift+P, в macOS Cmd+Shift+P).

3. Введите токен в появившемся поле — символы не отображаются. Если VS Code спросит, доверяете ли вы серверу, подтвердите.

4. Откройте чат, выберите режим «Agent» и убедитесь, что в списке инструментов появились инструменты blackbox.

Токена в файле нет, поэтому файл можно добавить в git. Чтобы сервер был доступен во всех проектах, поместите ту же настройку в пользовательский файл — он открывается командой «MCP: Open User Configuration».

Другие клиенты (Windsurf, Gemini CLI и другие)

Подойдёт любой клиент, который поддерживает удалённые MCP-серверы по HTTP (Streamable HTTP) с собственными заголовками. Используйте параметры из таблицы в начале статьи; от клиента к клиенту меняются только имена ключей, например:

Клиенты, которые поддерживают только локальные серверы (stdio) или только вход через OAuth, напрямую подключиться не смогут: BLACKBOX использует не OAuth, а токен в заголовке. Для собственных скриптов и приложений: Использование MCP из кода (AI API и HTTP).

Примечание Интерфейсы и форматы клиентов меняются от версии к версии. Если ключ или пункт меню отличаются от описанных здесь, следуйте документации клиента. Неизменными остаются URL, транспорт HTTP и заголовок Authorization: Bearer.

Проверьте подключение через whoami

После подключения напишите ассистенту:

Вызови инструмент whoami сервера blackbox и покажи разрешения токена.

Инструмент whoami не требует разрешений и ничего не меняет. В ответе:

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

Важно Сервер BLACKBOX помечает инструменты, которые что-то меняют (перезагрузка, команды от root, платежи), но подтверждение перед выполнением запрашивает клиент, а не сервер. Пока у токена есть разрешения на запись, не включайте автоматическое одобрение всех инструментов (варианты вроде «always allow» или режимы, в которых инструменты запускаются без вопросов). Подробнее: Безопасность токенов и AI-агентов.

Если подключение не работает

Проверьте токен без клиента

Команда ниже покажет ответ сервера на ваш токен. В Windows в PowerShell пишите curl.exe вместо curl.

curl -i https://api.app.blackbox.md/mcp -H "Authorization: Bearer bbx_pat_…"

Если токен действителен, придёт ответ 406 Not Acceptable. Для этой проверки это нормально и означает, что ошибка в настройках клиента. Если токен не принят, придёт 401 с причиной в поле error_description.

Ответы и причины

Полный список ошибок и лимитов: Лимиты и коды ошибок MCP.

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

После смены пароля аккаунта подключение перестало работать. Почему? Смена пароля аккаунта blackbox.md отключает все токены, созданные до неё. Создайте новый токен и замените его в настройках; если вы используете переменную BBX_PAT, достаточно поменять её значение. В Claude Code удалите сервер и добавьте его заново с новым токеном:

claude mcp remove blackbox

В VS Code измените id в inputs и в ${input:…} (например, на bbx-token-2) — при запуске VS Code запросит новый токен.

Можно ли подключиться через файл настроек Claude Desktop? Файл настроек Claude Desktop предназначен для локальных серверов. В приложении Claude подключите BLACKBOX как коннектор: Подключение в приложении Claude (пользовательский коннектор).

Есть ли REST API, с которым работает токен? Нет. Токен работает только по адресу https://api.app.blackbox.md/mcp, по протоколу MCP.