OpenRouter Agents MCP Server

npm MCP Stable GitHub

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).

Full Changelog | Extensions Guide | MCP Compliance Report

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

Full ENV Reference

{
  "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

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.

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-..."
      }
    }
  }
}

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

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)

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

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

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

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

Full Compliance Report

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)

States: closed (normal) -> open (failing, requests rejected) -> half-open (testing recovery).

Transport (v2.0.0)

Transport	Status	Use Case
Streamable HTTP	Primary	All new integrations
SSE	Deprecated	Legacy compatibility only
STDIO	Default	MCP clients (Claude, Jan AI, Continue)

Releasing

Releases are automated via release-please:

Push conventional commits to main (e.g. feat:, fix:, chore:)
release-please opens a version-bump PR
Merge the PR → GitHub Release created automatically
npm publish triggers on release via CI

Manual publish:

npm test && npm publish --access public

Version: 2.0.0 | MCP SDK: 1.27.1 | MCP Spec: 2025-11-25 | Author: Tej Desai | License: MIT