OpenRouter Agents MCP Server

What is OpenRouter Agents MCP Server about?

OpenRouter Agents MCP Server provides a production‑ready environment for multi‑agent AI research. It coordinates planning, parallel execution, and synthesis of tasks across a fleet of LLMs, stores every interaction in a local PGlite DB, and offers hybrid BM25‑vector search, SQL querying, and resource management.

How to use OpenRouter Agents MCP Server?

1. Install – No local cloning needed; run the packaged CLI with npx:

   npx @terminals-tech/openrouter-agents --stdio   # for IDE integration
   # or daemon mode
   SERVER_API_KEY=devkey npx @terminals-tech/openrouter-agents
   

2. Configure – Provide an .env (solo) or .mcp.json (team) with keys such as OPENROUTER_API_KEY, SERVER_API_KEY, and optional flags (MODE, ENSEMBLE_SIZE, PGLITE_DATA_DIR, etc.).
3. Interact – Use MCP‑compatible clients (Cursor, VS Code, Claude, etc.) or direct HTTP/SSE endpoints (/sse, /messages). Available slash commands include /mcp-status, /mcp-research, /mcp-search, and /mcp-query.
4. Monitor – Check job status via get_job_status, cancel with cancel_job, and retrieve reports through get_report_content.

Key features of OpenRouter Agents MCP Server

