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
- Prereqs
- Node 18+ (20 LTS recommended), npm, Git, OpenRouter API key
- Install
npm install
- 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
- 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
- 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:
- 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"
}
}
}
}
- 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, optionalexplain) - 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_modelsto 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.”
/modelsdiscovered 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/uito 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_dbcapture 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 tohttps://terminals.tech).