OpenRouter Agents MCP Server

[STATUS UPDATE – 2025-08-26] Dual operational modes configurable via MODE environment variable: - AGENT: Single unified tool (agent) handling routing for research, follow-up queries, data retrieval, and general inquiries. - MANUAL: Discrete, dedicated tools for each specific operational function. - ALL (Default): Combines AGENT functionality with individual tools, supplemented by persistent system utilities.

Operational Flow Schematic

[Persistent Utilities] health_check • query_server_uptime • monitor_job_progress • terminate_session

AGENT MODE User Input → Master Agent → (Investigate | Refine | Fetch Context | Query Data)

Key Capabilities: - Iterative Planning & Execution: Decomposes tasks, initiates concurrent searches with controlled resource allocation, and synthesizes results based on emergent consensus, contradiction analysis, and knowledge gaps. - Dynamic Model Selection: Features a configurable registry supporting leading-edge models including Anthropic Sonnet-4 and the entire OpenAI GPT-5 suite. - Integrated Semantic Knowledge Base: Leverages a persistent local storage layer (PGlite with pgvector) offering integrated management tools (backup, export/import, integrity check, vector index regeneration). - Lightweight Context Acquisition: Includes optimized web interaction utilities for rapid information fetching and page parsing. - Robust Communication: Guarantees resilient data transfer via Server-Sent Events (SSE) streaming, per-client secure authentication, and transparent operational logging.

Deployment & Execution

Dependency Installation: bash npm install @terminals-tech/openrouter-agents
Global Installation (Optional): bash npm install -g @terminals-tech/openrouter-agents
Execution via npx (Zero Install): bash npx @terminals-tech/openrouter-agents --stdio

Alternatively, as a persistent daemon:

SERVER_API_KEY=devkey npx @terminals-tech/openrouter-agents

Latest Release Notes (v1.5.0)

Synchronization of version numbering across npm, GitHub Releases, and Packages.
Implementation of a dual-path publishing mechanism.

View Full Change Log →

Initial Setup Guide

1) Prerequisites: - Runtime Environment: Node.js 18+ (20 LTS highly advised), npm package manager, Git, and a valid OpenRouter API credential.

2) Install Dependencies: bash npm install

3) Configuration (.env file): dotenv OPENROUTER_API_KEY=your_openrouter_key SERVER_API_KEY=your_http_transport_key SERVER_PORT=3002

Operational Mode Selection (default ALL)

AGENT = agent-only interface + persistent utilities

MANUAL = granular tools + persistent utilities

ALL = agent interface + granular tools + persistent utilities

MODE=ALL

Orchestration Tuning

ENSEMBLE_SIZE=2 PARALLELISM=4

Model Configuration (Overrides dynamic discovery)

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

Data Persistence Settings

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

Indexer Service Configuration

INDEXER_ENABLED=true INDEXER_AUTO_INDEX_REPORTS=true INDEXER_AUTO_INDEX_FETCHED=true

MCP Specific Features

MCP_ENABLE_PROMPTS=true MCP_ENABLE_RESOURCES=true

Prompt Formatting Strategy

PROMPTS_COMPACT=true PROMPTS_REQUIRE_URLS=true PROMPTS_CONFIDENCE=true

4) Launch Methods: - For IDE Integration (STDIO): bash node src/server/mcpServer.js --stdio

For Daemon Operation (HTTP/SSE): bash SERVER_API_KEY=$SERVER_API_KEY node src/server/mcpServer.js

Windows PowerShell Launch Examples

STDIO Mode: powershell $env:OPENROUTER_API_KEY='your_key' $env:INDEXER_ENABLED='true' node src/server/mcpServer.js --stdio
HTTP/SSE Daemon: powershell $env:OPENROUTER_API_KEY='your_key' $env:SERVER_API_KEY='devkey' $env:SERVER_PORT='3002' node src/server/mcpServer.js

Single-Line Execution Demos

Daemon (HTTP/SSE): bash SERVER_API_KEY=devkey INDEXER_ENABLED=true node src/server/mcpServer.js

STDIO (IDE): bash OPENROUTER_API_KEY=your_key INDEXER_ENABLED=true node src/server/mcpServer.js --stdio

MCP Client Manifest Configuration (Automatic Server Provisioning)

Registration via JSON manifests simplifies setup in compatible MCP clients.

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

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

If the software is globally available or accessed via npx, MCP clients can launch the service automatically. Consult your client's documentation for manifest file placement (e.g., ~/.config/client/mcp.json).

Core Toolset (High Utility)

Persistent Utilities (All Modes): ping, get_server_status, monitor_job_progress, terminate_session
AGENT Interface: agent (Unified interface for investigation, refinement, context retrieval, and querying)
Granular Toolset (MANUAL/ALL): initiate_investigation (async), execute_research_cycle (sync/stream), provide_followup_context, search (hybrid), fetch_stored_data (index/sql access), execute_query (SQL read-only), fetch_final_summary, enumerate_investigation_log
Job Management: monitor_job_progress, terminate_session
Data Retrieval: search (Fused BM25/vector search with optional LLM re-ranking), fetch_stored_data (database abstraction layer)
Data Querying: execute_query (SELECT operations, optional explain plan)
Knowledge Repository: get_past_research, enumerate_investigation_log, fetch_final_summary
Database Administration: backup_db (creates tar.gz archives), export_reports, import_reports, db_health, reindex_vectors
Model Discovery: list_models
Web Context: search_web, fetch_url
Indexing Engine: index_texts, index_url, search_index, index_status

