@orcarouter/mcp

OrcaRouter MCP Server

Official MCP server for the OrcaRouter LLM gateway.

Browse OrcaRouter's model catalog and run chat completions from inside any Model Context Protocol client — Claude Desktop, Claude Code, Cursor, Windsurf, Zed, or anything else that speaks the protocol.

Catalog browsing works without an API key — compare pricing and capabilities before signing up.

What you can do

• 🗺️ Discover providers and models without an API key
• 💬 Run chat completions through any served model
• 🧠 Auto-route requests through your workspace's orcarouter/auto router (cost / quality / balanced / LinUCB / gated-adaptive strategies)
• 🔁 Configure fallback chains (primary + up to 4 fallbacks) for resilience
• 📊 Filter models server-side by provider, capability, or minimum context window
• 🎯 Inspect detailed model cards: pricing, context, latency, supported endpoints
• 🔌 Works with Claude Desktop, Claude Code, Cursor, Windsurf, Zed, and any MCP client

Examples

You: What's the cheapest 200k-context model on OrcaRouter right now?

Claude: Calls orcarouter_models_list with min_context: 200000, sorts the returned JSON by pricing.prompt_per_million, and lists the three cheapest 200k+ context models.

You: Run this prompt through google/gemini-2.5-pro.

Claude: Calls orcarouter_chat with that model and returns Gemini's response.

More prompts to try:

• "Which providers does OrcaRouter currently serve?"
• "Show me all Anthropic models with their pricing"
• "Find chat models with at least 1M context"
• "Use orcarouter/auto to summarize this article in one paragraph"

Quick Start

Claude Code (CLI one-liner)

claude mcp add orcarouter -s user \
  -e ORCAROUTER_API_KEY=sk-orca-your-key \
  -- npx -y @orcarouter/mcp

Other clients (config-file path)

• Copy the example config for your MCP client into the client's config file:

  Client	Example	Action
  Claude Desktop	claude-desktop.json	Replace
  Claude Code	claude-code.json	Merge
  Cursor	cursor.json	Replace
  Windsurf	windsurf.json	Replace

  See examples/README.md for the config-file paths and notes on Zed and other clients.

• Replace sk-or-... in the copied file with your OrcaRouter API key.

• Restart your MCP client.

Requires Node.js 18 or later. The ORCAROUTER_API_KEY env var is only required for orcarouter_chat; catalog tools work without it.

Tools

• orcarouter_chat — run a chat completion (with optional fallback chain)
• orcarouter_models_list — browse the catalog (pricing, context, capabilities)
• orcarouter_model_card — detailed info for one model
• orcarouter_providers_list — list available providers with model counts and display info

Configuration

Name	Required	Description
ORCAROUTER_API_KEY	optional	OrcaRouter API key. Required only for orcarouter_chat.
ORCAROUTER_BASE_URL	optional	API base URL. Defaults to https://api.orcarouter.ai.
ORCAROUTER_REQUEST_TIMEOUT	optional	Per-request HTTP timeout in seconds. Defaults to 60.

Tool Reference

Full input/output schemas are exposed at runtime via the MCP tools/list method. Each summary below shows a minimal invocation.

orcarouter_chat

Send a single-turn chat request through OrcaRouter. Required input: prompt. Everything else is optional with sensible defaults.

Defaults: model: "orcarouter/auto" (your workspace's seeded auto-router), max_tokens: 2000, temperature: 0.7. For OpenAI reasoning models (gpt-5, o1, o3, o4 series) max_tokens is automatically translated to max_completion_tokens at the wire level — you never need to think about it.

Optional models array (1–5 entries) defines a fallback chain: the primary model always runs first; subsequent entries are tried only if the previous one fails.

Minimal:

{ "prompt": "Hello" }

With an explicit model and system prompt:

{
  "model": "openai/gpt-4o-mini",
  "prompt": "Summarize the Treaty of Westphalia in one sentence.",
  "system_prompt": "Be concise."
}

orcarouter_models_list

Lists available models. Works without an API key. Returns a one-line summary followed by a JSON array with id, name, context_length, pricing, supported_endpoint_types, and more. Optional filters (applied server-side): provider, capability (chat / embedding / image / audio), min_context.

{ "provider": "openai", "min_context": 128000 }

orcarouter_model_card

Detailed info for a single model — display name, description, context window, pricing, latency percentiles, supported endpoints. Works without an API key. The model input should be the exact id value returned by orcarouter_models_list (typically provider/slug form, e.g. openai/gpt-4o-mini).

{ "model": "openai/gpt-4o-mini" }

orcarouter_providers_list

Lists all model providers on OrcaRouter with their model counts and display metadata. Works without an API key. Useful for discovering provider ids (e.g. openai, anthropic) to pass to orcarouter_models_list as the provider filter.

{}

Security

API keys are read from environment variables, never logged, and only sent to the OrcaRouter API. See SECURITY.md for the vulnerability disclosure policy.

Development

# bun (preferred)
bun install
bun run test
bun run typecheck
bun run build

# or with npm
npm install
npm test
npm run typecheck
npm run build

The build produces an ESM bundle at dist/index.js with a #!/usr/bin/env node shebang, runnable as the orcarouter-mcp binary.

License

MIT