Возможности

• 🤖 Мультиэндпоинтный чат: поддержка совместимых с OpenAI Chat Completions, Anthropic Messages и OpenAI Responses эндпоинтов
• 🖼️ Мультимодальная генерация: помимо текстового чата поддерживает асинхронные задачи генерации изображений и видео (текст-в-, изображение-в-, первый/последний кадр, референсный материал)
• 🔍 Поиск моделей и аккаунта: список доступных моделей, детали модели, баланс аккаунта, детали использования/биллинга и транзакции пополнения
• 🔑 Передача ключа через заголовок: каждый вызов считывает API-ключ из заголовка запроса, поэтому один деплой можно использовать для нескольких аккаунтов — сервер никогда не сохраняет и не кеширует ключ

Быстрый старт

Используйте его в Claude Code (рекомендуется). Добавьте -s user, чтобы зарегистрировать его на уровне пользователя (доступен во всех ваших проектах).

Шаг 1: добавьте подключение

Копироватьclaude mcp add --transport http basicrouter https://api.basicrouter.ai/mcp \
  --header "X-Basicrouter-Api-Key: <ваш API-ключ BasicRouter>" \
  -s user

Шаг 2: проверьте подключение

Копироватьclaude mcp list          # должно показать ✓ Connected
claude mcp get basicrouter  # должно показать Scope: User config (available in all your projects)

Шаг 3: начните использовать

Вы можете попросить Claude, например:

• «Используй BasicRouter, чтобы вызвать claude-sonnet-5 и написать стихотворение про осень»
• «Покажи список моделей, доступных на моём аккаунте BasicRouter»
• «Проверь мой баланс BasicRouter и недавнее использование»
• «Используй BasicRouter, чтобы сгенерировать изображение киберпанк-города ночью»

Claude автоматически вызовет подходящий MCP-инструмент и вернёт результат.

Использование с Claude Desktop

Добавьте это в раздел mcpServers:

Копировать{
  "mcpServers": {
    "basicrouter": {
      "type": "http",
      "url": "https://api.basicrouter.ai/mcp",
      "headers": {
        "X-Basicrouter-Api-Key": "<ваш API-ключ BasicRouter>"
      }
    }
  }
}

Использование с Codex CLI

Рекомендуется: используйте env_http_headers, чтобы считывать ключ из переменной окружения

Сначала экспортируйте переменную окружения в вашей оболочке:

Копироватьexport BASICROUTER_API_KEY=<ваш API-ключ BasicRouter>

Затем в ~/.codex/config.toml:

Копировать[mcp_servers.basicrouter]
url = "https://api.basicrouter.ai/mcp"
env_http_headers = { "X-Basicrouter-Api-Key" = "BASICROUTER_API_KEY" }

Альтернатива: используйте http_headers, чтобы записать ключ прямо в конфиг (удобно, если вы не хотите заводить отдельную переменную окружения, но учтите, что ключ будет храниться в конфиге в открытом виде):

Копировать[mcp_servers.basicrouter]
url = "https://api.basicrouter.ai/mcp"
http_headers = { "X-Basicrouter-Api-Key" = "<ваш API-ключ BasicRouter>" }

При добавлении через интерфейс настроек Codex:

• Тип: HTTP / Streamable HTTP
• Имя: basicrouter
• URL: https://api.basicrouter.ai/mcp
• Имя заголовка: X-Basicrouter-Api-Key
• Значение заголовка: ваш API-ключ BasicRouter

Проверка подключения

После запуска Codex CLI команда /mcp выводит список настроенных MCP-серверов и статус их подключения — просто убедитесь, что он загрузился корректно. Схема использования совпадает с Claude: Codex автоматически выбирает нужный инструмент.

Если в вашем конфиге уже есть другие MCP-серверы, добавьте этот на том же уровне. После редактирования полностью закройте и снова откройте Claude Desktop.

Инструменты

Этот MCP-сервер предоставляет 14 инструментов, разделённых на пять групп:

