How to connect OpenRouter MCP with Python

Compare model quality beyond price using third-party benchmarks. The optional source arg selects the dataset and the result shape: source=artificial-analysis returns intelligence, coding, and agentic index scores; source=design-arena returns head-to-head standings (elo, win rate) filterable by arena and category. Omit source to get results from all sources in one call. Optional task_type (coding, intelligence, agentic) narrows to models suited for that workload.

See what OpenRouter traffic is actually used for: a market-share breakdown by task type (code generation, web search, summarization, ...) over a trailing window, each with its top models by usage, plus macro-category (Code, Data, Agent, General) aggregates. Use to learn which models real usage favors for a given kind of work. All shares are fractions (0-1) of sampled traffic; absolute volumes are not exposed.

Check the remaining account credit balance before running a workload.

See which APPS/products drive the most OpenRouter traffic, filterable by category, to gauge ecosystem adoption and find example use cases. For model rankings use list-daily-model-rankings instead.

See which MODELS are most used and trending by token volume, to pick a proven model. Optionally slice by period (day/week/month), modality, context_bucket, or by category / language_type (sampled weekly estimates). For app/product rankings use list-app-rankings instead.

See which providers serve a given model and at what price, latency, throughput, and data-policy status, to choose routing or debug a slow provider.

Inspect cost, token counts, and serving provider for a specific generation id, to debug spend and routing. send-message returns the generation id of each call in its output.

Submit structured feedback on a specific generation the caller made — a category plus an optional comment. Use after a generation had a problem (wrong or incoherent output, latency, formatting, billing, or an API error) so the OpenRouter team can act on it. Requires the generation id, which get-generation and send-message both return. In the comment, include diagnostic context OpenRouter cannot infer from the generation id: what agent you are and your version, the harness you run in (CLI, desktop app, IDE extension, server SDK), the model you intended to call, what you expected the generation to do, and what it actually did (quote the problematic part of the response if relevant).

Get full details for one model by author/slug (supports :variant suffixes and slug aliases) without fetching the whole catalog. Use this instead of list-models when the model is already known.

List the live OpenRouter model catalog with pricing, context length, modalities, supported parameters, and benchmark scores, to pick a model and wire the right slug into code. Prefer the server-side params over fetching the full list and post-processing. Search/sort: q (free-text name/slug search), sort (pricing-low-to-high/high-to-low, context-high-to-low, throughput-high-to-low, latency-low-to-high, most-popular, top-weekly, newest, intelligence-high-to-low, coding-high-to-low, agentic-high-to-low, design-arena-elo-high-to-low). Filters: category (use case, e.g. programming), min_price/max_price (prompt $/M), min_output_price/max_output_price (completion $/M), context (minimum tokens), min_age_days/max_age_days (model age), min_intelligence_index/max, min_coding_index/max, min_agentic_index/max (Artificial Analysis indices), min_tool_success_rate/max (0-1), arch (model family), model_authors, providers (case-sensitive display names, e.g. Groq), input/output_modalities, supported_parameters, zdr, and region.

List the caller's saved presets (named bundles of model, system prompt, and sampling config created in the OpenRouter dashboard), ordered by most recently updated. Use to discover which presets exist and get their slugs; use get-preset to inspect one preset's full config.

Get one saved preset by slug, including its designated version's config bundle (model, system prompt, temperature, and other sampling parameters), to inspect or reuse that configuration in a request. Find slugs with list-presets.

List available providers to configure allow/deny/routing preferences.

Health-check tool that verifies the MCP connection is alive.

Search the full OpenRouter documentation to answer "how do I…" questions with correct, current API usage. Each result includes a "View docs" link to the source page; if a result is marked truncated or you need the complete page, fetch that link or share it with the user.

Chat with a model and get its plain-text response, to test a prompt or compare models without leaving the editor. Model slug suffixes activate routing variants: ":online" enables web search (e.g. "deepseek/deepseek-v4-pro:online"), ":nitro" prioritizes throughput, ":floor" prioritizes lowest price, ":free" uses a free endpoint if one exists. For normal chats, omit "provider" and let the router choose. Set "provider" to pin the upstream provider only when you need zero variance, such as running evals or reproducing a result.

Generate an image from a text prompt and return it inline. The image is sent back as an image content block: clients that render images (e.g. desktop apps) display it, and the model can see it. This bills the authenticated user for the generation.

Transcribe speech from an audio file to text. Pass exactly one of audio_url (preferred; fetched server-side) or audio_base64. Returns the transcript plus the cost and generation id. This bills the authenticated user. Find STT models via list-models with output_modalities=transcription.

Synthesize speech from text and return it inline as an audio content block (clients that can play audio render it; not all MCP clients can). This bills the authenticated user. Find TTS models via list-models with output_modalities=speech, and each model's voices via get-model (supported_voices). Cost is available afterwards via get-generation.

Get the instructions for running a model eval with Ori, then follow them. Ori runs the user's own agent on their own prompts, on a pinned harness and model, and grades what it did — so a score change means the model changed, not the environment. Call this tool FIRST, before writing any eval code: it returns a step-by-step recipe (install and auth checks, how to spawn `ori code -p`, how to relay Ori's scoping questions to the user, how to report results) that you carry out yourself. Do not hand-roll an eval instead. Use it when the user asks which model they should use, wants to compare or bake off models, wants to measure whether their agent or prompt does the right thing, wants to catch regressions in agent behavior, or asks how good their current model is. Works for any codebase in any language. Do not use it for plain unit tests that involve no model, and do not use it to re-run an eval that already exists (run `ori eval <file>` directly instead). Takes no arguments; the same document is published at https://openrouter.ai/skills/spawn-ori-eval.

Get the hourly uptime history of every provider endpoint serving a model over the last 72 hours — the same per-provider uptime timeline shown on the model page. Use it to find which provider degraded during a window (e.g. "model X was failing between 05:00 and 08:30 UTC — whose uptime dipped?").

Get the instructions for installing and using Ori Harness, then follow them. Call this tool FIRST when the user asks to install Ori, run their existing coding agent CLI through Ori, sign in to Ori, upgrade Ori, or choose an OpenRouter model for a local agent. It returns the complete recipe for installing Ori, signing in with OAuth without an API key, running an agent CLI under Ori, passing any OpenRouter model id with `--model`, upgrading with `ori update`, and verifying the installation. Do not use it for Ori model evaluations, plain unit tests, or when the user only wants to run an already-installed agent directly. Takes no arguments; the same document is published at https://openrouter.ai/skills/install-ori-harness.

Submit many inference requests as one asynchronous batch (Batch API) at discounted batch pricing with results within a 24-hour window. Use it for offline/bulk workloads (evals, backfills, classification over a dataset) that do not need an immediate answer; use send-message for a single interactive reply. Returns the batch id and initial status ("validating"); poll get-batch to follow it to completed/failed and read the results. Completed requests are billed to the authenticated user.

Get the current status of a batch submitted with send-batch: lifecycle state (validating, in_progress, finalizing, completed, failed, expired, cancelling, cancelled), per-request completed/failed counts, the failure reason when the batch failed, and — once the batch is terminal — the inline results keyed by custom_id. Poll it until the status is terminal; batches usually take minutes to hours, so wait between polls rather than looping tightly.

List batches in the workspace of the authenticating API key, newest first, with id, status, model, and per-request completed/failed counts. Use status to narrow to in-flight work (validating, in_progress) and after with the returned last_id to page. List items never include inline results; call get-batch for a single batch to read them.