Использование MCP из кода (AI API и HTTP)

MCP-сервером BLACKBOX (https://api.app.blackbox.md/mcp) можно пользоваться не только из приложений вроде Claude или Cursor, но и из собственных скриптов и агентов. Подключение к серверу можно поручить API AI-провайдера (Anthropic или OpenAI) или отправлять JSON-RPC-запросы по HTTP самостоятельно. Проверить соединение поможет MCP Inspector. Токен создаётся на blackbox.md: «Личный кабинет» → «API-токены» (страница «Токены доступа (API)», blackbox.md/account/api-tokens).

Доступно: владельцу аккаунта blackbox.md, у которого есть API-токен (bbx_pat_…). Что сможет делать код, зависит от разрешений токена.

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

REST API для клиентов нет: токен работает только на /mcp, остальные адреса API его не принимают. Всё, что может делать код (серверы, SSH-ключи, баланс, заказы), доступно через инструменты MCP: Список инструментов MCP.

Храните токен в переменной окружения, а не в коде. В примерах ниже используется переменная BBX_PAT. В bash (Linux, macOS, WSL):

export BBX_PAT="bbx_pat_…"

В PowerShell:

$env:BBX_PAT = "bbx_pat_…"

Важно Когда инструменты вызывает API AI-провайдера, подтверждения перед каждым вызовом никто не спрашивает. Исключение — OpenAI с "require_approval": "always". Для таких скриптов используйте токен только для чтения (три разрешения, отмеченные по умолчанию при создании) или ограничьте список инструментов, как в примерах ниже. Токен и всё, что возвращают инструменты, включая пароли, ключи и вывод команд, проходит через AI-провайдера. Подробнее: Разрешения токенов (scopes).

Anthropic Messages API (MCP-коннектор)

API Anthropic самостоятельно подключается к серверу BLACKBOX и вызывает инструменты за вас. В запросе передаются две вещи:

• в mcp_servers — запись с "type": "url", url, "name": "blackbox" и authorization_token, равным вашему токену;
• в tools — запись типа mcp_toolset с "mcp_server_name": "blackbox".

Функция находится в бета-версии и требует заголовка anthropic-beta. На 9 октября 2026 года его значение — mcp-client-2025-11-20; актуальное значение проверьте в документации Anthropic.

Пример на Python (SDK anthropic), в котором включены только три инструмента для чтения:

import os
import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{
        "type": "url",
        "url": "https://api.app.blackbox.md/mcp",
        "name": "blackbox",
        "authorization_token": os.environ["BBX_PAT"],
    }],
    tools=[{
        "type": "mcp_toolset",
        "mcp_server_name": "blackbox",
        "default_config": {"enabled": False},
        "configs": {
            "whoami": {"enabled": True},
            "list_servers": {"enabled": True},
            "get_server": {"enabled": True},
        },
    }],
    messages=[{"role": "user", "content": "Покажи мои серверы BLACKBOX и их статус"}],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

• "default_config": {"enabled": False} отключает все инструменты, а configs включает только перечисленные. Без этих двух полей модель получит все инструменты, которые разрешает токен.
• Кроме текста, в ответе есть блоки mcp_tool_use (какой инструмент вызвала модель и с какими параметрами) и mcp_tool_result (что ответил сервер BLACKBOX).
• Название модели — только пример; укажите нужную вам модель.

OpenAI Responses API

В Responses API сервер BLACKBOX добавляется как инструмент типа mcp: "server_label": "blackbox", server_url, токен в headers.Authorization и "require_approval": "always", чтобы каждый вызов инструмента ждал вашего одобрения.

import os
from openai import OpenAI

client = OpenAI()

blackbox = {
    "type": "mcp",
    "server_label": "blackbox",
    "server_url": "https://api.app.blackbox.md/mcp",
    "headers": {"Authorization": "Bearer " + os.environ["BBX_PAT"]},
    "require_approval": "always",
}

response = client.responses.create(
    model="gpt-5",
    tools=[blackbox],
    input="Покажи мои серверы BLACKBOX и их статус",
)

Как одобрить вызов:

1. Найдите в response.output элементы типа mcp_approval_request. В каждом есть имя инструмента (name) и параметры (arguments).

2. Проверьте вызов.

3. Отправьте новый запрос с previous_response_id=response.id, тем же списком tools и вашим ответом в input:

   {"type": "mcp_approval_response", "approve": true, "approval_request_id": "mcpr_…"}

4. Чтобы отклонить вызов, передайте "approve": false.

В каждом запросе заново передавайте описание инструмента вместе с заголовком Authorization: OpenAI не сохраняет его между запросами. Параметр allowed_tools (например, ["whoami", "list_servers", "get_server"]) ограничивает набор инструментов, которые видит модель. Подробнее — в документации OpenAI.

Напрямую по HTTP (JSON-RPC)

