Как подключить MCP-инструменты через OpenRouter

Как подключить MCP-инструменты через OpenRouter: выберите один из двух путей. Первый — добавить в редактор или кодинг-агент официальный хостед-сервер по адресу https://mcp.openrouter.ai/mcp, тогда ассистент читает живые данные OpenRouter: каталог моделей, цены, бенчмарки, ваш баланс кредитов. Второй — дать моделям OpenRouter собственные MCP-инструменты через пакет @openrouter/mcp и Agent SDK. Выбор зависит от задачи: данные OpenRouter внутри редактора или ваши инструменты внутри агента.

Развилка: данные OpenRouter в редакторе или свои инструменты у модели

Первый сценарий закрывает вопрос «какую модель взять и сколько это стоит». В документации OpenRouter сказано, что хостед-сервер встраивает OpenRouter в инструменты, которыми вы уже пользуетесь: ассистент вытягивает живые данные о моделях, ценах, ваших кредитах, рейтингах и документации и может отправить быстрый тестовый запрос, не выходя из редактора. Сервер удалённый, локально ничего не ставится: подключение сводится к одному URL и подтверждению OAuth-входа в браузере.

Различие принципиальное. Хостед-сервер отдаёт наружу данные OpenRouter. SDK-пакет забирает внутрь вашего агента инструменты сторонних серверов. Во втором сценарии в createMCPTools() указывается адрес того MCP-сервера, чьи инструменты нужны вашему агенту.

Endpoint и удалённый HTTP-транспорт

Официальный сервер живёт по адресу https://mcp.openrouter.ai/mcp. Это удалённый сервер, который размещает OpenRouter; локальная установка не требуется. Транспорт — HTTP: в Claude Code он задаётся флагом --transport http, остальные клиенты получают тот же URL параметром команды или полем конфига.

Схема авторизации устроена так: неаутентифицированный запрос возвращает 401 и подсказывает клиенту адрес OAuth-сервера авторизации OpenRouter. Клиент регистрируется, вы подтверждаете страницу согласия, токен выдаётся по PKCE. Дальше инструменты работают как прокси к публичному API OpenRouter с вашим ключом.

Второй путь использует тот же принцип удалённого транспорта, но другой адрес — URL вашего MCP-сервера. В опциях createMCPTools() транспорт задаётся значением 'streamableHttp' (по умолчанию, с откатом на SSE) или 'sse'. Локальные stdio-серверы этот пакет не обслуживает.

Практический вывод для настройки: если в конфиге клиента вы указываете команду запуска процесса, это не тот путь. Официальный сервер подключается URL-адресом.

OAuth и выделенный ключ: срок, лимит, отзыв

При первом входе открывается страница согласия OpenRouter, где вы одобряете отдельный ключ именно для этого подключения. По документации сервера ключ получает метку вида OpenRouter MCP: <app name>, срок жизни 7 дней и стартовый лимит расходов $10. Лимит редактируется прямо на экране одобрения. Ключ отдельный от остальных ваших ключей и отзывается в любой момент из дашборда.

Срок и лимит — не формальность. Ключ живёт 7 дней, после чего инструменты начнут возвращать ошибку аутентификации. Лечится это повторным прохождением шага аутентификации в клиенте. Некоторые клиенты не показывают окно входа автоматически: тогда вход запускают вручную тем же шагом, что и при добавлении сервера.

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

Команды и конфиги клиентов

Синтаксис ниже приведён по документации хостед-сервера OpenRouter. Claude Code добавляет сервер и логинится двумя командами:

claude mcp add --transport http openrouter https://mcp.openrouter.ai/mcp
claude mcp login openrouter

Аутентификацию можно пройти и изнутри сессии: команда /mcp, выбрать openrouter, нажать Authenticate. Codex CLI использует свой синтаксис:

codex mcp add openrouter --url https://mcp.openrouter.ai/mcp
codex mcp login openrouter

OpenCode читает конфиг ~/.config/opencode/opencode.json и запускает OAuth сам при первом обращении, без отдельного шага входа:

{
  "mcp": {
    "openrouter": {
      "type": "remote",
      "url": "https://mcp.openrouter.ai/mcp",
      "enabled": true
    }
  }
}

