OpenRouter MCP Server

Удалённый MCP-сервер (streamable HTTP, stateless JSON), который позволяет ИИ-агентам делегировать задачи более дешёвым моделям через OpenRouter API, запрашивая каталог и актуальные цены, с политикой стоимости, настраиваемой через файл .env.

Что он делает

• Актуальный каталог: запрашивает GET /api/v1/models у OpenRouter (с кэшем на 5 минут) и предоставляет цены в USD за миллион токенов, размер контекстного окна и поддержку вызова инструментов.

• Явное делегирование: агент выбирает модель, глядя на цены, и делегирует задачу.

• Автоматическое делегирование на основе цены: сервер выбирает модель на основе уровня (economy / balanced / quality), используя настраиваемые ценовые диапазоны.

• Политика через .env: максимальные ценовые ограничения, списки разрешённых/заблокированных моделей, модель по умолчанию, предпочтительные провайдеры.

• Реальная стоимость: каждое делегирование возвращает использованные токены и расчётную стоимость в USD.

Related MCP server: frugal

Установка

npm install
cp .env.example .env   # edit and set your OPENROUTER_API_KEY
npm run build
npm start              # listens on http://localhost:3000/mcp

Для разработки с автоматической перезагрузкой: npm run dev.

Docker

Мультиархитектурный образ (linux/amd64, linux/arm64) автоматически собирается GitHub Actions и публикуется в GHCR:

ghcr.io/vmhq/openrouter-mcp-server

Доступные теги: latest (ветка main), vX.Y.Z / X.Y (релизы), main и sha-<commit>.

Docker Compose

services:
  openrouter-mcp:
    image: ghcr.io/vmhq/openrouter-mcp-server:latest
    container_name: openrouter-mcp
    restart: unless-stopped
    ports:
      - "3000:3000"
    env_file:
      - .env
    volumes:
      # Persists OAuth state (registered clients, token hashes)
      - ./data:/app/data
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3

docker compose up -d

Примечание: контейнер работает под непривилегированным пользователем node. Убедитесь, что смонтированный каталог ./data доступен для записи UID 1000 (chown -R 1000:1000 ./data), иначе состояние OAuth не сможет сохраняться.

Пример .env

# --- Required ---
# Your OpenRouter API key (https://openrouter.ai/keys)
OPENROUTER_API_KEY=sk-or-v1-...

# --- HTTP server ---
# Port where the MCP endpoint is exposed (http://host:PORT/mcp)
PORT=3000
# Optional static bearer token. If set, MCP clients must send
# "Authorization: Bearer <token>". Strongly recommended if the server
# is reachable outside localhost.
MCP_AUTH_TOKEN=

# --- Interactive OAuth with PocketID (for AI agents like Claude) ---
# Public URL of this server (e.g. https://mcp.example.com). Required so the
# OAuth metadata and callback point to the right URL behind a reverse proxy.
MCP_PUBLIC_URL=
# When all three POCKETID_* variables are set, the /oauth/authorize flow
# delegates the human login to your PocketID instance (passkey).
# In PocketID: create an OIDC client and register this callback:
#   <MCP_PUBLIC_URL>/oauth/callback
POCKETID_ISSUER=
POCKETID_CLIENT_ID=
POCKETID_CLIENT_SECRET=
# Optional OIDC scopes (space-separated). Default: "openid profile email".
# POCKETID_SCOPES=openid profile email
# Path of the file where OAuth state is persisted (registered clients,
# one-time codes, and token hashes). Default: ./data/oauth-state.json
# MCP_OAUTH_STATE_PATH=./data/oauth-state.json
# OAuth access token lifetime, in seconds. Default: 2592000 (30 days).
# MCP_OAUTH_TOKEN_TTL_S=2592000

# --- Optional OpenRouter attribution (rankings) ---
APP_URL=
APP_TITLE=OpenRouter MCP Server

# --- Delegation policy ---
# Default model when the agent doesn't specify one in openrouter_delegate_task
DEFAULT_MODEL=

# Price caps (USD per million tokens). Models above them are rejected
# with an explanatory error. Empty = no limit.
MAX_PROMPT_PRICE_PER_M=
MAX_COMPLETION_PRICE_PER_M=

# Comma-separated control lists. Accept exact ids ("openai/gpt-4.1-mini")
# or provider prefixes ("openai/"). Empty ALLOWED_MODELS = all allowed
# (except blocked ones).
ALLOWED_MODELS=
BLOCKED_MODELS=

# Allow free models (price 0)? They usually have strict rate limits.
ALLOW_FREE_MODELS=true

# Preferred providers for automatic selection (openrouter_auto_delegate)
PREFERRED_PROVIDERS=openai,anthropic,google,meta-llama,mistralai,deepseek,qwen,x-ai,amazon

