OpenRouter Agents by wheattoast11 - MCP Server

OpenRouter Agents MCP Server

Production MCP server for multi-agent AI research. Plan, parallelize, synthesize.

Install

npx @terminals-tech/openrouter-agents --stdio

Claude Code one-liner:

claude mcp add openrouter-agents -- npx @terminals-tech/openrouter-agents --stdio

What's New (v2.0.0)

MCP SDK 1.27.1 — registerTool/registerPrompt/registerResource APIs, security fixes
Zod 4 — Upgraded from Zod 3; z.record() syntax, config schema fixes
Express 5 — Upgraded from Express 4; modern path patterns, req.query handling
Streamable HTTP — Primary transport (SSE deprecated as legacy fallback)
Circuit breaker — Model API fault tolerance with configurable thresholds
Embedding-based model routing — Local vector similarity for model selection (no LLM call)
Persistent storage — Reports, jobs, knowledge graph persist across sessions by default

macOS/Node 25 Note: A cosmetic libc++abi: mutex lock failed message may appear on shutdown. This is harmless — data is checkpointed before shutdown. Set DB_AUTO_HEAL=true for in-memory mode (no persistence, no message).

| |

Configuration

Set OPENROUTER_API_KEY in your environment, then configure via .env or .mcp.json:

Variable	Default	Description
`OPENROUTER_API_KEY`	required	OpenRouter API key
`OPENROUTER_API_KEYS`	(optional)	Comma-separated OpenRouter keys for rotation
`OPENROUTER_KEY_COOLDOWN_MS`	`5000`	Base cooldown per key after failures
`SERVER_PORT`	`3002`	HTTP server port
`MODE`	`ALL`	`AGENT`, `MANUAL`, or `ALL`
`EMBEDDING_ROUTING_ENABLED`	`true`	Enable embedding-based model routing
`INDEXER_ENABLED`	`true`	Enable knowledge indexing

.mcp.json example (team-shareable)

{
  "mcpServers": {
    "openrouter-agents": {
      "command": "npx",
      "args": ["@terminals-tech/openrouter-agents", "--stdio"],
      "env": {
        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
        "INDEXER_ENABLED": "true"
      }
    }
  }
}

Multi-Client Setup

Transport Modes

Transport	Flag	Use Case
STDIO	(default)	MCP clients (Claude, Jan AI, Continue)
HTTP	`--http`	Web apps, shared server

STDIO is the default transport per MCP spec. Use --http explicitly for HTTP mode.

Client-Specific Setup

Jan AI

Enable MCP Servers in Settings → Advanced → Experimental
Click + to add server
Configure:
- Name: openrouter-agents
- Command: npx
- Arguments: @terminals-tech/openrouter-agents
- Environment: OPENROUTER_API_KEY=sk-or-...

Note: STDIO is now default - no --stdio flag needed.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "openrouter-agents": {
      "command": "npx",
      "args": ["@terminals-tech/openrouter-agents"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

Continue / Zed / Other MCP Clients

Standard MCP config - STDIO is default, no flags needed:

{
  "command": "npx",
  "args": ["@terminals-tech/openrouter-agents"],
  "env": { "OPENROUTER_API_KEY": "..." }
}

Feature Matrix

Feature	All MCP Clients	Claude Code Only
Core Research Tools	✓	✓
Knowledge Base	✓	✓
Session/Graph Tools	✓	✓
Rail Protocol Tools	✓	✓
Slash Commands	-	✓

Models (v2.0.0)

High-Cost Tier

Model	Domains
`anthropic/claude-sonnet-4.5`	reasoning, technical, general, creative
`anthropic/claude-opus-4.6`	reasoning, technical, general, creative
`openai/gpt-5.2-chat`	reasoning, technical, general
`openai/gpt-5.3-codex`	coding, technical, reasoning
`google/gemini-3-pro-preview`	reasoning, technical, general
`qwen/qwen3-coder`	coding, editing, technical

Low-Cost Tier

Model	Domains
`google/gemini-3-flash-preview`	coding, editing, technical
`anthropic/claude-haiku-4.5`	general, technical, reasoning
`deepseek/deepseek-chat-v3.1`	general, reasoning, technical, coding
`deepseek/deepseek-v3.2`	general, reasoning, technical, coding
`openai/gpt-oss-120b`	general, reasoning, search

Models are selected via embedding-based routing — query embeddings are matched to model domain profiles without an LLM call.

Tools

Research

Tool	Description
`research`	Async research (returns job_id)
`conduct_research`	Sync research with streaming
`batch_research`	Parallel batch queries
`research_follow_up`	Context-aware follow-up
`agent`	Unified entrypoint (auto-routes)

Knowledge Base

Tool	Description
`search`	Hybrid BM25+vector search
`retrieve`	Index or SQL query
`query`	SQL SELECT with params
`get_report`	Get report by ID
`history`	List recent reports

Session & Graph

Tool	Description
`undo` / `redo`	Session time-travel
`checkpoint`	Named save points
`fork_session`	Create alternate timeline
`graph_traverse`	Explore knowledge graph
`graph_clusters`	Find node clusters
`graph_pagerank`	Importance rankings

Rail Protocol

Tool	Description
`list_rails`	List rails, tunnels, routes, consensus
`explain_rail`	Detailed rail/tunnel config
`list_routes`	All defined routes
`list_tunnels`	Active agent-to-agent tunnels
`list_consensus`	Streaming consensus sessions

Utility

Tool	Description
`ping`	Health check
`get_server_status`	Full diagnostics
`job_status`	Check async job
`date_time`	Current timestamp
`calc`	Math evaluation
`list_tools`	Available tools

MCP Compliance

Compliant with MCP Specification 2025-11-25 (stable, AAIF/Linux Foundation governance).

Feature	SEP	Status
JSON-RPC 2.0	Core	Compliant
Tools/Resources/Prompts	Core	Compliant
Task Protocol	SEP-1686	Compliant
Sampling with Tools	SEP-1577	Compliant
Elicitation	SEP-1036	Compliant
MCP Apps	SEP-1865	Compliant
Enterprise Auth	SEP-990	Compliant
Client Metadata	SEP-991	Compliant

Architecture

User Query
    │
    ▼
┌─────────────────┐
│  Planning Agent  │ ─── Decomposes into sub-queries
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────┐
│Agent 1│ │Agent N│ ─── Parallel research (embedding-routed models)
└───┬───┘ └───┬───┘
    │         │
    ▼         ▼
┌─────────────────┐
│   Synthesizer   │ ─── Consensus + citations (Signal protocol)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Knowledge Base  │ ─── PGlite + pgvector (persistent)
└─────────────────┘

Core Abstractions

Module	Purpose
Signal Protocol	Inter-agent communication with confidence scoring and consensus
Rail Protocol	Bidirectional channels with backpressure, provenance, tunnels
Error Taxonomy	Deterministic classification with auto-learning and circuit breakers
Circuit Breaker	Model API fault tolerance with configurable thresholds and auto-recovery
Parameter Normalization	Declarative alias system (`q`→`query`, `cost`→`costPreference`)
RoleShift Protocol	Bidirectional server↔client via MCP sampling/elicitation
Embedding Router	Local vector-based model selection via `@terminals-tech/embeddings`

Circuit Breaker

Protects against cascading model API failures. Configurable via environment:

Variable	Default	Description
`RAIL_CIRCUIT_BREAKER`	`true`	Enable circuit breaker
`RAIL_CIRCUIT_THRESHOLD`	`5`	Failures before tripping
`RAIL_CIRCUIT_RESET_MS`	`120000`	Recovery timeout (ms)