OpenRouter Agents MCP Server

OpenRouter Agents MCP Server

A Model Context Protocol (MCP) server implementation for OpenRouter that provides sophisticated research agent capabilities. This server allows your conversational LLM to delegate research to a Claude research orchestrator that uses different specialized agents powered by various OpenRouter models.

🚀 New Beta Branch (03-29-2025)

OpenRouter Agents MCP Server Technical Overview

The OpenRouter Agents MCP Server implements a sophisticated orchestration system for AI-powered research. This summary highlights the key technical components and capabilities in the latest beta (03-29-2025).

Core Architecture

• Model Context Protocol (MCP): Full implementation with both STDIO and HTTP/SSE transports
• Multi-Agent Orchestration: Hierarchical system with planning, research, and context agent roles
• Vector Embedding Database: PGLite with pgvector for semantic knowledge storage
• Round-Robin Load Balancing: Distributes research tasks across different models for optimal results
• Adaptive Fallback System: High to low-cost model degradation when primary research fails

Research Capabilities

• Multi-Stage Planning: Claude 3.7 Sonnet decomposes complex queries into specialized sub-questions
• Parallel Execution: Concurrent research across multiple LLMs for comprehensive results
• Context-Aware Refinement: Second-stage planning that identifies and fills gaps in initial research
• Semantic Knowledge Base: Vector search finds relevant past research to enhance new queries
• Adaptive Synthesis: Contextual agent integrates findings with customizable audience levels and formats

Recent Enhancements

• Cross-Model Resilience: Comprehensive error handling keeps research flowing despite individual model failures
• Dynamic Caching: Intelligent TTL and cache optimization based on query complexity
• DB Resilience: Retry logic with exponential backoff for database operations
• Defensive Programming: Null-safe operations throughout the codebase
• Enhanced User Feedback: Rating system with detailed error recovery
• Comprehensive Testing: Verified functionality across all five MCP tools

The beta improves both reliability and research quality through architectural enhancements while maintaining the plug-and-play simplicity of the original implementation. The system seamlessly integrates with Cline in VS Code and Claude Desktop App, providing enterprise-grade research capabilities in a self-contained package.

These improvements deliver a more reliable and powerful research experience while maintaining the server's ease of use. To try the beta version:

🌟 Support This Project

If you find this project helpful, please consider giving it a star on GitHub! Your support helps make this project better.

Your feedback and contributions are always welcome!

Prerequisites

