OpenRouter Tool

Codex plugin for working with the live OpenRouter model catalog.

It provides a dependency-free MCP server plus a Codex skill for finding current models, pulling live prices, resolving model aliases and virtual variants, inspecting provider endpoints, generating SDK setup snippets, producing request scaffolds, planning retry/fallback behavior, checking public rankings, and reading authenticated usage metadata.

This project is not affiliated with OpenRouter.

Features

• Search /api/v1/models by name, provider, modality, supported parameter, context length, price, and free-model status.
• Search by use-case presets such as coding agents, tool calling, structured JSON, long context, cheapest, fastest, high reliability, reasoning, vision, multimodal, and production fallback chains.
• Pull live catalog pricing for all models, including raw API price strings and normalized USD-per-token / USD-per-million-token values.
• Resolve a model by id, canonical slug, display name, latest alias, or virtual variant such as :exacto.
• Inspect provider endpoint metadata, including provider name, status, uptime fields, token limits, quantization, supported parameters, and pricing.
• Generate OpenAI-compatible SDK setup for TypeScript, Python, fetch, and cURL.
• Generate per-model chat request headers for TypeScript, including model, messages, roles, reasoning controls, tool controls, structured output controls, and other supported request parameters.
• Build request scaffolds with request body, HTTP headers, provider routing, fallback models, supported-parameter reporting, retry snippets, router metadata, and docs links.
• Return retry and reliability plans for Retry-After, provider fallbacks, model fallbacks, require_parameters, tool-call recovery, streaming interruption handling, and router metadata.
• Look up curated OpenRouter docs guidance for retries, fallbacks, provider routing, tools, structured outputs, Exacto, router metadata, and app attribution.
• Parse public model pages for visible benchmark mentions, activity buckets, and page sections.
• Parse public ranking pages for daily, weekly, and monthly model token-volume views.
• Read account credit and API-key usage metadata when OPENROUTER_API_KEY has the required permissions.

Plugin Layout

.codex-plugin/plugin.json
.mcp.json
assets/openrouter-models.svg
scripts/openrouter-models-mcp.mjs
scripts/fixture-test.mjs
scripts/smoke-test.mjs
skills/openrouter-models/SKILL.md

Requirements

• Node.js 18 or newer.
• Network access to https://openrouter.ai.
• OPENROUTER_API_KEY for authenticated account and key-usage tools.

Public model search usually works without an API key. Endpoint and account metadata may require authentication depending on OpenRouter policy and account permissions.

Installation In Codex

Use this repository as a local Codex plugin source. A local marketplace entry should point to the plugin root:

{
  "name": "openrouter-models",
  "source": {
    "source": "local",
    "path": "./codex-plugins/openrouter-models"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Developer Tools"
}

The plugin manifest is:

.codex-plugin/plugin.json

The MCP server config is:

.mcp.json

Environment

Set these variables in the Codex/plugin environment when authenticated requests or app attribution are needed:

$env:OPENROUTER_API_KEY = "sk-or-..."
$env:OPENROUTER_SITE_URL = "https://your-app.example"
$env:OPENROUTER_APP_TITLE = "Your App Name"

OPENROUTER_SITE_URL and OPENROUTER_APP_TITLE are used for optional OpenRouter attribution headers:

• HTTP-Referer
• X-OpenRouter-Title
• X-OpenRouter-Categories

Tools

Tool	Purpose
openrouter_search_models	Search the live model catalog with filters.
openrouter_get_model	Resolve one model and optionally include endpoint metadata.
openrouter_model_pricing	Fetch live catalog pricing for all models or selected models.
openrouter_model_profile	Parse a public model page for visible profile data and benchmark mentions.
openrouter_get_model_endpoints	Fetch provider endpoint metadata for one model.
openrouter_sdk_config	Generate SDK transport headers and OpenAI-compatible setup snippets.
openrouter_model_request_headers	Generate per-model chat request headers from live supported parameters.
openrouter_model_resolve	Resolve ids, canonical slugs, latest aliases, and virtual variants such as :exacto.
openrouter_request_scaffold	Build a runnable request scaffold with model fallbacks, provider routing, supported parameters, and retry snippets.
openrouter_reliability_plan	Return retry/fallback/tool-call/streaming reliability guidance.
openrouter_docs_lookup	Look up concise curated docs guidance and official OpenRouter links.
openrouter_account_usage	Read authenticated credits and API-key usage metadata.
openrouter_rankings	Parse public ranking pages for model token-volume views.

Header Types

The plugin separates two commonly confused concepts.

SDK Transport Headers

Use openrouter_sdk_config for HTTP/auth/attribution setup:

• Authorization
• Content-Type
• HTTP-Referer
• X-OpenRouter-Title
• X-OpenRouter-Categories

In OpenAI-compatible SDKs, Authorization is handled through the SDK apiKey option. Attribution headers belong in defaultHeaders.

Per-Model Request Headers

Use openrouter_model_request_headers for chat request-body scaffolds:

• model
• messages
• role structure
• context/modality notes
• reasoning and include_reasoning, when supported
• tools and tool_choice, when supported
• response_format and structured output controls, when supported
• other supported parameters from the live model catalog

If a prompt asks for "SDK headers for models" without specifying transport headers, the skill should return both sections or label the chosen interpretation.

For new runnable requests, prefer openrouter_request_scaffold. It returns the request URL, HTTP headers, chat body, provider block, model fallback chain, supported-parameter report, retry snippet, and docs links in one result.

Pricing

Use openrouter_model_pricing when a task needs current model costs.

The tool returns:

• pricing_raw: exact price strings from the live OpenRouter catalog response.
• pricing_per_unit_usd: parsed numeric values using the same units as the raw catalog fields.
• token_prices_per_million_usd: token-priced fields multiplied by 1,000,000.
• unit_prices_usd: unit-priced fields such as request, image, and web search costs.
• pricing_field_basis: explicit classification for known token and unit fields.
• other_prices_usd: parsed numeric prices for currently unknown or newly introduced fields.

Token-priced fields include:

• prompt
• completion
• internal_reasoning
• input_cache_read
• input_cache_write

Unit-priced fields include:

• request
• image
• web_search

Fields not in those known sets are preserved and labeled with pricing_field_basis: "unknown" rather than being silently treated as token or unit prices.

Provider-specific endpoint prices can differ from catalog-level prices. Use openrouter_get_model_endpoints when the task needs per-provider pricing for a specific model.

free_only filtering is conservative. A model counts as free when the id contains :free or both prompt and completion prices are exactly zero. Null or omitted prices are not treated as free.

Verification

Run from the plugin root:

node --check .\scripts\openrouter-models-mcp.mjs
node --check .\scripts\smoke-test.mjs
node --check .\scripts\fixture-test.mjs
node .\scripts\openrouter-models-mcp.mjs --self-test
node .\scripts\smoke-test.mjs
node .\scripts\fixture-test.mjs

Run live catalog and pricing checks:

node .\scripts\smoke-test.mjs --live

If the live check fails in a sandboxed Codex shell, the MCP error now reports the target URL, cause metadata when Node exposes it, and the network-approval hint. The same command should pass when the shell has approved network access to https://openrouter.ai.

The server has no npm package dependencies.

Data Handling

• Public catalog, endpoint, profile, and ranking tools request data from OpenRouter.
• Account usage tools require OPENROUTER_API_KEY.
• The plugin does not store account responses on disk.
• In-memory model/catalog cache entries expire after a short TTL.
• Public ranking and model-page activity data are OpenRouter-wide. They are not private account usage.
• usage_daily, usage_weekly, and usage_monthly from key endpoints are credit usage values, not token counts.
• Per-generation token counts come from normal chat completion responses under usage.

License

MIT. See LICENSE.