What is Openrouterai

OpenRouter.ai is an MCP server designed to facilitate seamless integration with a variety of AI models within the OpenRouter.ai ecosystem, providing a unified interface for accessing these models.

Use cases

Use cases for OpenRouter.ai include building AI-driven applications, conducting model searches, validating model capabilities, and integrating various AI functionalities into existing systems.

How to use

To use OpenRouter.ai, install the package via npm, obtain an API key from OpenRouter, and configure your MCP settings with the necessary parameters including your API key and optional default model.

Key features

Key features include direct access to all OpenRouter.ai models, automatic model validation, performance optimization with caching and rate limiting, and robust error handling with detailed messages.

Where to use

undefined

OpenRouter MCP Server

A Model Context Protocol (MCP) server providing seamless integration with OpenRouter.ai’s diverse model ecosystem. Access various AI models through a unified, type-safe interface with built-in caching, rate limiting, and error handling.

Features

• Model Access

  • Direct access to all OpenRouter.ai models
  • Automatic model validation and capability checking
  • Default model configuration support

• Performance Optimization

  • Smart model information caching (1-hour expiry)
  • Automatic rate limit management
  • Exponential backoff for failed requests

• Unified Response Format

  • Consistent ToolResult structure for all responses
  • Clear error identification with isError flag
  • Structured error messages with context

Installation

pnpm install @mcpservers/openrouterai

Configuration

Prerequisites

1. Get your OpenRouter API key from OpenRouter Keys
2. Choose a default model (optional)

Environment Variables

• OPENROUTER_API_KEY: Required. Your OpenRouter API key.
• OPENROUTER_DEFAULT_MODEL: Optional. The default model to use if not specified in the request (e.g., openrouter/auto).
• OPENROUTER_MAX_TOKENS: Optional. Default maximum number of tokens to generate if max_tokens is not provided in the request.
• OPENROUTER_PROVIDER_QUANTIZATIONS: Optional. Comma-separated list of default quantization levels to filter by (e.g., fp16,int8) if provider.quantizations is not provided in the request. (Phase 1)
• OPENROUTER_PROVIDER_IGNORE: Optional. Comma-separated list of default provider names to ignore (e.g., mistralai,openai) if provider.ignore is not provided in the request. (Phase 1)
• OPENROUTER_PROVIDER_SORT: Optional. Default sort order for providers (“price”, “throughput”, or “latency”). Overridden by provider.sort argument. (Phase 2)
• OPENROUTER_PROVIDER_ORDER: Optional. Default prioritized list of provider IDs (JSON array string, e.g., '["openai/gpt-4o", "anthropic/claude-3-opus"]'). Overridden by provider.order argument. (Phase 2)
• OPENROUTER_PROVIDER_REQUIRE_PARAMETERS: Optional. Default boolean (true or false) to only use providers supporting all specified request parameters. Overridden by provider.require_parameters argument. (Phase 2)
• OPENROUTER_PROVIDER_DATA_COLLECTION: Optional. Default data collection policy (“allow” or “deny”). Overridden by provider.data_collection argument. (Phase 2)
• OPENROUTER_PROVIDER_ALLOW_FALLBACKS: Optional. Default boolean (true or false) to control fallback behavior if preferred providers fail. Overridden by provider.allow_fallbacks argument. (Phase 2)

# Example .env file content
OPENROUTER_API_KEY=your-api-key-here
OPENROUTER_DEFAULT_MODEL=openrouter/auto
OPENROUTER_MAX_TOKENS=1024
OPENROUTER_PROVIDER_QUANTIZATIONS=fp16,int8
OPENROUTER_PROVIDER_IGNORE=openai,anthropic
OPENROUTER_PROVIDER_SORT=price
OPENROUTER_PROVIDER_ORDER='["openai/gpt-4o", "anthropic/claude-3-opus"]'
OPENROUTER_PROVIDER_REQUIRE_PARAMETERS=true
OPENROUTER_PROVIDER_DATA_COLLECTION=deny
OPENROUTER_PROVIDER_ALLOW_FALLBACKS=false

OPENROUTER_PROVIDER_QUANTIZATIONS=fp16,int8
OPENROUTER_PROVIDER_IGNORE=openai,anthropic

### Setup

Add to your MCP settings configuration file (`cline_mcp_settings.json` or `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "openrouterai": {
      "command": "npx",
      "args": ["@mcpservers/openrouterai"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here",
        "OPENROUTER_DEFAULT_MODEL": "optional-default-model",
        "OPENROUTER_MAX_TOKENS": "1024",
        "OPENROUTER_PROVIDER_QUANTIZATIONS": "fp16,int8",
        "OPENROUTER_PROVIDER_IGNORE": "openai,anthropic"
      }
    }
  }
}

## Response Format

All tools return responses in a standardized structure:

```typescript
interface ToolResult {
  isError: boolean;
  content: Array<{
    type: "text";
    text: string; // JSON string or error message
  }>;
}

Success Example:

{
  "isError": false,
  "content": [
    {
      "type": "text",
      "text": "{\"id\": \"gen-123\", ...}"
    }
  ]
}

Error Example:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error: Model validation failed - 'invalid-model' not found"
    }
  ]
}

Available Tools

