Recursos

• 🤖 Chat multi-API: suporta os endpoints compatíveis com OpenAI Chat Completions, Anthropic Messages e OpenAI Responses
• 🖼️ Geração multimodal: além do chat de texto, suporta tarefas assíncronas de geração de imagem e vídeo (texto-para-, imagem-para-, primeiro/último quadro, ativo de referência)
• 🔍 Consulta de modelos e conta: lista modelos disponíveis, detalhes de modelos, saldo da conta, detalhes de uso/cobrança e transações de recarga
• 🔑 Chave passada via cabeçalho: cada chamada lê a chave da API a partir do cabeçalho da requisição, então uma única implantação pode ser compartilhada por várias contas — o servidor nunca persiste nem armazena em cache qualquer chave

Início rápido

Use no Claude Code (recomendado). Adicione -s user para registrá-lo no escopo do usuário (disponível em todos os seus projetos).

Passo 1: Adicionar a conexão

Copiarclaude mcp add --transport http basicrouter https://api.basicrouter.ai/mcp \
  --header "X-Basicrouter-Api-Key: <sua chave de API do BasicRouter>" \
  -s user

Passo 2: Verificar a conexão

Copiarclaude mcp list          # deve mostrar ✓ Connected
claude mcp get basicrouter  # deve mostrar Scope: User config (available in all your projects)

Passo 3: Comece a usar

Você pode pedir ao Claude coisas como:

• "Use o BasicRouter para chamar o claude-sonnet-5 e escrever um poema sobre o outono"
• "Liste os modelos disponíveis na minha conta BasicRouter"
• "Verifique meu saldo e uso recente no BasicRouter"
• "Use o BasicRouter para gerar uma imagem de uma cidade cyberpunk à noite"

O Claude chamará automaticamente a ferramenta MCP correspondente e retornará o resultado.

Usando com o Claude Desktop

Adicione isto à seção mcpServers:

Copiar{
  "mcpServers": {
    "basicrouter": {
      "type": "http",
      "url": "https://api.basicrouter.ai/mcp",
      "headers": {
        "X-Basicrouter-Api-Key": "<sua chave de API do BasicRouter>"
      }
    }
  }
}

Usando com o Codex CLI

Recomendado: use env_http_headers para ler a chave a partir de uma variável de ambiente

Primeiro, exporte a variável de ambiente no seu shell:

Copiarexport BASICROUTER_API_KEY=<sua chave de API do BasicRouter>

Depois, em ~/.codex/config.toml:

Copiar[mcp_servers.basicrouter]
url = "https://api.basicrouter.ai/mcp"
env_http_headers = { "X-Basicrouter-Api-Key" = "BASICROUTER_API_KEY" }

Alternativa: use http_headers para escrever a chave diretamente na configuração (útil se você não quiser gerenciar uma variável de ambiente separada, mas note que a chave fica então armazenada em texto simples no arquivo de configuração):

Copiar[mcp_servers.basicrouter]
url = "https://api.basicrouter.ai/mcp"
http_headers = { "X-Basicrouter-Api-Key" = "<sua chave de API do BasicRouter>" }

Se estiver adicionando pela interface de configurações do Codex:

• Tipo: HTTP / Streamable HTTP
• Nome: basicrouter
• URL: https://api.basicrouter.ai/mcp
• Nome do cabeçalho: X-Basicrouter-Api-Key
• Valor do cabeçalho: sua chave de API do BasicRouter

Verificar a conexão

Depois de iniciar o Codex CLI, o comando /mcp lista os servidores MCP configurados e o status de suas conexões — basta confirmar que carregou corretamente. O padrão de uso é igual ao do Claude: o Codex escolhe automaticamente a ferramenta certa.

Se o seu arquivo de configuração já tiver outros servidores MCP, adicione este no mesmo nível. Saia completamente e reabra o Claude Desktop após editar.

Ferramentas

Este servidor MCP fornece 14 ferramentas, agrupadas em cinco categorias:

1. Chat

