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 (v1.9.1)

• Parameter normalization - Unified alias system (taskId → job_id, q → query)
• Semantic error messages - Rust-style diagnostics with actionable suggestions
• Progress notifications - Real-time job updates via MCP notifications/progress
• Token-efficient slash commands - Streamlined Claude Code integrations

Full Changelog | 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 | | SERVER_PORT | 3002 | HTTP server port | | MODE | ALL | AGENT, MANUAL, or ALL | | PGLITE_DATA_DIR | ./researchAgentDB | Database location | | 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

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.

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 | ✓ | ✓ | | Slash Commands | - | ✓ | | Zero CLI | - | standalone |

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

| Feature | Spec | Status | |---------|------|--------| | JSON-RPC 2.0 | Core | Compliant | | Tools/Resources/Prompts | 2025-06-18 | Compliant | | Task Protocol (SEP-1686) | Draft | Implemented | | Sampling (SEP-1577) | Draft | Implemented | | Elicitation (SEP-1036) | Draft | Implemented | | MCP Apps (SEP-1865) | Draft | Implemented | | Enterprise Auth (SEP-990) | Draft | Implemented | | Client Metadata (SEP-991) | Draft | Implemented |

Architecture

User Query
    │
    ▼
┌─────────────────┐
│  Planning Agent │ ─── Decomposes into sub-queries
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────┐
│Agent 1│ │Agent N│ ─── Parallel research
└───┬───┘ └───┬───┘
    │         │
    ▼         ▼
┌─────────────────┐
│   Synthesizer   │ ─── Consensus + citations
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Knowledge Base │ ─── PGlite + pgvector
└─────────────────┘

Links

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

Publishing

npm test                           # Run unit tests
npm version minor                  # Bump version
git push --follow-tags             # Push with tags
npm publish --access public        # Publish to npm

Version: 1.9.1 | Author: Tej Desai | License: MIT