chat_completion

Sends a request to the OpenRouter Chat Completions API.

Input Schema:

• model (string, optional): The model to use (e.g., openai/gpt-4o, google/gemini-pro). Overrides OPENROUTER_DEFAULT_MODEL. Defaults to openrouter/auto if neither is set.
  • Model Suffixes: You can append :nitro to a model ID (e.g., openai/gpt-4o:nitro) to potentially route to faster, experimental versions if available. Append :floor (e.g., mistralai/mistral-7b-instruct:floor) to use the cheapest available variant of a model, often useful for testing or low-cost tasks. Note: Availability of :nitro and :floor variants depends on OpenRouter.
• messages (array, required): An array of message objects conforming to the OpenAI chat completion format.
• temperature (number, optional): Sampling temperature. Defaults to 1.
• max_tokens (number, optional): Maximum number of tokens to generate in the completion. Overrides OPENROUTER_MAX_TOKENS.
• provider (object, optional): Provider routing configuration. Overrides corresponding OPENROUTER_PROVIDER_* environment variables.
  • quantizations (array of strings, optional): List of quantization levels to filter by (e.g., ["fp16", "int8"]). Only models matching one of these levels will be considered. Overrides OPENROUTER_PROVIDER_QUANTIZATIONS. (Phase 1)
  • ignore (array of strings, optional): List of provider names to exclude (e.g., ["openai", "anthropic"]). Models from these providers will not be used. Overrides OPENROUTER_PROVIDER_IGNORE. (Phase 1)
  • sort (“price” | “throughput” | “latency”, optional): Sort providers by the specified criteria. Overrides OPENROUTER_PROVIDER_SORT. (Phase 2)
  • order (array of strings, optional): A prioritized list of provider IDs (e.g., ["openai/gpt-4o", "anthropic/claude-3-opus"]). Overrides OPENROUTER_PROVIDER_ORDER. (Phase 2)
  • require_parameters (boolean, optional): If true, only use providers that support all specified request parameters (like tools, functions, temperature). Overrides OPENROUTER_PROVIDER_REQUIRE_PARAMETERS. (Phase 2)
  • data_collection (“allow” | “deny”, optional): Specify whether providers are allowed to collect data from the request. Overrides OPENROUTER_PROVIDER_DATA_COLLECTION. (Phase 2)
  • allow_fallbacks (boolean, optional): If true (default), allows falling back to other providers if the preferred ones fail or are unavailable. If false, fails the request if preferred providers cannot be used. Overrides OPENROUTER_PROVIDER_ALLOW_FALLBACKS. (Phase 2)

Example Usage:

{
  "tool": "chat_completion",
  "arguments": {
    "model": "anthropic/claude-3-haiku",
    "messages": [
      {
        "role": "user",
        "content": "Explain the concept of quantization in AI models."
      }
    ],
    "max_tokens": 500,
    "provider": {
      "quantizations": [
        "fp16"
      ],
      "ignore": [
        "openai"
      ],
      "sort": "price",
      "order": [
        "anthropic/claude-3-haiku",
        "google/gemini-pro"
      ],
      "require_parameters": true,
      "allow_fallbacks": false
    }
  }
}

This example requests a completion from anthropic/claude-3-haiku, limits the response to 500 tokens. It specifies provider routing options: prefer fp16 quantized models, ignore openai providers, sort remaining providers by price, prioritize anthropic/claude-3-haiku then google/gemini-pro, require the chosen provider to support all request parameters (like max_tokens), and disable fallbacks (fail if the prioritized providers cannot fulfill the request).

search_models

Search and filter available models:

interface ModelSearchRequest {
  query?: string;
  provider?: string;
  minContextLength?: number;
  capabilities?: {
    functions?: boolean;
    vision?: boolean;
  };
}

// Response: ToolResult with model list or error

get_model_info

Get detailed information about a specific model:

{
  model: string;           // Model identifier
}

validate_model

Check if a model ID is valid:

interface ModelValidationRequest {
  model: string;
}

// Response: 
// Success: { isError: false, valid: true }
// Error: { isError: true, error: "Model not found" }

Error Handling

The server provides structured errors with contextual information:

// Error response structure
{
  isError: true,
  content: [{
    type: "text",
    text: "Error: [Category] - Detailed message"
  }]
}

Common Error Categories:

• Validation Error: Invalid input parameters
• API Error: OpenRouter API communication issues
• Rate Limit: Request throttling detection
• Internal Error: Server-side processing failures

Handling Responses:

async function handleResponse(result: ToolResult) {
  if (result.isError) {
    const errorMessage = result.content[0].text;
    if (errorMessage.startsWith('Error: Rate Limit')) {
      // Handle rate limiting
    }
    // Other error handling
  } else {
    const data = JSON.parse(result.content[0].text);
    // Process successful response
  }
}

Development

See CONTRIBUTING.md for detailed information about:

• Development setup
• Project structure
• Feature implementation
• Error handling guidelines
• Tool usage examples

# Install dependencies
pnpm install

# Build project
pnpm run build

# Run tests
pnpm test

Changelog

See CHANGELOG.md for recent updates including:

• Unified response format implementation
• Enhanced error handling system
• Type-safe interface improvements

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.