Configuring OpenRouter

Relevant source files

The following files were used as context for generating this wiki page:

• providers/openrouter.py
• conf/openrouter_models.json
• tests/test_openrouter_provider.py
• README.md
• conf/CLAUDE.md
• AGENTS.md

The OpenRouter provider acts as an aggregation layer, allowing the Zen MCP Server to access a wide variety of AI models from different sources through a single, unified API. This integration simplifies model management by providing a consistent interface and a centralized point for API key configuration.

By enabling OpenRouter, users can leverage dozens of models without needing to manage separate API keys and configurations for each individual provider. The Zen MCP server activates the OpenRouter provider automatically if the corresponding API key is found in the environment configuration.

Sources: README.md, providers/openrouter.py

Enabling the Provider

To enable the OpenRouter provider, you must add your OpenRouter API key to the .env file or your MCP client configuration (e.g., ~/.claude/settings.json). The server detects the presence of the OPENROUTER_API_KEY and automatically activates the provider.

Sources: README.md, AGENTS.md

The following diagram illustrates the provider activation flow.

Architecture and Data Flow

The OpenRouterProvider class, located in providers/openrouter.py, is responsible for all interactions with the OpenRouter API. It handles fetching model capabilities and invoking model completions.

Key Components

Component	File	Description
OpenRouterProvider	providers/openrouter.py	The main class that implements the provider logic, including fetching capabilities and invoking models.
openrouter_models.json	conf/openrouter_models.json	A JSON configuration file that defines the metadata for all models available through OpenRouter.
test_openrouter_provider.py	tests/test_openrouter_provider.py	Unit tests for the OpenRouter provider, ensuring its functionality.

Sources: providers/openrouter.py, conf/openrouter_models.json, tests/test_openrouter_provider.py

Model Capability Loading

When the Zen MCP server starts, the OpenRouterProvider's get_capabilities method is called. This method reads the openrouter_models.json file to load the metadata for all available models, such as context window size, pricing, and supported features.

This flow is depicted in the diagram below.

Model Configuration

All models accessible via OpenRouter are defined in conf/openrouter_models.json. Each model is an object within a larger JSON object, keyed by its unique identifier.

Model Definition Schema

The structure for defining a model is as follows:

Field	Type	Description
name	string	The unique identifier for the model used in API calls.
display_name	string	A user-friendly name for the model.
context_window	integer	The maximum number of tokens in the model's context window.
max_output_tokens	integer	The maximum number of tokens the model can generate in a single response.
supports_vision	boolean	Indicates if the model can process image inputs.
supports_functions	boolean	Indicates if the model supports function calling.
pricing	object	Contains pricing information for input and output tokens.
input_tokens	float	Cost per input token.
output_tokens	float	Cost per output token.

Sources: conf/openrouter_models.json, conf/CLAUDE.md

Example Model Definition

Here is an example of a model definition from conf/openrouter_models.json.

{
  "google/gemini-flash-1.5": {
    "name": "google/gemini-flash-1.5",
    "display_name": "Google Gemini Flash 1.5",
    "context_window": 1048576,
    "max_output_tokens": 8192,
    "supports_vision": true,
    "supports_functions": true,
    "pricing": {
      "input_tokens": 3.5e-07,
      "output_tokens": 7e-07
    }
  }
}

Sources: conf/openrouter_models.json

Summary

Configuring OpenRouter within the Zen MCP Server is a straightforward process that unlocks access to a vast array of AI models. By setting a single API key, the server automatically loads the provider and its associated model definitions from the conf/openrouter_models.json file. This modular design, centered around the OpenRouterProvider class, provides a scalable and easy-to-maintain way to integrate multiple models into the Zen MCP ecosystem.

Sources: README.md, providers/openrouter.py, conf/openrouter_models.json