OpenRouter MCP: Setup, Model Calls, and Real Trade-Offs

OpenRouter MCP is a hosted Model Context Protocol server for researching and testing models: an agent can inspect live prices, benchmarks, endpoints, and documentation before you commit to a model. It is not a replacement for the OpenRouter API in production.

The short answer: what OpenRouter MCP changes

The official server is available at https://mcp.openrouter.ai/mcp. A compatible client such as Claude Code, Cursor, or Claude Desktop connects over remote HTTP, allowing the agent to call OpenRouter tools inside the conversation. It helps the agent research and test the catalog; a production API or provider-owned MCP still handles the work that belongs in an application or a provider account.

OpenRouter's official announcement describes live model data, rankings, prices, documentation, and test inference. The MCP documentation is the source for the endpoint, tools, and authentication behavior.

Start with the workflow, not the server URL

The most useful pattern is discover, compare, test, inspect. It turns “What is the best model?” into a decision with explicit constraints.

1. Discover: ask for models that meet a task, price, context, modality, or provider requirement. Use list-models and list-benchmarks for current catalog and benchmark data.
2. Compare: call list-model-endpoints for each candidate to see provider-level price, latency, throughput, and data-policy information where available.
3. Test: run the same prompt with send-message and a named model slug. This can incur an inference charge.
4. Inspect: pass each generation ID to get-generation for token counts, cost, and serving provider.

Use this prompt in Claude Code or Cursor:

Use OpenRouter MCP to find three models for extracting structured data from
legal documents. Requirements: at least 100k context, tool calling, and the
lowest available input price. Compare providers and data policies. Then use
send-message to run this exact prompt against the best two candidates:

"Extract every contract renewal date from the text below. Return only JSON
with an array named renewals, each item containing party, date, and evidence."

After the tests, use get-generation for each generation ID and report the
actual cost and serving provider. Do not call a model until I approve the
candidates.

Require approval before the test because catalog searches are read-only while send-message can incur an inference charge. For repeatable evaluations, use an explicit model and provider; suffixes such as :free, :floor, :nitro, and :online express routing preferences where available, not fixed quality guarantees.

Connect the official remote server

There is nothing to install locally. Add the remote endpoint, complete browser-based OAuth, and authorize a dedicated OpenRouter key separate from your other keys. The documented default is a 7-day expiry and a $10 spend cap, editable on the approval screen. OpenRouter documents OAuth with PKCE, so you authorize in a browser instead of pasting a normal API key into the client configuration.

Claude Code

Run:

claude mcp add --transport http openrouter https://mcp.openrouter.ai/mcp
claude mcp login openrouter

The first command registers the remote HTTP server; the second opens the OAuth flow. Inside a Claude Code session, the Claude Code MCP documentation also supports /mcp: select the OpenRouter server and authenticate.

Test the connection with a read-only request such as: “Use OpenRouter MCP to list two current models with at least 128k context and show their input prices.”

Cursor

Add the remote server to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "openrouter": {
      "url": "https://mcp.openrouter.ai/mcp"
    }
  }
}

Reload Cursor if the server does not appear. Authentication starts from Cursor's MCP settings or on first tool use. The documented CLI is cursor-agent; verify the entry with:

cursor-agent mcp list

Cursor's MCP documentation explains its user-level and project-level configuration. Put the entry at the level where you need it and do not commit a personal authentication configuration to a shared repository.

Claude Desktop and Claude Web

If OpenRouter is not in Claude's connector directory, OpenRouter's connection guide directs users to add a custom remote connector:

1. Open Settings > Connectors > Customize > Connectors.
2. Click +, then choose Add custom connector.
3. Name it OpenRouter MCP.
4. Enter https://mcp.openrouter.ai/mcp as the remote MCP server URL.
5. Leave OAuth fields blank, add the connector, open it, and click Connect.
6. Complete the OpenRouter browser approval.

Some organizations disable custom connectors. If the option is missing in a managed account, check with the administrator. Anthropic's MCP documentation covers the client-side protocol concepts.

What you can safely ask it to do

Most official OpenRouter MCP tools are live lookups. Grouping them by side effect is more useful than memorizing the full inventory.

For selection, state the decision rule: “Find the lowest-cost model with tool calling and a 64k context window, then show the fastest available endpoint.” Documented filters include price, minimum context, model family, author, provider, modality, supported parameters, benchmark ranges, tool-calling success rate, zero-data-retention availability, and region.

For a controlled model test, name a slug and make the prompt reproducible:

Use OpenRouter MCP send-message with model "openai/gpt-4o".
Send exactly this user message and do not add a system prompt:

"Return a JSON object with keys title and risks. Analyze this release note:
[paste text here]"

Show me the response and the generation ID. Do not run another model.

The slug is illustrative; use one that list-models confirms is available. For auditable comparisons, explicitly require the lookup tools, returned values, and a generation ID instead of accepting an unsupported model recommendation.

OpenRouter MCP versus official provider MCP servers

OpenRouter MCP is a cross-provider intelligence and testing layer. An official provider MCP is usually better when the action belongs to that provider's product, account, or data plane.

Choose OpenRouter MCP when the question is “Which model or route should I use?” Choose a first-party provider MCP when the question is “What can I do inside this provider's service?” They can be connected to the same agent when both capabilities are needed.

Community-built local or multimodal MCP servers are a separate category. OpenRouter's Works With OpenRouter page describes one server for several clients and text, image, audio, and video workflows; it requires an OpenRouter API key and credits, and is not the official hosted service at mcp.openrouter.ai.

The boundaries that matter in a real project

“@OpenRouter’s ori harness/cli has been a blessing... p.s: also thanks for openrouter mcp for quickly checking up info on models 🫰” — @CodewithP, X, describing a model-information lookup use case.

OpenRouter's MCP cookbook also covers the reverse direction: using OpenRouter models as the LLM backend for other MCP tool servers, rather than connecting a coding client to OpenRouter MCP.

Troubleshoot the first failed call

1. The server appears but tools fail authentication. Re-run the client-specific OAuth step. The dedicated key has a documented 7-day lifetime and can also be disconnected from the OpenRouter dashboard.
2. No browser window opens. Use claude mcp login openrouter, Claude Code's /mcp action, Cursor's MCP settings, or the Claude connector's Connect button.
3. Claude Desktop has no custom connector option. Check whether an organization administrator has disabled custom connectors.
4. A model answer looks stale. Explicitly ask for list-models, list-benchmarks, or list-model-endpoints, and require the returned values.
5. A test costs more or routes differently than expected. Inspect its generation ID with get-generation, then pin an explicit provider for the next reproducibility run.

FAQ

Can OpenRouter MCP call any OpenRouter model?

It can test model slugs exposed by the live catalog, subject to availability, capabilities, credit, and routing constraints. Confirm the slug with list-models first.

Can I use OpenRouter MCP with Claude Desktop, Cursor, and Claude Code at the same time?

You can add the same official endpoint in each client, using each client's documented configuration and authentication flow. Keep shared configuration free of personal credentials.

Should I install a community openrouter-mcp package instead?

Only if you need a local stdio workflow or multimodal orchestration that the official hosted server does not provide. Verify the repository, credential handling, package source, and maintenance status first.

Start with a read-only catalog query; authorize a controlled inference call only after the model, route, and spend boundary are clear.