1. Чат

1. chat_completion — Chat Completions

Отправляет один запрос диалога и возвращает полный ответ модели (без стриминга). Помимо текста, принимает изображения для визуального понимания (модель должна поддерживать vision) — измените content сообщения со строки на массив блоков контента, смешивая text и image_url.

Мультимодальный ввод (text / image / video)

Ввод изображения (URL):

Копировать{"role": "user", "content": [
  {"type": "text", "text": "Что на этом изображении?"},
  {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]}

Ввод изображения (Base64):

Копировать{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,<BASE64_STRING>"}}

Поддерживаемые форматы: PNG, JPEG, GIF (только первый кадр), WebP. Одно изображение до 20MB.

Примечание: Base64-кодирование больших изображений даёт очень длинные строки и может завершиться ошибкой из-за слишком большого тела запроса; предпочтительнее передавать изображения по URL.

Параметр detail (необязательный, задаётся в объекте image_url) управляет точностью обработки изображения: "auto" (по умолчанию — модель решает по размеру) / "low" (превью 512x512, быстро и дёшево, для простой классификации) / "high" (полное разрешение, для мелкого текста / деталей). В массиве content одного сообщения можно разместить несколько блоков image_url, чтобы передать несколько изображений.

Ввод видео (URL):

Копировать{"role": "user", "content": [
  {"type": "text", "text": "Опишите, что происходит в этом видео."},
  {"type": "video_url", "video_url": {"url": "https://example.com/video.mp4"}}
]}

Ввод видео (Base64):

Копировать{"type": "video_url", "video_url": {"url": "data:video/mp4;base64,<BASE64_STRING>"}}

Модели, поддерживающие ввод видео на BasicRouter, включают отдельные модели серий Qwen, Doubao (dola-seed), Kimi, MiniMax — проверьте input_modalities, возвращаемый list_models. Официальный стандарт Chat Completions OpenAI не поддерживает видео нативно, но шлюз BasicRouter поддерживает через

Копировать{"type": "video_url", "video_url": {"url": "..."}}

формат расширения. Этот формат совместим с форматом video_url, используемым OpenRouter, NVIDIA NIM, vLLM и другими платформами.

2. create_message — совместим с Anthropic Messages

Вызывает совместимый интерфейс Anthropic Messages (без стриминга). Блоки контента поддерживают text, image, tool_use, tool_result, thinking, redacted_thinking. Изображения передаются через блоки контента.

Копировать{"type": "image", "source": {...}}

Мультимодальный ввод (text / image / video)

Ввод изображения поддерживает три типа source:

1. Base64-кодирование (внимание: поле data — чистая Base64-строка, без префикса data:); media_type поддерживает image/jpeg, image/png, image/gif, image/webp:

Копировать{"type": "image", "source": {
  "type": "base64",
  "media_type": "image/jpeg",
  "data": "<BASE64_STRING>"
}}

2. URL-ссылка:

Копировать{"type": "image", "source": {
  "type": "url",
  "url": "https://example.com/image.jpg"
}}

3. File ID (сначала загрузите изображение через Files API с purpose="vision", чтобы получить file_id):

Копировать{"type": "image", "source": {
  "type": "file",
  "file_id": "<file_id>"
}}

В массиве content одного сообщения можно разместить несколько блоков image, чтобы передать несколько изображений.

Примечание: Base64-кодирование больших изображений даёт очень длинные строки и может завершиться ошибкой из-за слишком большого тела запроса; предпочтительнее передавать изображения по URL.

Ввод видео: API Anthropic Messages не поддерживает видеофайлы нативно. Для понимания видео сначала извлеките ключевые кадры через ffmpeg или аналоги, затем передайте каждый кадр как блок контента image. Для моделей, поддерживающих ввод видео на BasicRouter (проверьте input_modalities, возвращаемый list_models), используйте интерфейс chat_completion или create_response для нативной поддержки видео.

3. create_response — совместим с OpenAI Responses

Использует input вместо messages, instructions вместо системного сообщения и text.format вместо response_format. Помимо текста, принимает изображения для визуального понимания (модель должна поддерживать vision) — задайте input как массив объектов-сообщений, чей content — массив блоков контента, смешивающий текст и изображения.

Мультимодальный ввод (text / image / video)

Примечание: Responses API использует типы блоков контента input_text / input_image / input_video (не text / image_url / video_url как в Chat Completions), а image_url / video_url — bare-строка, не вложенный объект.

Ввод изображения (URL):

Копировать[{"role": "user", "content": [
  {"type": "input_text", "text": "Что на этом изображении?"},
  {"type": "input_image", "image_url": "https://example.com/image.jpg"}
]}]

Ввод изображения (Base64):

Копировать{"type": "input_image", "image_url": "data:image/jpeg;base64,<BASE64_STRING>"}

Поддерживаемые форматы: PNG, JPEG, GIF (только первый кадр), WebP. Одно изображение до 20MB.

Примечание: Base64-кодирование больших изображений даёт очень длинные строки и может завершиться ошибкой из-за слишком большого тела запроса; предпочтительнее передавать изображения по URL.

Ввод изображения (File ID):

Копировать{"type": "input_image", "file_id": "<file_id>"}

— file_id получается загрузкой изображения через Files API с purpose="vision".

Параметр detail (необязательный, в объекте input_image) управляет точностью обработки: "auto" (по умолчанию) / "low" (превью 512x512, быстро и дёшево) / "high" (полное разрешение, для мелкого текста / деталей) / "original" (оригинальное разрешение). В массиве content одного сообщения можно разместить несколько блоков input_image для нескольких изображений.

Ввод видео (URL):

Копировать[{"role": "user", "content": [
  {"type": "input_text", "text": "Опишите, что происходит в этом видео."},
  {"type": "input_video", "video_url": "https://example.com/video.mp4"}
]}]

Ввод видео (Base64):

Копировать{"type": "input_video", "video_url": "data:video/mp4;base64,<BASE64_STRING>"}

; Video input (File ID):

Копировать{"type": "input_video", "file_id": "<file_id>"}

. Модели, поддерживающие ввод видео на BasicRouter, включают отдельные модели серий Qwen, Doubao (dola-seed), Kimi, MiniMax — проверьте input_modalities, возвращаемый list_models. Официальный стандарт Responses API OpenAI не поддерживает видео нативно, но шлюз BasicRouter поддерживает через

Копировать{"type": "input_video", "video_url": "..."}

формат расширения. Этот формат совместим с форматом input_video, используемым BytePlus/Volcengine и другими платформами.

2. Модели и аккаунт

4. list_models — список доступных моделей

Возвращает модели, доступные текущему аккаунту, с метаданными о вендоре, модальности, возможностях и ценах. Без параметров. Каждый элемент списка содержит ценовые тарифы price_tiers — действующую цену биллинга для вызывающего, совпадающую с реальным списанием (см. описание поля ценовых тарифов) (only some newer models).

5. get_model — получить детали одной модели

Вывод содержит ценовые тарифы price_tiers (см. описание поля ценовых тарифов); при отсутствии модели возвращает 404 без ценовых полей.

6. get_balance — проверить баланс аккаунта

Возвращает текущее использование и баланс аккаунта. Без параметров.

3. Биллинг

7. list_usage — детали использования моделей/биллинга

Постраничные детали биллинга по использованию моделей, отсортированные по времени создания заказа по убыванию. Только обычные списания за использование — без пополнений и корректировок.

8. list_transactions — транзакции пополнений/пакетов

Постраничные оплаченные транзакции пополнения / покупки пакетов, отсортированные по времени создания по убыванию.

4. Генерация изображений

9. list_image_models — список моделей изображений

Возвращает поддерживаемые модели генерации изображений с разрешением, соотношением сторон, максимальным числом изображений (maxCount) и максимальным числом референсных изображений (fileMax). Без параметров. Проверяйте это перед генерацией изображений — можно передавать только опубликованные здесь значения. Каждый элемент списка содержит ценовые тарифы priceTiers (см. описание поля ценовых тарифов).

10. create_image_generation — отправить задачу генерации изображения

Отправляет асинхронно и сразу возвращает taskId; расходует кредиты аккаунта.

11. get_image_generation — опросить задачу генерации изображения

Возвращает: status — pending / success / failed; images — JSON-массив строк с URL изображений; text содержит дополнительный вывод модели (например, мультимодальный вывод Gemini).

5. Генерация видео

12. list_video_models — список моделей видео

Возвращает поддерживаемые модели генерации видео с allowedVideoTypes, диапазоном длительности (videoDurationMin/Max), разрешением, соотношением сторон и лимитом референсных материалов (fileMax). Без параметров. Проверяйте это перед генерацией видео. Каждый элемент списка содержит ценовые тарифы priceTiers (см. описание поля ценовых тарифов).

13. create_video_generation — отправить задачу генерации видео

Отправляет асинхронно и сразу возвращает taskId; расходует кредиты аккаунта.

Значения video_type:

14. get_video_generation — опросить задачу генерации видео

Описание поля ценовых тарифов

Вывод этих 4 инструментов запроса моделей — list_models, get_model, list_image_models, list_video_models — возвращает действующую цену биллинга вызывающего (пользователя API Key), полностью совпадающую с реальным списанием, и включает все ценовые тарифы модели.

Различие в именовании: list_models / get_model используют OpenAI snake_case (price_tiers); list_image_models / list_video_models используют camelCase (priceTiers). Структура одинакова.

price_tiers / priceTiers — массив; каждый элемент это ценовой тариф:

Три типа моделей имеют одну структуру; различаются только поля описания, неприменимые поля равны null:

Смысл цены: возвращаемые inputPrice / outputPrice / cacheReadPrice / cacheWritePrice и т.д. — это итоговые цены биллинга для текущего пользователя API Key, вычисленные через ценовую цепочку (chain) → guidance → базовую цену, и совпадают с реальным списанием. Цена, которую видит вызывающий, зависит от его ценовой цепочки (reseller / distributor / предприятие / пользовательская настройка).

Реальное списание = объём ÷ quantity × цена × ratio. При посекундном биллинге видео: реальное списание = duration × outputPrice × ratio.

Граничные случаи и обработка ошибок (read-only эндпоинт не возвращает 500 из-за конфигурации цены):

Пример ответа (list_models, текстовая модель):

Копировать{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "display_name": "gpt-4o",
      "context_length": 128000,
      "description": "...",
      "price_tiers": [
        {
          "region": "GLOBAL",
          "bandMin": null,
          "bandMax": null,
          "resolution": null,
          "clarity": null,
          "unit": "token",
          "quantity": 1000,
          "description": "за 1K token",
          "inputPrice": 0.0025,
          "outputPrice": 0.01,
          "cachePrice": 0.00125,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

Пример ответа (list_image_models, модель изображений; priceTiers структура та же, unit равен image):

Копировать{
  "object": "list",
  "data": [
    {
      "id": "dall-e-3",
      "object": "image_model",
      "displayName": "dall-e-3",
      "resolutions": ["1024x1024", "1792x1024", "1024x1792"],
      "priceTiers": [
        {
          "region": null,
          "bandMin": null,
          "bandMax": null,
          "resolution": "1024x1024",
          "clarity": "standard",
          "unit": "image",
          "quantity": 1,
          "description": "за изображение",
          "inputPrice": 0,
          "outputPrice": 0.04,
          "cachePrice": 0,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

Примеры

Пример 1: обычный запрос чата

Спросите: «Используй BasicRouter, чтобы вызвать claude-sonnet-5 и спросить, что такое GIL в Python»

AI вызовет chat_completion с параметрами:

Копировать{
  "model": "claude-sonnet-5",
  "messages": [{"role": "user", "content": "What is Python's GIL?"}]
}

Пример 2: использование инструментов через эндпоинт Anthropic Messages

Спросите: «Используй эндпоинт Messages BasicRouter и позволь модели решить, нужно ли проверять погоду»

AI вызовет create_message, передав определение tools и tool_choice; в ответе будет блок контента tool_use.

Пример 3: список доступных моделей

Спросите: «Покажи список моделей на моём аккаунте BasicRouter»

AI вызовет list_models, вернув ID, вендоров, модальности, цены и другую информацию по каждой доступной модели.

Пример 4: проверка баланса и использования

Спросите: «Проверь моё использование BasicRouter за этот месяц»

AI вызовет get_balance для баланса, затем list_usage (с start_time, ограниченным этим месяцем) для разбивки использования.

Пример 5: генерация изображения

Спросите: «Используй BasicRouter, чтобы сгенерировать изображение киберпанк-города ночью»

AI сначала вызовет list_image_models, чтобы проверить спецификации, затем create_image_generation, чтобы получить taskId, затем опросит get_image_generation для получения URL изображения.

Пример 6: текст-в-видео

Спросите: «Используй BasicRouter, чтобы сгенерировать 5-секундное видео космической туманности»

AI сначала вызовет list_video_models, чтобы проверить спецификации, затем create_video_generation (video_type=1, duration=5), и после получения taskId опросит get_video_generation.

ЧАВО

Вызов инструмента завершается ошибкой «missing BasicRouter API Key»

• Вы выполнили claude mcp add без --header, либо ключ указан неверно
• Если вы редактируете JSON-конфиг напрямую, имя поля в headers указано неверно (должно быть X-Basicrouter-Api-Key)
• Запуск локально без установленной переменной окружения BASICROUTER_API_KEY

Вызов инструмента завершается ошибкой «BasicRouter returned 401 unauthorized»

Сам API-ключ неверен или истёк — перегенерируйте его в консоли BasicRouter.

Claude не вызывает инструменты BasicRouter — что делать?

• Убедитесь, что подключение показывает ✓ Connected через claude mcp list
• Проверьте статус подключения: claude mcp get basicrouter
• Попробуйте сформулировать явно: «Используй инструмент chat_completion BasicRouter, чтобы вызвать claude-sonnet-5 …»

Генерация изображения/видео бесконечно висит в статусе pending

• Опрашивайте задачи изображений через get_image_generation, а задачи видео через get_video_generation — обратите внимание, что у выполняющейся задачи видео статус «running», а не «pending»
• Генерация занимает время, обычно от нескольких до десятков секунд, для видео — дольше
• Если вы передали callback_url, задача сама вызовет обратный вызов по завершении — опрос не требуется

Ошибки list_image_models / list_video_models

Ни один из этих инструментов сам по себе не расходует кредиты — ошибка обычно указывает на проблему с ключом или сетью. Сначала убедитесь, что list_models работает нормально.

Примечания

• Имя заголовка:MCP передаёт ключ через X-Basicrouter-Api-Key.
• Расход кредитов:chat_completion / create_message / create_response / create_image_generation / create_video_generation — все они расходуют кредиты аккаунта; проверьте get_balance заранее, если хотите знать баланс до вызова.
• Проверяйте спецификации перед генерацией:Параметры генерации изображений/видео, такие как model, resolution, ratio, count, duration и video_type, должны использовать только значения, опубликованные list_image_models / list_video_models, иначе вызов завершится ошибкой.
• Без потоковой передачи:Ни один из трёх эндпоинтов чата не поддерживает потоковую передачу — каждый возвращает полный результат сразу.
• Stateless-дизайн:Каждый запрос независим, сессии не сохраняются; для многошаговых диалогов используйте previous_response_id в create_response или самостоятельно поддерживайте историю в messages.