Cursor CLI (cursor-agent) читает тот же конфиг, что и IDE: запись добавляется в ~/.cursor/mcp.json, проверка — командой cursor-agent mcp list, вход — из настроек MCP или по запросу при первом вызове инструмента.

{
  "mcpServers": {
    "openrouter": { "url": "https://mcp.openrouter.ai/mcp" }
  }
}

Claude Desktop и Web настраиваются через интерфейс: Settings → Connectors → Customize → Connectors, затем кнопка «+» и пункт Add custom connector. Имя — OpenRouter MCP, Remote MCP server URL — https://mcp.openrouter.ai/mcp, поля OAuth оставить пустыми. Затем нажать Add, открыть коннектор и нажать Connect, чтобы пройти OAuth. В организациях, где добавление своих коннекторов запрещено, этот пункт может не отображаться — вопрос решается через администратора.

Таблица инструментов: чтение, расход, запись

В документации сервера прямо сказано: большинство инструментов — read-only обращения к живым данным OpenRouter. Исключения — send-message и generate-image, которые делают оплачиваемые вызовы инференса, и send-feedback, который записывает отзыв о вашей генерации. spawn-ori-eval и install-ori-harness возвращают инструкции, а расход возникает при их исполнении.

Первый проверочный запрос: только чтение

Начните с инструментов чтения — они не тратят кредиты и сразу показывают, что связь и авторизация работают. Подойдёт вопрос про баланс: Сколько кредитов у меня осталось на OpenRouter? Ассистент вызовет get-credits и вернёт остаток.

Дальше проверьте каталог: «Какая модель сейчас лучшая для кода?» Документация описывает поведение так: для любого вопроса «какую модель использовать» ассистент опирается на живые list-benchmarks, list-daily-model-rankings и list-models. send-message настроен так, чтобы ассистент не называл модель по памяти. Полезные формулировки для проверки: Какая модель возглавляет индекс интеллекта Artificial Analysis?, Какие embedding-модели доступны и какая лучше?, Как привязать модель к конкретному провайдеру, например Bedrock?.

Сценарий (б): @openrouter/mcp и Agent SDK

Для своего агента установите пакеты:

npm install @openrouter/mcp @openrouter/agent

Схема работы: createMCPTools() вызывается один раз, возвращает handle с массивом mcp.tools, который раскрывается в callModel({ tools }), а по завершении handle закрывается. Минимальный пример из документации Agent SDK:

import { OpenRouter } from '@openrouter/agent';
import { callModel } from '@openrouter/agent/call-model';
import { createMCPTools } from '@openrouter/mcp';

const client = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });

const mcp = await createMCPTools({
  url: 'https://mcp.example.com/mcp',
  auth: { kind: 'bearer', token: process.env.MCP_TOKEN },
});

const result = callModel(client, {
  model: 'anthropic/claude-opus-4-8',
  input: 'What are my three most recently updated issues?',
  tools: mcp.tools,
});

console.log(await result.getText());
await mcp.close();

Свои инструменты и MCP-инструменты живут в одном массиве tools. Каждый обёрнутый инструмент помечен брендом _mcp, поэтому SDK различает источники: результат своего инструмента типизирован по его схеме, результат MCP-инструмента приходит как unknown. Проверка isMcpTool(tool) пригодится в хуках жизненного цикла. Для нескольких серверов используйте toolNamePrefix, чтобы имена не пересекались.

Сценарий (б): конвертация под OpenAI-совместимый API

Второй вариант того же сценария — ручная конвертация MCP-инструментов в формат OpenAI-совместимого API. В документации OpenRouter приведён пример на Python с MCP client SDK: клиент подключается к stdio-серверу filesystem, получает список инструментов и преобразует каждое определение в OpenAI-формат.

Функция конвертации из примера переносит name, description и inputSchema в объект с type: "function". Клиент создаёт OpenAI с base_url="https://openrouter.ai/api/v1", поднимает сессию через stdio_client, вызывает session.initialize() и печатает список доступных инструментов. Дальше цикл: отправить запрос, получить tool_calls, выполнить инструмент через session.call_tool, добавить результат в историю сообщений и запросить финальный ответ.