# "Combined" price caps (70% prompt + 30% completion, USD/M tokens)
# for each tier of the automatic selection.
TIER_ECONOMY_MAX_PRICE=0.5
TIER_BALANCED_MAX_PRICE=3
TIER_QUALITY_MAX_PRICE=15

# Model catalog cache, in seconds
MODELS_CACHE_TTL_SECONDS=300

Переменные окружения

См. .env.example — основные:

Доступные инструменты

Типичный поток агента: openrouter_list_models (или сразу openrouter_auto_delegate с уровнем economy) → делегировать задачу → использовать ответ, зная, сколько это стоило.

Важно: делегированная модель не видит разговор агента; задача (task) должна быть самодостаточной, со всем необходимым контекстом.

Подключение агента

Claude Code:

claude mcp add --transport http openrouter http://localhost:3000/mcp

С токеном аутентификации:

claude mcp add --transport http openrouter http://YOUR_HOST:3000/mcp --header "Authorization: Bearer YOUR_TOKEN"

Любой MCP-клиент: укажите ему конечную точку POST /mcp с транспортом "streamable HTTP". Для мониторинга есть конечная точка GET /health.

claude.ai (удалённый коннектор): требуется публичный HTTPS URL — разверните сервер на VPS за обратным прокси (Caddy/nginx) или используйте туннель (например, cloudflared tunnel). С включённым OAuth (см. ниже) добавьте коннектор, указав https://YOUR_HOST/mcp, и оставьте расширенные поля OAuth Client ID/Secret пустыми: сервер публикует OAuth-метаданные и поддерживает Dynamic Client Registration, поэтому Claude регистрируется сам и автоматически получает токен при нажатии Authorize.

OAuth с PocketID

Сервер реализует полный OAuth 2.1 для ИИ-агентов (Claude, Cursor, …): он выступает в роли сервера авторизации по отношению к MCP-клиентам (RFC 7591 Dynamic Client Registration + PKCE S256 + выпуск собственных токенов, с метаданными RFC 8414/9728) и делегирует вход человека вашему экземпляру PocketID через OIDC (passkey).

Поток: MCP-клиент получает 401 с WWW-Authenticate → обнаруживает метаданные по адресу /.well-known/oauth-protected-resource → регистрируется на /oauth/register → открывает /oauth/authorize в браузере → пользователь входит в PocketID с помощью passkey → PocketID возвращает на /oauth/callback → сервер выдаёт собственный код, и клиент обменивает его на /oauth/token на токен доступа (по умолчанию 30 дней).

Настройка:

1. В PocketID создайте новый OIDC-клиент.

2. Зарегистрируйте callback: <MCP_PUBLIC_URL>/oauth/callback.

3. Ограничьте, кто может входить, с помощью разрешённых групп OIDC-клиента в PocketID.

4. Скопируйте Client ID и Client Secret в POCKETID_CLIENT_ID / POCKETID_CLIENT_SECRET, а базовый URL PocketID укажите в POCKETID_ISSUER.

5. Установите MCP_PUBLIC_URL на публичный HTTPS URL сервера.

Если переменные POCKETID_* не заданы, интерактивный поток /oauth/authorize показывает ошибку; статический bearer-токен MCP_AUTH_TOKEN продолжает работать параллельно для доступа между машинами (curl, Codex и т.д.).

Состояние OAuth (зарегистрированные клиенты, одноразовые коды и SHA-256 хеши токенов — никогда не сами токены в открытом виде) сохраняется в ./data/oauth-state.json (настраивается через MCP_OAUTH_STATE_PATH). Если после перезапуска со стёртым состоянием коннектор перестаёт работать, удалите его в Claude и добавьте заново, чтобы он перерегистрировался.

Как openrouter_auto_delegate выбирает модель

1. Фильтрует каталог по политике .env и требованиям вызова (require_tools, min_context, текстовый вывод).

2. Вычисляет комбинированную цену для каждой модели: 0.7·input_price + 0.3·output_price (USD/М токенов).

3. В зависимости от уровня ищет в своём ценовом диапазоне (при пустом диапазоне переходит к соседнему):

   • economy (≤ $0.5/М по умолчанию): самая дешёвая.

   • balanced ($0.5–$3/М): самая дешёвая в среднем диапазоне.

   • quality ($3–$15/М): самая дорогая в пределах потолка (цена как прокси для возможностей, без флагманских моделей).

4. Предпочитает провайдеров из PREFERRED_PROVIDERS и сообщает в ответе выбранную модель, обоснование и отклонённые альтернативы.

Безопасность

• Ключ OpenRouter API хранится только в .env сервера; он никогда не раскрывается агентам.

• Файл .env находится в .gitignore.

• Если порт доступен извне, установите MCP_AUTH_TOKEN и обслуживайте через HTTPS.