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)

Related MCP server: Ultimate MCP Server

Install / Run

• Install (project dependency)

• Global install (optional)

• Run with npx (no install)

What's new (v1.7.0 - December 3, 2025)

• Adaptive Tokens: Model-aware token limits using OpenRouter catalog (fixes report truncation)

• Tool Chaining: Recursive tool execution with chain action (max depth: 3)

• Claude Code Integration: One-liner setup, slash commands, and LLM integration guide

• Truncation Detection: Warns when API responses appear cut off mid-sentence

Changelog → | Compliance Report →

Quick start

1. Prereqs

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

2. Install

3. Configure (.env)

4. Run

• STDIO (for Cursor/VS Code MCP):

• HTTP/SSE (local daemon):

Windows PowerShell examples

• STDIO

• HTTP/SSE

One-liner demo scripts

Dev (HTTP/SSE):

STDIO (Cursor/VS Code):

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)

2. HTTP/SSE transport (daemon mode)

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:

Or interactive setup with slash commands and hooks:

Included Slash Commands

Environment Setup

Set your API key before using:

Portable Project Configuration

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

Verification

After setup, verify the connection:

Or use the tools directly:

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:

Or use the script:

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

• Bin: openrouter-agents

• Author: Tej Desai admin@terminals.tech

• Homepage: https://terminals.tech

Install and run without cloning:

Publish (scoped)

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