1. chat_completion — Chat Completions

Envia uma única requisição de chat e retorna a resposta completa do modelo (sem streaming). Além de texto simples, também aceita imagens para compreensão visual (o modelo deve suportar vision) — mude o content da mensagem de string para um array de blocos de conteúdo misturando text e image_url.

Entrada multimodal (text / image / video)

Entrada de imagem (URL):

Copiar{"role": "user", "content": [
  {"type": "text", "text": "O que há nesta imagem?"},
  {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]}

Entrada de imagem (Base64):

Copiar{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,<BASE64_STRING>"}}

Formatos suportados: PNG, JPEG, GIF (apenas o primeiro quadro), WebP. Limite de tamanho por imagem 20MB.

Nota: imagens grandes em Base64 produzem strings muito longas e podem falhar pelo corpo da requisição exceder o limite; prefira passar imagens por URL.

O parâmetro detail (opcional, definido no objeto image_url) controla a fidelidade do processamento da imagem: "auto" (padrão — o modelo decide pelo tamanho) / "low" (miniatura 512x512, rápido e barato, bom para classificação simples) / "high" (resolução total, bom para texto pequeno / detalhes). O array content de uma mensagem pode conter vários blocos image_url para passar várias imagens.

Entrada de vídeo (URL):

Copiar{"role": "user", "content": [
  {"type": "text", "text": "Descreva o que acontece neste vídeo."},
  {"type": "video_url", "video_url": {"url": "https://example.com/video.mp4"}}
]}

Entrada de vídeo (Base64):

Copiar{"type": "video_url", "video_url": {"url": "data:video/mp4;base64,<BASE64_STRING>"}}

Modelos com suporte a entrada de vídeo no BasicRouter incluem alguns modelos das séries Qwen, Doubao (dola-seed), Kimi, MiniMax — verifique input_modalities retornado por list_models. O padrão oficial Chat Completions da OpenAI não suporta vídeo nativamente, mas o gateway BasicRouter suporta via

Copiar{"type": "video_url", "video_url": {"url": "..."}}

formato de extensão. Este formato é consistente com o formato video_url usado por OpenRouter, NVIDIA NIM, vLLM e outras plataformas.

2. create_message — Compatível com Anthropic Messages

Chama o endpoint compatível com Anthropic Messages (sem streaming). Os blocos de conteúdo suportam text, image, tool_use, tool_result, thinking, redacted_thinking. As imagens são passadas via blocos de conteúdo.

Copiar{"type": "image", "source": {...}}

Entrada multimodal (text / image / video)

A entrada de imagem suporta três tipos de source:

1. Codificação Base64 (atenção: o campo data é uma string Base64 pura, sem o prefixo data:); media_type suporta image/jpeg, image/png, image/gif, image/webp:

Copiar{"type": "image", "source": {
  "type": "base64",
  "media_type": "image/jpeg",
  "data": "<BASE64_STRING>"
}}

2. Referência por URL:

Copiar{"type": "image", "source": {
  "type": "url",
  "url": "https://example.com/image.jpg"
}}

3. File ID (primeiro faça upload da imagem via Files API com purpose="vision" para obter um file_id):

Copiar{"type": "image", "source": {
  "type": "file",
  "file_id": "<file_id>"
}}

O array content de uma mensagem pode conter vários blocos image para passar várias imagens.

Nota: imagens grandes em Base64 produzem strings muito longas e podem falhar pelo corpo da requisição exceder o limite; prefira passar imagens por URL.

Entrada de vídeo: a API Anthropic Messages não suporta arquivos de vídeo nativamente. Para compreensão de vídeo, primeiro extraia quadros-chave com ffmpeg ou similar, depois passe cada quadro como um bloco de conteúdo image. Para os modelos com suporte a entrada de vídeo no BasicRouter (verifique input_modalities retornado por list_models), use a interface chat_completion ou create_response para suporte nativo a vídeo.

3. create_response — Compatível com OpenAI Responses

Usa input em vez de messages, instructions em vez de mensagem de sistema e text.format em vez de response_format. Além de texto simples, também aceita imagens para compreensão visual (o modelo deve suportar vision) — defina input como um array de objetos de mensagem cujo content é um array de blocos de conteúdo misturando texto e imagens.

Entrada multimodal (text / image / video)

Nota: a Responses API usa os tipos de bloco de conteúdo input_text / input_image / input_video (não text / image_url / video_url do Chat Completions), e image_url / video_url é uma string direta, não um objeto aninhado.

Entrada de imagem (URL):

Copiar[{"role": "user", "content": [
  {"type": "input_text", "text": "O que há nesta imagem?"},
  {"type": "input_image", "image_url": "https://example.com/image.jpg"}
]}]

Entrada de imagem (Base64):

Copiar{"type": "input_image", "image_url": "data:image/jpeg;base64,<BASE64_STRING>"}

Formatos suportados: PNG, JPEG, GIF (apenas o primeiro quadro), WebP. Limite de tamanho por imagem 20MB.

Nota: imagens grandes em Base64 produzem strings muito longas e podem falhar pelo corpo da requisição exceder o limite; prefira passar imagens por URL.

Entrada de imagem (File ID):

Copiar{"type": "input_image", "file_id": "<file_id>"}

o file_id é obtido fazendo upload da imagem via Files API com purpose="vision".

O parâmetro detail (opcional, no objeto input_image) controla a fidelidade do processamento: "auto" (padrão) / "low" (miniatura 512x512, rápido e barato) / "high" (resolução total, para texto pequeno / detalhes) / "original" (resolução original). O array content de uma mensagem pode conter vários blocos input_image para várias imagens.

Entrada de vídeo (URL):

Copiar[{"role": "user", "content": [
  {"type": "input_text", "text": "Descreva o que acontece neste vídeo."},
  {"type": "input_video", "video_url": "https://example.com/video.mp4"}
]}]

Entrada de vídeo (Base64):

Copiar{"type": "input_video", "video_url": "data:video/mp4;base64,<BASE64_STRING>"}

Entrada de vídeo (File ID):

Copiar{"type": "input_video", "file_id": "<file_id>"}

Modelos com suporte a entrada de vídeo no BasicRouter incluem alguns modelos das séries Qwen, Doubao (dola-seed), Kimi, MiniMax — verifique input_modalities retornado por list_models. O padrão oficial Responses API da OpenAI não suporta vídeo nativamente, mas o gateway BasicRouter suporta via

Copiar{"type": "input_video", "video_url": "..."}

formato de extensão. Este formato é consistente com o formato input_video usado por BytePlus/Volcengine e outras plataformas.

2. Modelos e conta

4. list_models — Listar modelos disponíveis

Retorna os modelos disponíveis para a conta atual, com metadados de fornecedor, modalidade, capacidade e preço. Sem parâmetros. Cada item da lista inclui uma faixa de preço price_tiers — o preço de cobrança efetivo do chamador, correspondendo ao débito real (veja Referência do campo de faixas de preço) (only some newer models).

5. get_model — Obter detalhes de um modelo

A resposta inclui uma faixa de preço price_tiers (veja Referência do campo de faixas de preço); retorna 404 (sem campos de preço) quando o modelo não existe.

6. get_balance — Verificar saldo da conta

Retorna o uso e o saldo da conta atual. Sem parâmetros.

3. Cobrança

7. list_usage — Detalhes de uso/cobrança de modelos

Detalhes paginados de cobrança por uso de modelos, ordenados pela data de criação do pedido em ordem decrescente. Apenas cobranças normais de uso — sem recargas ou ajustes.

8. list_transactions — Transações de recarga/pacote

Transações pagas de recarga / compra de pacote, paginadas e ordenadas pela data de criação em ordem decrescente.

4. Geração de imagens

9. list_image_models — Listar modelos de imagem

Retorna os modelos de geração de imagem suportados, com resolução, proporção de tela, número máximo de imagens (maxCount) e número máximo de imagens de referência (fileMax). Sem parâmetros. Verifique isso antes de gerar imagens — você só pode passar valores que ele publica. Cada item da lista inclui uma faixa de preço priceTiers (veja Referência do campo de faixas de preço).

10. create_image_generation — Enviar uma tarefa de geração de imagem

Envia de forma assíncrona e retorna imediatamente um taskId; consome crédito da conta.

11. get_image_generation — Consultar uma tarefa de imagem

Retorna: status é pending / success / failed; images é um array de string JSON com URLs de imagens; text traz qualquer saída extra do modelo (ex.: saída multimodal do Gemini).

5. Geração de vídeos

12. list_video_models — Listar modelos de vídeo

Retorna os modelos de geração de vídeo suportados, com allowedVideoTypes, faixa de duração (videoDurationMin/Max), resolução, proporção de tela e limite de ativos de referência (fileMax). Sem parâmetros. Verifique isso antes de gerar vídeo. Cada item da lista inclui uma faixa de preço priceTiers (veja Referência do campo de faixas de preço).

13. create_video_generation — Enviar uma tarefa de geração de vídeo

Envia de forma assíncrona e retorna imediatamente um taskId; consome crédito da conta.

Significado de video_type:

14. get_video_generation — Consultar uma tarefa de vídeo

Referência do campo de faixas de preço

As saídas destas 4 ferramentas de consulta de modelos — list_models, get_model, list_image_models, list_video_models — retornam o preço de cobrança efetivo do chamador (usuário do API Key), correspondendo exatamente ao débito real, e incluem todas as faixas de preço do modelo.

Diferença de nomenclatura: list_models / get_model seguem o snake_case do OpenAI (price_tiers); list_image_models / list_video_models seguem camelCase (priceTiers). A estrutura é a mesma.

price_tiers / priceTiers é um array; cada elemento é uma faixa de preço:

Os três tipos de modelo compartilham a mesma estrutura; apenas os campos de descrição diferem, e campos não aplicáveis são null:

Significado do preço: os inputPrice / outputPrice / cacheReadPrice / cacheWritePrice retornados, etc., são os preços unitários finais de cobrança para o usuário atual do API Key, resolvidos através da cadeia de preço (chain) → guidance → preço base, e correspondem ao débito real. O preço unitário que o chamador vê varia conforme sua cadeia de preço (reseller / distributor / empresa / configuração de nível de usuário).

Débito real = uso ÷ quantity × preço unitário × ratio. Para cobrança de vídeo por segundo: débito real = duration × outputPrice × ratio.

Casos extremos e tratamento de erros (um endpoint somente leitura nunca retorna 500 por configuração de preço):

Exemplo de resposta (list_models, modelo de texto):

Copiar{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "display_name": "gpt-4o",
      "context_length": 128000,
      "description": "...",
      "price_tiers": [
        {
          "region": "GLOBAL",
          "bandMin": null,
          "bandMax": null,
          "resolution": null,
          "clarity": null,
          "unit": "token",
          "quantity": 1000,
          "description": "por 1K tokens",
          "inputPrice": 0.0025,
          "outputPrice": 0.01,
          "cachePrice": 0.00125,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

Exemplo de resposta (list_image_models, modelo de imagem; priceTiers mesma estrutura, unit é image):

Copiar{
  "object": "list",
  "data": [
    {
      "id": "dall-e-3",
      "object": "image_model",
      "displayName": "dall-e-3",
      "resolutions": ["1024x1024", "1792x1024", "1024x1792"],
      "priceTiers": [
        {
          "region": null,
          "bandMin": null,
          "bandMax": null,
          "resolution": "1024x1024",
          "clarity": "standard",
          "unit": "image",
          "quantity": 1,
          "description": "por imagem",
          "inputPrice": 0,
          "outputPrice": 0.04,
          "cachePrice": 0,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

Exemplos

Exemplo 1: uma requisição de chat simples

Pergunte: "Use o BasicRouter para chamar o claude-sonnet-5 e perguntar o que é o GIL do Python"

A IA chamará chat_completion com:

Copiar{
  "model": "claude-sonnet-5",
  "messages": [{"role": "user", "content": "What is Python's GIL?"}]
}

Exemplo 2: uso de ferramentas via o endpoint Anthropic Messages

Pergunte: "Use o endpoint Messages do BasicRouter e deixe o modelo decidir se deve verificar o clima"

A IA chamará create_message, passando uma definição de tools e tool_choice; a resposta incluirá um bloco de conteúdo tool_use.

Exemplo 3: listar modelos disponíveis

Pergunte: "Liste os modelos na minha conta BasicRouter"

A IA chamará list_models, retornando IDs, fornecedores, modalidades, preços e mais para cada modelo disponível.

Exemplo 4: verificar saldo e uso

Pergunte: "Verifique meu uso do BasicRouter neste mês"

A IA chamará get_balance para o saldo e, em seguida, list_usage (com start_time delimitado a este mês) para o detalhamento de uso.

Exemplo 5: gerar uma imagem

Pergunte: "Use o BasicRouter para gerar uma imagem de uma cidade cyberpunk à noite"

A IA primeiro chamará list_image_models para verificar as especificações, depois create_image_generation para obter um taskId, e então fará polling em get_image_generation para obter a URL da imagem.

Exemplo 6: texto para vídeo

Pergunte: "Use o BasicRouter para gerar um vídeo de 5 segundos de uma nebulosa espacial"

A IA primeiro chamará list_video_models para verificar as especificações, depois create_video_generation (video_type=1, duration=5), e após obter um taskId, fará polling em get_video_generation.

FAQ

A chamada de ferramenta falha com "missing BasicRouter API Key"

• Você executou claude mcp add sem --header, ou a chave está errada
• Se estiver editando o JSON de configuração diretamente, o nome do campo headers está errado (deveria ser X-Basicrouter-Api-Key)
• Executando localmente sem a variável de ambiente BASICROUTER_API_KEY definida

A chamada de ferramenta falha com "BasicRouter returned 401 unauthorized"

A própria chave de API está errada ou expirou — gere uma nova no console do BasicRouter.

O Claude não está chamando as ferramentas do BasicRouter — o que fazer?

• Confirme que a conexão mostra ✓ Connected via claude mcp list
• Verifique o status da conexão: claude mcp get basicrouter
• Tente ser explícito: "Use a ferramenta chat_completion do BasicRouter para chamar claude-sonnet-5 …"

A geração de imagem/vídeo fica pendente para sempre

• Faça polling de tarefas de imagem com get_image_generation e de tarefas de vídeo com get_video_generation — note que o status de uma tarefa de vídeo em execução é "running", não "pending"
• A geração leva tempo, geralmente de alguns a dezenas de segundos, mais para vídeo
• Se você passou um callback_url, a tarefa fará o callback na conclusão — sem necessidade de polling

Erros em list_image_models / list_video_models

Nenhuma das duas ferramentas consome crédito por si só — um erro geralmente indica um problema de chave ou de rede. Primeiro confirme que list_models funciona normalmente.

Notas

• Nome do cabeçalho:O MCP passa a chave via X-Basicrouter-Api-Key.
• Consumo de crédito:chat_completion / create_message / create_response / create_image_generation / create_video_generation consomem todos crédito da conta — verifique get_balance primeiro se quiser saber o saldo antecipadamente.
• Verifique as especificações antes de gerar:Parâmetros de geração de imagem/vídeo como model, resolution, ratio, count, duration e video_type devem usar apenas valores publicados por list_image_models / list_video_models, caso contrário a chamada resulta em erro.
• Sem streaming:Nenhum dos três endpoints de chat suporta streaming — cada um retorna o resultado completo de uma vez.
• Design sem estado:Cada requisição é independente e nenhuma sessão é armazenada; para conversas de múltiplos turnos, use previous_response_id de create_response ou mantenha o histórico você mesmo em messages.