LLM Tool Interaction Recipes

Consult the tool_patterns resource for optimized JSON sequences, such as: - Web Search → Data Fetching → Research Synthesis - Asynchronous workflow: Submission → Real-time updates via SSE /jobs/:id/events → Final report retrieval

Notes: - Data persistence location defaults to PGLITE_DATA_DIR (i.e., ./researchAgentDB). Backups are stored as compressed archives in ./backups. - Use list_models to dynamically ascertain supported provider capabilities and IDs.

Architecture Schematic

Refer to docs/diagram-architecture.mmd (Mermaid format). Visualization can be generated using Mermaid CLI: bash npx @mermaid-js/mermaid-cli -i docs/diagram-architecture.mmd -o docs/diagram-architecture.svg

Or via the convenience script: bash npm run gen:diagram

If rendering fails in your viewer, open docs/diagram-architecture-branded.svg directly.

Result Synthesis Viewpoint

Distinction from Standard Agent Chains: - Goes beyond fixed sequences; employs dynamic computation of the execution plan, concurrent data gathering, followed by a synthesis step that critically evaluates convergence, discrepancies, and missing information. - Information indexed during research enhances the speed and accuracy of subsequent related queries. - Attention is managed by explicit guardrails: mandatory URL citations, labeling of uncertain findings as [Unverified], and quantifiable confidence metrics.

Token Efficiency Prompting Strategy

Compact Mode: Eliminates verbose preambles, focusing only on crucial operational directives; secondary details are contextually inferred.
Enforced Directives: Strict requirements for verifiable URL citations and confidence assessments; no tolerance for speculative content.
Concise Tool Definitions: Utilizes abbreviated parameter names, relying on server defaults for optional values.

Typical User Scenarios

“Deliver a high-level executive summary detailing the state of MCP technology as of mid-2025.”
System decomposes request, sources validated external data, and constructs a synthesized brief complete with source attribution.
Existing indexed knowledge accelerates refinement iterations.
“Identify models capable of visual processing and devise a robust pathway for image data handling.”
Discovers and filters available models via /models, generates an optimized routing template, with text-only fallbacks established.
“Provide a MECE comparison of bounded parallelism orchestration frameworks (e.g., Temporal, OTel).”
Ingests documentation from relevant frameworks, generating a structured synthesis with actionable code implementation pointers.

Integration with Cursor IDE

Configure this service in Cursor's MCP settings by pointing it to node src/server/mcpServer.js --stdio.
Leverage new prompt templates (planning_prompt, synthesis_prompt) within Cursor to initiate complex scaffolding tasks.

Frequently Asked Questions

How is result fabrication mitigated?
Through rigorous citation mandates, [Unverified] tagging, leveraging prior research context, and automated indexing.
Can features be selectively deactivated?
Yes, via the environment flags detailed previously.
Is data streaming supported?
Yes, via SSE over HTTP and native stdio streams for MCP connections.

Command Reference Map

Initialization (stdio): npm run stdio
Initialization (HTTP/SSE): npm start
Execution via npx (Scoped):
npx @terminals-tech/openrouter-agents --stdio
Example Generation: npm run gen:examples
Model Listing: MCP call list_models { refresh:false }
Asynchronous Investigation Submission: initiate_investigation { target_query:"<query>", resource_priority:"low", target_audience:"intermediate", output_format:"report", include_sources:true }
Job Monitoring: monitor_job_progress { job_id:"..." }, Termination: terminate_session { job_id:"..." }
Unified Information Retrieval: search { term:"<query>", limit:10, context_scope:"both" }
Read-Only SQL: execute_query { sql:"SELECT ... WHERE id = $1", params:[1], explain:true }
Access Historical Work: get_past_research { topic:"<query>", count:5 }
Index External Data (if enabled): index_url { uri:"https://..." }
Local Dashboard (Ghost UI): Navigate to http://localhost:3002/ui to observe job events in real-time via SSE.

Software Distribution Details

Package Identifier: @terminals-tech/openrouter-agents
Current Release: 1.3.2
Executable Entry: openrouter-agents
Originator: Tej Desai admin@terminals.tech
Project Portal: https://terminals.tech

Launch without local cloning: bash npx @terminals-tech/openrouter-agents --stdio

Or for daemon operation:

SERVER_API_KEY=your_key npx @terminals-tech/openrouter-agents

Scoped Publication Steps

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

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

Citation Verification: Strict enforcement of URL sourcing and confidence tagging; ambiguous data flagged as [Unverified].
Cross-Validation: Parallel execution across diverse models; synthesis quantifies agreement versus disagreement among sources.
Knowledge Grounding: Localized hybrid index (BM25/vector) retrieves prior findings for internal cross-referencing.
User Feedback Integration: The rate_research_report { score, rationale } command persists ratings to the DB, directly influencing adaptive follow-up strategies.
Auditability: export_reports and backup_db functions ensure all artifacts are preserved for review.

Run Demonstrations: npm run gen:examples
Review Results: enumerate_investigation_log, fetch_final_summary {reportId}
Provide Rating: rate_research_report { reportId, rating:1..5, comment }
Optimize Retrieval: reindex_vectors, index_status, search_index { query:"..." }

Branded Architecture Visualization

Consult docs/diagram-architecture-branded.svg (Includes corporate branding linking to https://terminals.tech).

openrouter-advanced-research-orchestrator

Author

wheattoast11

Quick Info

Actions

Tags