# Openrouterai

> MCP server for OpenRouter.ai integration

- **Type:** MCP server
- **Install:** `agentstack add mcp-heltonteixeira-openrouterai`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [heltonteixeira](https://agentstack.voostack.com/s/heltonteixeira)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [heltonteixeira](https://github.com/heltonteixeira)
- **Source:** https://github.com/heltonteixeira/openrouterai

## Install

```sh
agentstack add mcp-heltonteixeira-openrouterai
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# OpenRouter MCP Server

[](https://github.com/heltonteixeira/openrouterai)
[](CHANGELOG.md)
[](https://www.typescriptlang.org/)
[](LICENSE)

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

```bash
pnpm install @mcpservers/openrouterai
```

## Configuration

### Prerequisites

1.  Get your OpenRouter API key from [OpenRouter Keys](https://openrouter.ai/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)

```env
# 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;
}
```

**Success Example:**
```json
{
  "isError": false,
  "content": [{
    "type": "text",
    "text": "{\"id\": \"gen-123\", ...}"
  }]
}
```

**Error Example:**
```json
{
  "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:**

```json
{
  "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:

```typescript
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:

```typescript
{
  model: string;           // Model identifier
}
```

### validate_model

Check if a model ID is valid:

```typescript
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:

```typescript
// 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:**
```typescript
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](CONTRIBUTING.md) for detailed information about:
- Development setup
- Project structure
- Feature implementation
- Error handling guidelines
- Tool usage examples

```bash
# Install dependencies
pnpm install

# Build project
pnpm run build

# Run tests
pnpm test
```

## Changelog
See [CHANGELOG.md](./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](LICENSE) file for details.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [heltonteixeira](https://github.com/heltonteixeira)
- **Source:** [heltonteixeira/openrouterai](https://github.com/heltonteixeira/openrouterai)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-heltonteixeira-openrouterai
- Seller: https://agentstack.voostack.com/s/heltonteixeira
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.