Без SDK отправляйте POST-запросы в формате JSON-RPC 2.0 на тот же адрес со следующими заголовками:

Примеры написаны для bash (Linux, macOS); в Windows запускайте их в WSL.

1. Откройте сессию запросом initialize:

   curl -i https://api.app.blackbox.md/mcp \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -H "Authorization: Bearer $BBX_PAT" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"script","version":"1.0"}}}'

2. Ответ приходит со статусом 200 и заголовком mcp-session-id. Тело — поток событий; результат JSON-RPC находится в строке, которая начинается с data::

   event: message
   data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","serverInfo":{"name":"blackbox",…},"instructions":"…",…}}

   В поле instructions — инструкции сервера для AI-ассистента. Если вы пишете собственного агента, передайте их модели.

3. Сохраните ID сессии (значение заголовка mcp-session-id) в переменную MCP_SID:

   export MCP_SID="ID_СЕССИИ"

   Затем подтвердите инициализацию:

   curl https://api.app.blackbox.md/mcp \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -H "Authorization: Bearer $BBX_PAT" \
     -H "mcp-session-id: $MCP_SID" \
     -H "MCP-Protocol-Version: 2025-06-18" \
     -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

   В ответ придёт 202 Accepted без тела.

4. С теми же заголовками запросите список инструментов. В нём только те инструменты, которые разрешает токен, а также whoami и list_vm_plans — им разрешения не нужны:

   {"jsonrpc":"2.0","id":2,"method":"tools/list"}

5. Вызовите инструмент через tools/call:

   {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"whoami","arguments":{}}}

   Результат находится в result.content в виде JSON-текста. Если инструмент отказал, HTTP-статус всё равно будет 200, но в результате будет "isError": true, а в тексте — код ошибки (например, missing_scope или rate_limited).

6. В конце сессию можно закрыть запросом DELETE на тот же адрес с заголовками Authorization и mcp-session-id.

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

Проверка в MCP Inspector

MCP Inspector — официальный инструмент для проверки MCP-серверов. Для него нужен Node.js.

1. Запустите его:

   npx @modelcontextprotocol/inspector

2. В интерфейсе, который откроется в браузере, выберите транспорт «Streamable HTTP» и введите адрес https://api.app.blackbox.md/mcp.

3. Добавьте заголовок Authorization со значением Bearer bbx_pat_….

4. Подключитесь, откройте список инструментов и вызовите whoami. В ответе будут ID аккаунта, разрешения токена и разрешения, которых ему не хватает (missing_scopes).

У Inspector есть и режим командной строки — он удобен в скриптах и автоматических проверках:

npx @modelcontextprotocol/inspector --cli https://api.app.blackbox.md/mcp \
  --transport http \
  --header "Authorization: Bearer $BBX_PAT" \
  --method tools/list

Примечание API AI-провайдеров и MCP Inspector часто меняются. Названия полей, бета-заголовка и параметров в примерах актуальны на 9 октября 2026 года; перед использованием сверьтесь с официальной документацией.

Время ответа и лимиты

• Запрос может выполняться около 5 минут, например долгая команда через run_server_command (не дольше 300 секунд) или оплата заказа через pay_order. Установите в HTTP-клиенте или SDK тайм-аут чтения чуть больше 5 минут.
• Если кажется, что pay_order завершился по тайм-ауту, прежде чем повторять вызов, проверьте заказ через list_orders: Заказы, оплата, отмена и апгрейд через AI.
• Долгие задачи запускайте на сервере в фоне (nohup, systemd-run) и проверяйте результат позже: Выполнение команд на сервере через AI.
• Лимиты действуют на весь аккаунт, для всех токенов вместе: 120 вызовов инструментов в минуту плюс отдельные лимиты для некоторых инструментов. Вызовы, сделанные во время ограничения, тоже засчитываются, поэтому не повторяйте запрос сразу, а подождите. Подробнее: Лимиты и коды ошибок MCP.

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

Есть ли у BLACKBOX REST API? Нет. Единственный программный интерфейс для клиентов — MCP-сервер. Токен bbx_pat_…, отправленный на другие адреса API, не принимается.

Можно ли вызывать MCP-сервер из JavaScript на сайте? Нет. Сервер отклоняет запросы из браузера с чужих сайтов (403 «Invalid Origin header»), а токен увидел бы любой посетитель страницы. Вызывайте сервер с бэкенда.

Скрипт работал, а теперь получает 401. Почему? Токен отозван, или вы сменили пароль аккаунта blackbox.md — после этого перестают работать все токены, созданные до смены. Создайте новый токен: API-токены: создание, копирование и отзыв.

Подойдут ли другие SDK и фреймворки для агентов? Да, подойдёт любой MCP-клиент, который поддерживает транспорт Streamable HTTP и собственные заголовки, например официальные MCP SDK. Используйте адрес и заголовок из таблицы «Параметры подключения».