Openrouter Deep Research Mcp

OpenRouter Agents MCP Server

[](https://www.npmjs.com/package/@terminals-tech/openrouter-agents) [](https://spec.modelcontextprotocol.io/specification/2025-11-25/) [](https://github.com/terminals-tech/openrouter-agents)

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](docs/CHANGELOG.md) | [Extensions Guide](docs/EXTENSIONS.md) | [MCP Compliance Report](docs/MCP-COMPLIANCE-REPORT.md)

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](docs/ENV-REFERENCE.md)

.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

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

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

[Full Compliance Report](docs/MCP-COMPLIANCE-REPORT.md)

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

Links

• Homepage: terminals.tech
• npm: @terminals-tech/openrouter-agents
• GitHub: terminals-tech/openrouter-agents
• Docs: [CLAUDE.md](CLAUDE.md) | [Tool Patterns](docs/TOOL-PATTERNS.md) | [Getting Started](docs/GETTING-STARTED.md)

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wheattoast11
• Source: wheattoast11/openrouter-deep-research-mcp
• License: MIT
• Homepage: https://terminals.tech

Install and usage instructions live in the source repository linked above.