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

Full Changelog | Extensions Guide | MCP Compliance Report

Configuration

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

Full ENV Reference

.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

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

Client-Specific Setup

Jan AI

1. Enable MCP Servers in Settings → Advanced → Experimental

2. Click + to add server

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

Models (v2.0.0)

High-Cost Tier

Low-Cost Tier

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

Tools

Research

Knowledge Base

Session & Graph

Rail Protocol

Utility

MCP Compliance

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

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

Circuit Breaker

Protects against cascading model API failures. Configurable via environment:

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

Transport (v2.0.0)

Links

• Homepage: terminals.tech
• npm: @terminals-tech/openrouter-agents
• GitHub: terminals-tech/openrouter-agents
• Docs: CLAUDE.md | Tool Patterns | Getting Started

Releasing

Releases are automated via release-please:

1. Push conventional commits to main (e.g. feat:, fix:, chore:)

2. release-please opens a version-bump PR

3. Merge the PR → GitHub Release created automatically

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