원격 MCP 서버(streamable HTTP, stateless JSON)로, AI 에이전트가 OpenRouter API를 통해 저렴한 모델에 작업을 위임할 수 있게 해주며, 카탈로그와 실시간 가격을 조회하고, .env 파일을 통해 비용 정책을 구성할 수 있습니다.
실시간 카탈로그: OpenRouter의 GET /api/v1/models를 조회하고(5분 캐시), 백만 토큰당 USD 가격, 컨텍스트 창, 도구 호출 지원 여부를 노출합니다.
명시적 위임: 에이전트가 가격을 보고 모델을 선택하여 작업을 위임합니다.
자동 가격 기반 위임: 서버가 구성 가능한 가격대를 사용하여 티어(economy / balanced / quality)에 따라 모델을 선택합니다.
.env를 통한 정책: 최대 가격 상한, 허용/차단 모델 목록, 기본 모델, 선호 공급자.
실제 비용: 모든 위임은 사용된 토큰 수와 예상 USD 비용을 반환합니다.
Related MCP server: whichmodel-mcp
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.
멀티 아키텍처 이미지(linux/amd64, linux/arm64)는 GitHub Actions에 의해 자동으로 빌드되어 GHCR에 게시됩니다:
ghcr.io/vmhq/openrouter-mcp-server사용 가능한 태그: latest(main 브랜치), vX.Y.Z / X.Y(릴리스), main, sha-<commit>.
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: 3docker 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 참조 — 주요 변수:
변수 | 설명 |
| 필수. https://openrouter.ai/keys에서 발급받은 키 |
| HTTP 포트(기본값 3000) |
| 설정된 경우 클라이언트는 |
| 서버의 공개 URL(예: |
| PocketID 인스턴스에 인증을 위임하여 대화형 OAuth 로그인을 활성화합니다(아래 참조) |
| 에이전트가 모델을 지정하지 않을 때 |
| 가격 상한(USD/M 토큰); 더 비싼 모델은 거부됩니다 |
| 쉼표로 구분된 목록: 정확한 ID 또는 접두사( |
| 무료 모델 허용(기본값 |
| 자동 선택의 각 티어에 대한 결합 가격 상한(0.7·입력 + 0.3·출력) |
도구 | 설명 |
| 실시간 가격으로 모델 목록을 표시합니다. 텍스트, 가격, 컨텍스트, 도구 호출로 필터링하고, 가격/컨텍스트/최신순으로 정렬하며, 페이지네이션을 지원합니다. |
| 모델의 전체 세부 정보 + |
| 특정 모델에 작업을 위임합니다. 응답, 토큰 수, 예상 비용을 반환합니다. |
| 서버가 가격 티어( |
| 구성된 API 키의 사용량 및 한도 |
일반적인 에이전트 흐름: openrouter_list_models(또는 economy 티어로 바로 openrouter_auto_delegate) → 작업 위임 → 비용을 확인하면서 응답 사용.
중요: 위임된 모델은 에이전트의 대화를 볼 수 없습니다. 작업(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 클라이언트: "streamable HTTP" 전송으로 POST /mcp 엔드포인트를 가리키세요. 모니터링을 위한 GET /health 엔드포인트도 있습니다.
claude.ai(원격 커넥터): 공개 HTTPS URL이 필요합니다. VPS에 리버스 프록시(Caddy/nginx) 뒤에 서버를 배포하거나 터널(예: cloudflared tunnel)을 사용하세요. OAuth가 활성화된 경우(아래 참조), https://YOUR_HOST/mcp를 가리키는 커넥터를 추가하고 고급 OAuth Client ID/Secret 필드는 비워 두세요. 서버가 OAuth 메타데이터를 게시하고 Dynamic Client Registration을 지원하므로, Authorize를 클릭하면 Claude가 자동으로 등록하고 토큰을 얻습니다.
서버는 AI 에이전트(Claude, Cursor 등)를 위한 완전한 OAuth 2.1을 구현합니다. MCP 클라이언트에 대해 인증 서버 역할을 하며(RFC 7591 Dynamic Client Registration + PKCE S256 + 자체 토큰 발급, RFC 8414/9728 메타데이터), 사용자 로그인은 OIDC(패스키)를 통해 PocketID 인스턴스에 위임합니다.
흐름: MCP 클라이언트가 401과 WWW-Authenticate를 받음 → /.well-known/oauth-protected-resource에서 메타데이터를 발견 → /oauth/register에 등록 → 브라우저에서 /oauth/authorize를 엶 → 사용자가 패스키로 PocketID에 로그인 → PocketID가 /oauth/callback으로 돌아감 → 서버가 자체 코드를 발급하고 클라이언트가 /oauth/token에서 액세스 토큰(기본 30일)으로 교환.
설정:
PocketID에서 새 OIDC 클라이언트를 만듭니다.
콜백을 등록합니다: <MCP_PUBLIC_URL>/oauth/callback.
PocketID의 OIDC 클라이언트 허용 그룹을 사용하여 로그인할 수 있는 사용자를 제한합니다.
Client ID와 Client Secret을 POCKETID_CLIENT_ID / POCKETID_CLIENT_SECRET에 복사하고, PocketID 기본 URL을 POCKETID_ISSUER에 설정합니다.
MCP_PUBLIC_URL을 서버의 공개 HTTPS URL로 설정합니다.
POCKETID_* 변수가 설정되지 않은 경우 대화형 /oauth/authorize 흐름은 오류를 표시합니다. 정적 MCP_AUTH_TOKEN 베어러는 머신 간 액세스(curl, Codex 등)를 위해 병렬로 계속 작동합니다.
OAuth 상태(등록된 클라이언트, 일회용 코드, 토큰의 SHA-256 해시 — 일반 텍스트 토큰은 절대 아님)는 ./data/oauth-state.json에 저장됩니다(MCP_OAUTH_STATE_PATH로 구성 가능). 상태가 지워진 후 재시작 후 커넥터가 실패하면 Claude에서 커넥터를 제거하고 다시 추가하여 재등록하세요.
openrouter_auto_delegate가 모델을 선택하는 방법.env 정책과 호출 요구 사항(require_tools, min_context, 텍스트 출력)으로 카탈로그를 필터링합니다.
모델별 결합 가격을 계산합니다: 0.7·input_price + 0.3·output_price(USD/M 토큰).
티어에 따라 해당 가격대 내에서 검색합니다(비어 있으면 인접 대역으로 폴백):
economy(기본적으로 ≤ $0.5/M): 가장 저렴한 모델.
balanced($0.5–$3/M): 중간 대역에서 가장 저렴한 모델.
quality($3–$15/M): 상한 내에서 가장 높은 가격(플래그십 모델에 도달하지 않으면서 능력의 대용으로 가격 사용).
PREFERRED_PROVIDERS의 공급자를 선호하며, 응답에서 선택된 모델, 이유, 제외된 대안을 보고합니다.
OpenRouter API 키는 서버의 .env에 만 존재합니다. 에이전트에게 절대 노출되지 않습니다.
.env 파일은 .gitignore에 있습니다.
포트가 외부에서 접근 가능한 경우 MCP_AUTH_TOKEN을 설정하고 HTTPS 뒤에서 서비스하세요.
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
SaaS intelligence for AI agents. 5 unified tools cover 1,000+ services with 91-96% token savings.
See, price, and control every tool call your AI agents make: policy checks, cost, and audit tools.
Human-as-a-Service for AI agents. Delegate tasks that need a real human, get results via API.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/vmhq/openrouter-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server