OpenRouter MCP: configuração, chamadas de modelo e os trade-offs reais

O OpenRouter MCP é um servidor hospedado de Model Context Protocol voltado à pesquisa e aos testes de modelos. Ele permite que um agente consulte preços atualizados, benchmarks, endpoints e documentação antes de você escolher um modelo. Não é, porém, um substituto para a API do OpenRouter em produção.

Em que o OpenRouter MCP realmente ajuda

O servidor oficial está disponível em https://mcp.openrouter.ai/mcp. Clientes compatíveis, como Claude Code, Cursor e Claude Desktop, podem se conectar a ele por HTTP remoto e acionar as ferramentas do OpenRouter durante a conversa. A ideia é pesquisar o catálogo e experimentar modelos; para o tráfego da sua aplicação ou operações ligadas a uma conta de provedor, continuam valendo a API de produção ou o MCP oficial daquele provedor.

O anúncio oficial do OpenRouter cita dados de modelos em tempo real, rankings, preços, documentação e inferência para testes. A documentação do MCP é a referência para endpoint, ferramentas e comportamento de autenticação.

Defina o fluxo antes de configurar o servidor

O padrão mais útil é descobrir, comparar, testar e inspecionar. Assim, a pergunta “qual é o melhor modelo?” vira uma decisão baseada em restrições explícitas.

1. Descubra opções: peça modelos que atendam aos requisitos de tarefa, preço, contexto, modalidade ou provedor. Use list-models e list-benchmarks para consultar o catálogo e os benchmarks atuais.
2. Compare: execute list-model-endpoints para cada candidato e veja preço por provedor, latência, throughput e informações de política de dados quando disponíveis.
3. Teste: envie o mesmo prompt com send-message e um slug de modelo definido. Isso pode gerar custo de inferência.
4. Inspecione: passe cada ID de geração para get-generation e confira contagem de tokens, custo e provedor que serviu a requisição.

Use este prompt no Claude Code ou Cursor:

Use o OpenRouter MCP para encontrar três modelos para extrair dados estruturados de
documentos jurídicos. Requisitos: pelo menos 100k de contexto, tool calling e o
menor preço de entrada disponível. Compare provedores e políticas de dados. Depois,
use send-message para executar exatamente este prompt nos dois melhores candidatos:

"Extraia todas as datas de renovação contratual do texto abaixo. Retorne apenas JSON
com um array chamado renewals, e cada item deve conter party, date e evidence."

Após os testes, use get-generation para cada ID de geração e informe o custo real
e o provedor que atendeu a chamada. Não chame nenhum modelo antes da minha aprovação.

Exija aprovação antes do teste: pesquisas no catálogo são somente leitura, mas send-message pode gerar cobrança de inferência. Para avaliações reproduzíveis, especifique um modelo e um provedor. Sufixos como :free, :floor, :nitro e :online indicam preferências de roteamento quando disponíveis, não garantias fixas de qualidade.

Como conectar o servidor remoto oficial

Não há nada para instalar localmente. Basta adicionar o endpoint remoto, concluir o OAuth no navegador e autorizar uma chave dedicada do OpenRouter, separada das demais chaves. O padrão documentado é validade de 7 dias e limite de gasto de $10, ambos editáveis na tela de aprovação. O OpenRouter documenta OAuth com PKCE: em vez de colar uma API key comum na configuração do cliente, você autoriza o acesso pelo navegador.

Claude Code

Execute:

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

O primeiro comando registra o servidor HTTP remoto; o segundo abre o fluxo OAuth. Em uma sessão do Claude Code, a documentação de MCP do Claude Code também permite usar /mcp: selecione o servidor OpenRouter e autentique-se.

Teste a conexão com uma solicitação somente leitura, por exemplo: “Use o OpenRouter MCP para listar dois modelos atuais com pelo menos 128k de contexto e mostrar seus preços de entrada.”

Cursor

Adicione o servidor remoto a ~/.cursor/mcp.json:

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

Recarregue o Cursor se o servidor não aparecer. A autenticação começa nas configurações de MCP do Cursor ou no primeiro uso de uma ferramenta. A CLI documentada é cursor-agent; confira a entrada com:

cursor-agent mcp list

A documentação de MCP do Cursor explica as configurações em nível de usuário e de projeto. Coloque a entrada no nível necessário e não faça commit de uma configuração de autenticação pessoal em um repositório compartilhado.

Claude Desktop e Claude Web

Se o OpenRouter não aparecer no diretório de conectores do Claude, o guia de conexão do OpenRouter orienta a adicionar um conector remoto personalizado:

1. Abra Settings > Connectors > Customize > Connectors.
2. Clique em + e escolha Add custom connector.
3. Nomeie-o como OpenRouter MCP.
4. Informe https://mcp.openrouter.ai/mcp como URL do servidor MCP remoto.
5. Deixe os campos OAuth em branco, adicione o conector, abra-o e clique em Connect.
6. Conclua a aprovação do OpenRouter no navegador.