• Multi‑Agent Orchestration – Plan → parallelize → synthesize with adaptive concurrency.
• Async Job System – SSE streaming for long‑running research tasks.
• Hybrid Knowledge Base – BM25 + pgvector indexing via PGlite in WebAssembly.
• Dynamic Model Catalog – Supports Anthropic Sonnet‑4, OpenAI GPT‑5, Google Gemini 2.5, and many low‑cost alternatives.
• MCP Compliance – Full spec conformance, discovery metadata, and extension hooks.
• Three Operating Modes – AGENT, MANUAL, ALL for flexible tool exposure.
• Built‑in UI Resources – Mini UI endpoints (ui://research/viewer, ui://knowledge/graph).
• Session Time‑Travel – Undo/redo, forks, checkpoints.
• Robust Security – Rate limiting, request size caps, JWT/API‑key auth.
• Extensible Toolset – Search, retrieve, SQL query, web fetch, indexing, model listing, and more.

Use cases of OpenRouter Agents MCP Server

• Academic literature surveys – Parallel agents crawl papers, extract citations, and synthesize a report with confidence scores.
• Tech scouting – Compare orchestration frameworks, retrieve official docs, and generate code snippets.
• Market research – Run asynchronous web fetches, index results, and produce executive briefings.
• Model benchmarking – Dispatch the same task to multiple LLMs, collect responses, and evaluate consensus.
• Knowledge‑base augmentation – Continuously ingest new URLs, re‑index vectors, and make past research instantly searchable.

FAQ from the OpenRouter Agents MCP Server

Q: Do I need to run a database separately? A: No. All data is stored in an embedded PGlite instance that runs in WebAssembly; the directory is configurable via PGLITE_DATA_DIR.

Q: Can I disable the hybrid indexer? A: Yes. Set INDEXER_ENABLED=false in the environment or .mcp.json.

Q: How are costs managed across models? A: The server categorizes models into HIGH_COST_MODELS, LOW_COST_MODELS, etc., and the planning step selects appropriate candidates based on the cost parameter of the request.

Q: Is streaming supported for IDE integration? A: Absolutely. Use the --stdio mode for Cursor/VS Code MCP clients or the HTTP/SSE endpoint for external tools.

Q: What authentication is required? A: Provide an OpenRouter API key (OPENROUTER_API_KEY) for model access and a server‑side key (SERVER_API_KEY) for client authentication.

Q: Can I run the server globally without cloning the repo? A: Yes. The npx command pulls the package directly from npm and launches the server.

OpenRouter Agents MCP Server

Overview

Production-ready MCP server for multi-agent AI research with OpenRouter integration. Fully compliant with MCP Specification 2025-06-18 and prepared for November 2025 spec updates.

Key Features

• Multi-Agent Orchestration: Plan → parallelize → synthesize workflow with adaptive concurrency
• Async Operations: Job system with SSE streaming for long-running research tasks
• Knowledge Base: Hybrid BM25+vector search with PGlite + pgvector
• Model Support: Dynamic catalog supporting Anthropic Sonnet-4, OpenAI GPT-5, Google Gemini, and more
• Production Hardened: Rate limiting, request size limits, multi-tier auth (JWT/API key)
• MCP Compliant: 100% spec compliance with server discovery and extension metadata
• Three Modes: AGENT (simple), MANUAL (granular), or ALL (both)

Install / Run

• Install (project dependency)

npm install @terminals-tech/openrouter-agents

• Global install (optional)

npm install -g @terminals-tech/openrouter-agents

• Run with npx (no install)

npx @terminals-tech/openrouter-agents --stdio
# or daemon
SERVER_API_KEY=devkey npx @terminals-tech/openrouter-agents

What's New (v1.8.0 - December 5, 2025)

• MCP Apps (SEP-1865): UI resources for autonomous interface surfacing (ui://research/viewer, ui://knowledge/graph)
• Knowledge Graph: New tools for graph exploration - graph_traverse, graph_path, graph_clusters, graph_pagerank
• Session Time-Travel: Undo/redo, fork sessions, checkpoints, and time navigation via @terminals-tech/core
• Error Visibility: Structured error handling with cause chains, pre-flight validation, and detailed diagnostics
• Package Ecosystem: Integrated @terminals-tech/embeddings, @terminals-tech/graph, @terminals-tech/core

Changelog → | Compliance Report →

Quick start

1. Prereqs

• Node 18+ (20 LTS recommended), npm, Git, OpenRouter API key

2. Install

npm install

3. Verify installation (optional but recommended)

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

Configuration: .env vs .mcp.json

Choose your configuration method based on your use case:

Are you working alone or with a team?
│
├─ ALONE (local development)
│   │
│   └─► Use .env file
│       • Keeps secrets out of version control
│       • Personal API keys stay private
│       • Add .env to .gitignore
│
└─ TEAM (shared project)
    │
    └─► Use .mcp.json file
        • Commit to version control
        • Use ${VAR} syntax for secrets
        • Team shares same configuration
        • Each member sets own env vars

Quick Decision:

• .env → Solo developer, local machine, prototype
• .mcp.json → Team project, CI/CD, shareable config

4. Configure (.env)

OPENROUTER_API_KEY=your_openrouter_key
SERVER_API_KEY=your_http_transport_key
SERVER_PORT=3002

# Modes (pick one; default ALL)
# AGENT  = agent-only + always-on ops (ping/status/jobs)
# MANUAL = individual tools + always-on ops
# ALL    = agent + individual tools + always-on ops
MODE=ALL

# Orchestration
ENSEMBLE_SIZE=2
PARALLELISM=4

# Models (override as needed) - Updated with state-of-the-art cost-effective models
PLANNING_MODEL=openai/gpt-5-chat
PLANNING_CANDIDATES=openai/gpt-5-chat,google/gemini-2.5-pro,anthropic/claude-sonnet-4
HIGH_COST_MODELS=x-ai/grok-4,openai/gpt-5-chat,google/gemini-2.5-pro,anthropic/claude-sonnet-4,morph/morph-v3-large
LOW_COST_MODELS=deepseek/deepseek-chat-v3.1,z-ai/glm-4.5v,qwen/qwen3-coder,openai/gpt-5-mini,google/gemini-2.5-flash
VERY_LOW_COST_MODELS=openai/gpt-5-nano,deepseek/deepseek-chat-v3.1

# Storage
PGLITE_DATA_DIR=./researchAgentDB
PGLITE_RELAXED_DURABILITY=true
REPORT_OUTPUT_PATH=./research_outputs/

# Indexer
INDEXER_ENABLED=true
INDEXER_AUTO_INDEX_REPORTS=true
INDEXER_AUTO_INDEX_FETCHED=true

# MCP features
MCP_ENABLE_PROMPTS=true
MCP_ENABLE_RESOURCES=true

# Prompt strategy
PROMPTS_COMPACT=true
PROMPTS_REQUIRE_URLS=true
PROMPTS_CONFIDENCE=true

4. Run

• STDIO (for Cursor/VS Code MCP):

node src/server/mcpServer.js --stdio

• HTTP/SSE (local daemon):

SERVER_API_KEY=$SERVER_API_KEY node src/server/mcpServer.js

Windows PowerShell examples

• STDIO

$env:OPENROUTER_API_KEY='your_key'
$env:INDEXER_ENABLED='true'
node src/server/mcpServer.js --stdio

• HTTP/SSE

$env:OPENROUTER_API_KEY='your_key'
$env:SERVER_API_KEY='devkey'
$env:SERVER_PORT='3002'
node src/server/mcpServer.js

One-liner demo scripts

Dev (HTTP/SSE):

SERVER_API_KEY=devkey INDEXER_ENABLED=true node src/server/mcpServer.js

STDIO (Cursor/VS Code):

OPENROUTER_API_KEY=your_key INDEXER_ENABLED=true node src/server/mcpServer.js --stdio

MCP client JSON configuration (no manual start required)

You can register this server directly in MCP clients that support JSON server manifests.

Minimal examples:

1. STDIO transport (recommended for IDEs)

{
  "servers": {
    "openrouter-agents": {
      "command": "npx",
      "args": ["@terminals-tech/openrouter-agents", "--stdio"],
      "env": {
        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
        "SERVER_API_KEY": "${SERVER_API_KEY}",
        "PGLITE_DATA_DIR": "./researchAgentDB",
        "INDEXER_ENABLED": "true"
      }
    }
  }
}

2. HTTP/SSE transport (daemon mode)

{
  "servers": {
    "openrouter-agents": {
      "url": "http://127.0.0.1:3002",
      "sse": "/sse",
      "messages": "/messages",
      "headers": {
        "Authorization": "Bearer ${SERVER_API_KEY}"
      }
    }
  }
}

With the package installed globally (or via npx), MCP clients can spawn the server automatically. See your client's docs for where to place this JSON (e.g., ~/.config/client/mcp.json).

Claude Code Integration

One-liner setup for Claude Code:

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

Or interactive setup with slash commands and hooks:

npx @terminals-tech/openrouter-agents --setup-claude

Included Slash Commands

Command	Description
/mcp-status	Check server health and recent activity
/mcp-research	Run synchronous research query
/mcp-async-research	Run async research (returns job_id)
/mcp-search	Search the knowledge base
/mcp-query	Execute SQL query

Environment Setup

Set your API key before using:

export OPENROUTER_API_KEY="sk-or-..."

Portable Project Configuration

The setup creates a .mcp.json file for team-shareable configuration:

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

Verification

After setup, verify the connection:

/mcp-status

Or use the tools directly:

ping {}                    // → {"pong":true}
get_server_status {}       // → Full health check
list_tools {}              // → Available tools

See .claude/README.md for detailed configuration options.

Tools (high‑value)

• Always‑on (all modes): ping, get_server_status, job_status, get_job_status, cancel_job
• AGENT: agent (single entrypoint for research / follow_up / retrieve / query)
• MANUAL/ALL toolset: submit_research (async), conduct_research (sync/stream), research_follow_up, search (hybrid), retrieve (index/sql), query (SELECT), get_report_content, list_research_history
• Jobs: get_job_status, cancel_job
• Retrieval: search (hybrid BM25+vector with optional LLM rerank), retrieve (index/sql wrapper)
• SQL: query (SELECT‑only, optional explain)
• Knowledge base: get_past_research, list_research_history, get_report_content
• DB ops: backup_db (tar.gz), export_reports, import_reports, db_health, reindex_vectors
• Models: list_models
• Web: search_web, fetch_url
• Indexer: index_texts, index_url, search_index, index_status

Tool usage patterns (for LLMs)

Use tool_patterns resource to view JSON recipes describing effective chaining, e.g.:

• Search → Fetch → Research
• Async research: submit, stream via SSE /jobs/:id/events, then get report content

Notes

• Data lives locally under PGLITE_DATA_DIR (default ./researchAgentDB). Backups are tarballs in ./backups.
• Use list_models to discover current provider capabilities and ids.

Architecture at a glance

See docs/diagram-architecture.mmd (Mermaid). Render to SVG with Mermaid CLI if installed:

npx @mermaid-js/mermaid-cli -i docs/diagram-architecture.mmd -o docs/diagram-architecture.svg

Or use the script:

npm run gen:diagram

If the image doesn’t render in your viewer, open docs/diagram-architecture-branded.svg directly.

Answer crystallization view

How it differs from typical “agent chains”:

• Not just hardcoded handoffs; the plan is computed, then parallel agents search, then a synthesis step reasons over consensus, contradictions, and gaps.
• The system indexes what it reads during research, so subsequent queries get faster/smarter.
• Guardrails shape attention: explicit URL citations, [Unverified] labelling, and confidence scoring.

Minimal‑token prompt strategy

• Compact mode strips preambles to essential constraints; everything else is inferred.
• Enforced rules: explicit URL citations, no guessing IDs/URLs, confidence labels.
• Short tool specs: use concise param names and rely on server defaults.

Common user journeys

• “Give me an executive briefing on MCP status as of July 2025.”

  • Server plans sub‑queries, fetches authoritative sources, synthesizes with citations.
  • Indexed outputs make related follow‑ups faster.

• “Find vision‑capable models and route images gracefully.”

  • /models discovered and filtered, router template generated, fallback to text models.

• “Compare orchestration patterns for bounded parallelism.”

  • Pulls OTel/Airflow/Temporal docs, produces a MECE synthesis and code pointers.

Cursor IDE usage

• Add this server in Cursor MCP settings pointing to node src/server/mcpServer.js --stdio.
• Use the new prompts (planning_prompt, synthesis_prompt) directly in Cursor to scaffold tasks.

FAQ (quick glance)

• How does it avoid hallucinations?
  • Strict citation rules, [Unverified] labels, retrieval of past work, on‑the‑fly indexing.
• Can I disable features?
  • Yes, via env flags listed above.
• Does it support streaming?
  • Yes, SSE for HTTP; stdio for MCP.

Command Map (quick reference)

• Start (stdio): npm run stdio
• Start (HTTP/SSE): npm start
• Run via npx (scoped): npx @terminals-tech/openrouter-agents --stdio
• Generate examples: npm run gen:examples
• List models: MCP list_models { refresh:false }
• Submit research (async): submit_research { q:"<query>", cost:"low", aud:"intermediate", fmt:"report", src:true }
• Track job: get_job_status { job_id:"..." }, cancel: cancel_job { job_id:"..." }
• Unified search: search { q:"<query>", k:10, scope:"both" }
• SQL (read‑only): query { sql:"SELECT ... WHERE id = $1", params:[1], explain:true }
• Get past research: get_past_research { query:"<query>", limit:5 }
• Index URL (if enabled): index_url { url:"https://..." }
• Micro UI (ghost): visit http://localhost:3002/ui to stream job events (SSE).

Package publishing

• Name: @terminals-tech/openrouter-agents
• Version: 1.8.0
• Bin: openrouter-agents
• Author: Tej Desai admin@terminals.tech
• Homepage: https://terminals.tech

Install and run without cloning:

npx @terminals-tech/openrouter-agents --stdio
# or daemon
SERVER_API_KEY=your_key npx @terminals-tech/openrouter-agents

Publish (scoped)

npm login
npm version patch -m "chore(release): %s"
git push --follow-tags
npm publish --access public --provenance

Validation – MSeeP (Multi‑Source Evidence & Evaluation Protocol)

• Citations enforced: explicit URLs, confidence tags; unknowns marked [Unverified].
• Cross‑model triangulation: plan fans out to multiple models; synthesis scores consensus vs contradictions.
• KB grounding: local hybrid index (BM25+vector) retrieves past work for cross‑checking.
• Human feedback: rate_research_report { rating, comment } stored to DB; drives follow‑ups.
• Reproducibility: export_reports + backup_db capture artifacts for audit.

Quality feedback loop

• Run examples: npm run gen:examples
• Review: list_research_history, get_report_content {reportId}
• Rate: rate_research_report { reportId, rating:1..5, comment }
• Improve retrieval: reindex_vectors, index_status, search_index { query }

Architecture diagram (branded)

• See docs/diagram-architecture-branded.svg (logo links to https://terminals.tech).

Stargazers