OpenRouter Agents

You are equipped with a production-ready MCP Server for OpenRouter‑driven multi‑agent research. It orchestrates planning, parallel execution, and synthesis across agents, with streaming job results, a knowledge base, and a robust security model. This guide shows you how to install, configure, and run the server locally or as part of a team workflow, and how to connect MCP clients to leverage its orchestration and retrieval capabilities.

How to use

You connect an MCP client to the OpenRouter Deep Research MCP Server to plan research tasks, run asynchronous experiments, and query the knowledge base. The server supports multiple modes: AGENT for a streamlined agent, MANUAL for granular tool control, or ALL for both. Use the client to submit research, monitor jobs, fetch results, and search the hybrid knowledge base (BM25 + vector index). You can stream long‑running results via SSE for real‑time feedback and attach checkpoints or versions to your sessions for reproducibility.

How to install

Prerequisites and initial setup are straightforward. You’ll need Node.js, npm, and an OpenRouter API key. Then you install the MCP server package, run it, and, if desired, verify the installation before you begin active usage.

# Prerequisites
Install Node.js (18+ is recommended).

# Install the MCP server package locally
npm install @terminals-tech/openrouter-agents

# Optional: install globally for easy access
npm install -g @terminals-tech/openrouter-agents

# Run server in stdio mode for your editor or IDE integration
npx @terminals-tech/openrouter-agents --stdio

# Or run as a daemon with an API key
SERVER_API_KEY=devkey npx @terminals-tech/openrouter-agents

Configuration and running tips

Choose your configuration method based on whether you are working solo or as part of a team. Use a local .env file for personal keys and rapid prototyping, or a shared .mcp.json file for team collaboration and CI/CD workflows.

# .env example for solo development
OPENROUTER_API_KEY=your_openrouter_key
SERVER_API_KEY=your_http_transport_key
SERVER_PORT=3002

# Modes
MODE=ALL

# Orchestration
ENSEMBLE_SIZE=2
PARALLELISM=4

# Models (override as needed)
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 and indexer
PGLITE_DATA_DIR=./researchAgentDB
PGLITE_RELAXED_DURABILITY=true
REPORT_OUTPUT_PATH=./research_outputs/
INDEXER_ENABLED=true
INDEXER_AUTO_INDEX_REPORTS=true
INDEXER_AUTO_INDEX_FETCHED=true

# MCP features and prompts
MCP_ENABLE_PROMPTS=true
MCP_ENABLE_RESOURCES=true
PROMPTS_COMPACT=true
PROMPTS_REQUIRE_URLS=true
PROMPTS_CONFIDENCE=true

Notes, tips, and troubleshooting

Data stays local by default under the configured data directory. Backups are tarballs stored in the backups folder. Use the provided tooling to index, search, and retrieve from the knowledge base, and to manage jobs and reports.

To help clients integrate smoothly, you can expose a minimal MCP client manifest that points at the local stdio server for IDEs or use a daemon endpoint with a URL and SSE streams. The server supports a suite of tools for planning, researching, and querying, plus a knowledge base with hybrid indexing.

Security and reliability

Security is reinforced through multi‑tier authentication, request size limits, and rate limiting. The system emphasizes explicit citations, confidence scoring, and [Unverified] labels when applicable. Long tasks can stream results, and structured errors provide diagnostics to help you fix issues quickly.

If you need to recover from a faulty state, you can export reports, backup the database, and reindex vectors to ensure your knowledge base remains current and reliable for future queries.

Available tools

ping

Always-on tool to check server responsiveness and reachability.

get_server_status

Return a full health check and recent status of the MCP server.

job_status

Check the status of an asynchronous job by its job_id.

get_job_status

Query the status of a running or completed job.

cancel_job

Cancel an in-progress job by its job_id.

agent

Single entrypoint for initiating an autonomous research task or follow-up action.

submit_research

Submit a research task asynchronously for later processing.

conduct_research

Run a research operation synchronously or stream results.

research_follow_up

Perform follow-up research based on prior results.

search

Search the knowledge base with a hybrid index and optional reranking.

retrieve

Retrieve indexed documents or results from the knowledge base.

query

Execute a SELECT-style query against the knowledge base or indexed data.

get_report_content

Read the content of a generated research report.

list_research_history

List historical research activities and outcomes.

backup_db

Create a tar.gz backup of the database.

export_reports

Export generated reports for external use.

import_reports

Import external reports into the knowledge base.

db_health

Check database health and integrity.

reindex_vectors

Rebuild or update vector indexes for improved retrieval.

list_models

List available models and capabilities in use by the server.

search_web

Search the web for source material to support research.

fetch_url

Fetch a URL content for inclusion in a knowledge graph.

index_texts

Index a set of texts into the knowledge base.

index_url

Index content from a URL into the knowledge base.

index_status

Check the status of indexing tasks.