Algumas organizações desativam conectores personalizados. Se a opção não estiver disponível em uma conta gerenciada, consulte o administrador. A documentação de MCP da Anthropic aborda os conceitos do protocolo no lado do cliente.

O que dá para pedir com segurança

A maior parte das ferramentas oficiais do OpenRouter MCP faz consultas em tempo real. Separá-las pelo efeito colateral é mais útil do que decorar a lista completa.

Na seleção, deixe clara a regra de decisão: “Encontre o modelo de menor custo com tool calling e janela de contexto de 64k, depois mostre o endpoint disponível mais rápido.” Os filtros documentados incluem preço, contexto mínimo, família de modelo, autor, provedor, modalidade, parâmetros aceitos, faixas de benchmark, taxa de sucesso em tool calling, disponibilidade de zero data retention e região.

Para um teste controlado, informe o slug e torne o prompt reproduzível:

Use o OpenRouter MCP send-message com o modelo "openai/gpt-4o".
Envie exatamente esta mensagem de usuário e não adicione um prompt de sistema:

"Retorne um objeto JSON com as chaves title e risks. Analise esta nota de lançamento:
[cole o texto aqui]"

Mostre a resposta e o ID de geração. Não execute outro modelo.

O slug é apenas ilustrativo; use um que list-models confirme como disponível. Para comparações auditáveis, exija explicitamente as ferramentas de consulta, os valores retornados e um ID de geração, em vez de aceitar uma recomendação de modelo sem suporte verificável.

OpenRouter MCP ou MCP oficial do provedor?

O OpenRouter MCP funciona como uma camada de inteligência e testes entre provedores. Já o MCP oficial de um provedor costuma ser melhor quando a ação pertence ao produto, à conta ou ao plano de dados desse provedor.

Escolha o OpenRouter MCP quando a pergunta for “Qual modelo ou rota devo usar?”. Prefira um MCP de primeira parte quando a pergunta for “O que consigo fazer dentro do serviço deste provedor?”. Os dois podem ser conectados ao mesmo agente quando ambas as capacidades forem necessárias.

Servidores MCP locais ou multimodais criados pela comunidade são uma categoria à parte. A página Works With OpenRouter descreve um servidor para vários clientes e fluxos de texto, imagem, áudio e vídeo; ele exige uma API key do OpenRouter e créditos, e não é o serviço hospedado oficial em mcp.openrouter.ai.

Limites importantes em projetos reais

“@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, descrevendo um caso de uso de consulta de informações sobre modelos.

O cookbook de MCP do OpenRouter também trata do caminho inverso: usar modelos do OpenRouter como backend de LLM para outros servidores de ferramentas MCP, em vez de conectar um cliente de programação ao OpenRouter MCP.

Como resolver a primeira chamada que falhar

1. O servidor aparece, mas as ferramentas falham na autenticação. Refaça a etapa de OAuth específica do cliente. A chave dedicada tem validade documentada de 7 dias e também pode ser desconectada pelo dashboard do OpenRouter.
2. Nenhuma janela do navegador abre. Use claude mcp login openrouter, a ação /mcp do Claude Code, as configurações de MCP do Cursor ou o botão Connect do conector do Claude.
3. O Claude Desktop não oferece conector personalizado. Verifique se um administrador da organização desativou conectores personalizados.
4. A resposta sobre um modelo parece desatualizada. Peça explicitamente list-models, list-benchmarks ou list-model-endpoints e exija os valores retornados.
5. Um teste custa mais ou usa uma rota diferente do esperado. Inspecione o ID de geração com get-generation e fixe um provedor explícito na próxima execução voltada à reprodutibilidade.

Perguntas frequentes

O OpenRouter MCP consegue chamar qualquer modelo do OpenRouter?

Ele pode testar slugs de modelos expostos pelo catálogo em tempo real, sujeito a disponibilidade, recursos, créditos e restrições de roteamento. Confirme o slug primeiro com list-models.

Posso usar o OpenRouter MCP no Claude Desktop, Cursor e Claude Code ao mesmo tempo?

Você pode adicionar o mesmo endpoint oficial em cada cliente, seguindo a configuração e o fluxo de autenticação documentados para cada um. Não inclua credenciais pessoais em configurações compartilhadas.

Devo instalar um pacote comunitário openrouter-mcp no lugar dele?

Somente se você precisar de um fluxo local com stdio ou de uma orquestração multimodal que o servidor hospedado oficial não oferece. Antes, verifique o repositório, o tratamento das credenciais, a origem do pacote e o status de manutenção.

Comece por uma consulta somente leitura ao catálogo; autorize uma chamada de inferência controlada apenas quando modelo, rota e limite de gasto estiverem claros.