• Node.js (v18 or later recommended) and npm
• Git
• An OpenRouter API key (Get one at https://openrouter.ai/)

Features

• Research planning with Claude 3.7 Sonnet (thinking mode)
• Multiple research agents powered by various OpenRouter LLMs
• Round-robin assignment of models to research tasks
• Configurable cost options (high/low) for different research needs
• Self-contained with no external database dependencies
• In-memory caching for fast response times
• PGLite with vector extension for persistent storage and similarity search

How It Works

1. When you send a research query, the planning agent (Claude 3.7 Sonnet) breaks it down into multiple specialized research questions
2. Each research question is assigned to a different research agent using either high-cost or low-cost LLMs
3. The results from all agents are synthesized into a comprehensive research report
4. Results are cached in memory and stored persistently with embedded vector search capabilities
5. The final contextualized report is returned to you

Installation (Node.js / Standard)

This is the recommended method for integrating with MCP clients like Cline in VS Code.

1. Clone this repository:
   git clone https://github.com/wheattoast11/openrouter-deep-research-mcp.git cd openrouter-agents
2. Install dependencies:
   npm install
3. Create your .env file from the example:
   cp .env.example .env
   (On Windows, you might use copy .env.example .env)
4. Edit the .env file and add your OpenRouter API key:
   OPENROUTER_API_KEY=your_api_key_here
   (Ensure this file is saved in the root directory of the project)

Cline / VS Code MCP Integration (Recommended)

To use this server with Cline in VS Code, you need to add it to your MCP settings file.

1. Locate your Cline MCP settings file:
   • Typically found at: c:\Users\YOUR_USERNAME\AppData\Roaming\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json (Windows) or ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (macOS). Replace YOUR_USERNAME accordingly.
2. Edit the cline_mcp_settings.json file: Add the following configuration object within the main mcpServers object. Make sure to replace "YOUR_PROJECT_PATH_HERE" with the absolute path to where you cloned this repository and "YOUR_OPENROUTER_API_KEY_HERE" with your actual API key.
   { "mcpServers": { // ... potentially other existing servers ... "openrouter-research-agents": { "command": "cmd.exe", "args": [ "/c", "YOUR_PROJECT_PATH_HERE/start-mcp-server.bat" ], "env": { // IMPORTANT: Replace with your actual OpenRouter API Key "OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY_HERE" }, "disabled": false, // Ensure the server is enabled "autoApprove": [ "conduct_research", "research_follow_up", "get_past_research", "rate_research_report", "list_research_history" ] } // ... potentially other existing servers ... } }
   • Why the batch file? Using the batch file ensures the server starts with the proper environment and directory context.
   • Why the API key in env? While the server uses dotenv to load the .env file, providing the key in the env block ensures the server process always has access to it.
3. Save the settings file. Cline should automatically detect the new server configuration. You might need to restart VS Code or the Cline extension if it doesn't appear immediately.

Once configured, you'll see the conduct_research and other research tools available in Cline. You can use them like this:

Or specify a cost preference:

Available Models

High-Cost Models

• perplexity/sonar-deep-research
• perplexity/sonar-pro
• perplexity/sonar-reasoning-pro
• openai/gpt-4o-search-preview

Low-Cost Models

• perplexity/sonar-reasoning
• openai/gpt-4o-mini-search-preview
• google/gemini-2.0-flash-001

Customization

You can customize the available models by editing the .env file:

You can also customize the database and cache settings in the .env file:

Alternative Installation: HTTP/SSE for Claude Desktop App

The server can also be run as a standalone HTTP/SSE service for integration with the Claude Desktop App.

HTTP/SSE Installation Steps

1. Clone this repository (if not already done):
   git clone https://github.com/wheattoast11/openrouter-deep-research-mcp.git cd openrouter-agents
2. Create and configure your .env file as described in the standard installation (Steps 3 & 4).
3. Start the server using npm:
   npm start
4. The MCP server will be running and accessible via HTTP/SSE on http://localhost:3002 (or the port specified in your .env).

Claude Desktop App Integration (HTTP/SSE)

1. Open Claude desktop app.
2. Go to Settings > Developer.
3. Click "Edit Config".
4. Add the following to the mcpServers array in the configuration:
   { "type": "sse", "name": "OpenRouter Research Agents (HTTP)", // Differentiate if also using STDIO "host": "localhost", "port": 3002, // Or your configured port "streamPath": "/sse", "messagePath": "/messages" }
5. Save and restart Claude.

Persistence & Data Storage

This server uses:

• In-memory cache: For efficient response caching (using node-cache)
• PGLite with pgvector: For persistent storage of research reports and vector search capabilities
  • Research reports are stored with vector embeddings for semantic similarity search
  • Vector search is used to find relevant past research for new queries
  • All data is stored locally in the specified data directory (default: './researchAgentDB')

Troubleshooting

• Connection Issues: Ensure Claude's developer settings match the server configuration
• API Key Errors: Verify your OpenRouter API key is correct
• No Agents Found: If planning fails, ensure Claude is parsing the XML correctly
• Model Errors: Check if the specified models are available in your OpenRouter account

Advanced Configuration

The server configuration can be modified in config.js. You can adjust:

• Available models
• Default cost preferences
• Planning agent settings
• Server port and configuration
• Database and cache settings

Authentication Security

As of the latest update, API key authentication is now mandatory by default for HTTP/SSE transport:

1. Set the SERVER_API_KEY environment variable in your .env file for production:
   SERVER_API_KEY=your_secure_api_key_here
2. For development/testing only, you can disable authentication by setting:
   ALLOW_NO_API_KEY=true

This provides enhanced security for production deployments while maintaining flexibility for development and testing.

Testing Tools

The repository includes several testing tools to verify the implementation:

1. Basic Tool Testing:
   test-all-tools.bat
   This script tests all five MCP tools in isolation to verify they are working correctly.
2. MCP Server Testing:
   test-mcp-server.js
   Tests the MCP server implementation including all transport options.
3. Research Agent Testing:
   test-research-agent.js
   Tests the core research agent functionality with actual OpenRouter API calls.

These tools help ensure that all components are functioning correctly after any modifications.

License

MIT