Документация честно предупреждает: взаимодействие с MCP-серверами сложнее вызова REST-эндпоинта, протокол хранит состояние и требует управления сессией, а сам пример клиента занимает около сотни строк. Для TypeScript-агента тот же результат даёт @openrouter/mcp. Ручную конвертацию выбирают, когда нужен Python, свой контроль над циклом вызовов или нестандартный транспорт.

Правило: production-трафик идёт через прямой API

Причина практическая. В документации сервера сказано прямо: этот MCP нужен на время разработки, а модели в приложении вызываются через API OpenRouter напрямую. Ключ MCP выдан под одно подключение, живёт 7 дней и стартует с лимитом расходов $10, поэтому рабочей нагрузке он не подходит. Плюс MCP-протокол хранит состояние и требует управления сессией, тогда как прямой вызов API проще и предсказуемее. Разделение ролей: MCP для выбора модели и проверки промптов, API для продакшена.

Сторонние серверы

В выдаче по запросу встречаются сторонние MCP-серверы для OpenRouter. Например, llm-wrapper-mcp-server на thedailyworkflow.com описан как MCP-сервер, позволяющий агентам с поддержкой MCP общаться с любой LLM или делегировать ей задачи. Репозиторий mcp-group-org/mcp_openrouterai на GitHub заявлен как MCP-реализация подключения к openrouter.ai.

Эти проекты не от OpenRouter. Их ведут сторонние авторы, поэтому гарантий совместимости, поддержки и поведения от OpenRouter у них нет. Для llm-wrapper-mcp-server в описании указан транспорт STDIO. Официальная документация описывает только хостед-сервер mcp.openrouter.ai и пакет @openrouter/mcp. Сторонний сервер стоит рассматривать как отдельное решение со своим README и своей ответственностью за безопасность ключей.

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

Что такое OpenRouter MCP?

Это MCP-сервер, который подключает OpenRouter к инструментам, которыми вы уже пользуетесь. После подключения ассистент вытягивает живые данные OpenRouter — модели, цены, ваши кредиты, рейтинги, документацию — и может отправить быстрый тестовый запрос, не выходя из редактора. Сервер удалённый, размещён OpenRouter, локально ничего не устанавливается. Подключение сводится к одному URL и подтверждению OAuth-входа в браузере.

Как подключить OpenRouter MCP в Cursor?

Добавьте запись в ~/.cursor/mcp.json с URL https://mcp.openrouter.ai/mcp, затем проверьте командой cursor-agent mcp list. Аутентификация проходит из настроек MCP или запускается запросом при первом вызове инструмента. Cursor CLI читает тот же конфиг, что и IDE. В организациях, где свои коннекторы запрещены, настройка может не отобразиться.

Сколько стоит использование MCP-сервера OpenRouter?

Сервер выдаёт выделенный ключ со стартовым лимитом расходов $10, который редактируется на экране одобрения. Большинство инструментов — read-only обращения к данным OpenRouter и расходов не создают. Платные вызовы делают send-message и generate-image: они выполняют инференс с оплатой из баланса ключа. send-feedback записывает отзыв о вашей генерации.

Чем MCP-сервер отличается от прямого вызова API?

MCP-сервер — ассистент для разработки: он даёт кодинг-агенту живые данные OpenRouter и возможность отправить тестовое сообщение. Приложение для реальной нагрузки должно вызывать API OpenRouter напрямую. Ключ MCP живёт 7 дней и стартует с лимитом расходов $10, а протокол хранит состояние и требует управления сессией. Роли разделяются: MCP для выбора модели, API для продакшена.

Можно ли подключить свои MCP-инструменты к моделям OpenRouter?

Да, через пакет @openrouter/mcp вместе с @openrouter/agent. Функция createMCPTools() подключается к удалённому MCP-серверу по Streamable HTTP или SSE и возвращает handle, чей массив mcp.tools раскрывается в callModel({ tools }). Пакет обслуживает удалённые серверы, доступные по HTTP. Свои инструменты и MCP-инструменты можно держать в одном массиве, SDK различает их по источнику.