Características

• 🤖 Chat multi-API: admite endpoints compatibles con OpenAI Chat Completions, Anthropic Messages y OpenAI Responses
• 🖼️ Generación multimodal: además del chat de texto, admite tareas asíncronas de generación de imagen y video (texto a, imagen a, primer/último cuadro, activo de referencia)
• 🔍 Consulta de modelos y cuenta: liste los modelos disponibles, los detalles de modelos, el saldo de la cuenta, los detalles de uso/facturación y las transacciones de recarga
• 🔑 Clave enviada mediante encabezado: cada llamada lee la clave API desde el encabezado de la solicitud, de modo que una sola implementación puede compartirse entre varias cuentas — el servidor nunca persiste ni almacena en caché ninguna clave

Inicio rápido

Úselo en Claude Code (recomendado). Agregue -s user para registrarlo en el ámbito de usuario (disponible en todos sus proyectos).

Paso 1: agregar la conexión

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

Paso 2: verificar la conexión

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

Paso 3: empezar a usarlo

Puede pedirle a Claude cosas como:

• "Usa BasicRouter para llamar a claude-sonnet-5 y escribe un poema sobre el otoño"
• "Lista los modelos disponibles en mi cuenta de BasicRouter"
• "Consulta mi saldo y uso reciente en BasicRouter"
• "Usa BasicRouter para generar una imagen de una ciudad cyberpunk de noche"

Claude llamará automáticamente a la herramienta MCP correspondiente y devolverá el resultado.

Uso con Claude Desktop

Agregue esto a la sección mcpServers:

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

Uso con Codex CLI

Recomendado: use env_http_headers para leer la clave desde una variable de entorno

Primero exporte la variable de entorno en su shell:

Copiarexport BASICROUTER_API_KEY=<su clave API de BasicRouter>

Luego, en ~/.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 escribir la clave directamente en la configuración (útil si no desea gestionar una variable de entorno aparte, pero tenga en cuenta que la clave quedará almacenada en texto plano en el archivo de configuración):

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

Si lo agrega mediante la interfaz de configuración de Codex:

• Tipo: HTTP / Streamable HTTP
• Nombre: basicrouter
• URL: https://api.basicrouter.ai/mcp
• Nombre del encabezado: X-Basicrouter-Api-Key
• Valor del encabezado: su clave API de BasicRouter

Verificar la conexión

Después de iniciar Codex CLI, el comando /mcp lista los servidores MCP configurados y su estado de conexión — solo confirme que se cargó correctamente. El patrón de uso coincide con el de Claude: Codex elige automáticamente la herramienta adecuada.

Si su archivo de configuración ya tiene otros servidores MCP, agregue este al mismo nivel. Cierre por completo y vuelva a abrir Claude Desktop después de editar.

Herramientas

Este servidor MCP ofrece 14 herramientas, agrupadas en cinco categorías:

1. Chat

1. chat_completion — Chat Completions

Envía una única solicitud de chat y devuelve la respuesta completa del modelo (sin streaming). Además de texto, también acepta imágenes para comprensión visual (el modelo debe soportar vision) — cambia el content del mensaje de string a un array de bloques de contenido mezclando text e image_url.

Entrada multimodal (text / image / video)

Entrada de imagen (URL):

Copiar{"role": "user", "content": [
  {"type": "text", "text": "¿Qué hay en esta imagen?"},
  {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]}

Entrada de imagen (Base64):

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

Formatos soportados: PNG, JPEG, GIF (solo el primer fotograma), WebP. Límite de tamaño por imagen 20MB.

Nota: las imágenes grandes en Base64 producen cadenas muy largas y pueden fallar por un cuerpo de solicitud demasiado grande; se recomienda pasar imágenes por URL.

El parámetro detail (opcional, definido en el objeto image_url) controla la fidelidad del procesamiento de la imagen: "auto" (predeterminado — el modelo decide según el tamaño) / "low" (miniatura 512x512, rápido y barato, bueno para clasificación simple) / "high" (resolución total, bueno para texto pequeño / detalles). El array content de un mensaje puede contener varios bloques image_url para pasar varias imágenes.

Entrada de video (URL):

Copiar{"role": "user", "content": [
  {"type": "text", "text": "Describe lo que sucede en este video."},
  {"type": "video_url", "video_url": {"url": "https://example.com/video.mp4"}}
]}

Entrada de video (Base64):

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

Los modelos que admiten entrada de video en BasicRouter incluyen algunos modelos de las series Qwen, Doubao (dola-seed), Kimi, MiniMax — verifica input_modalities devuelto por list_models. El estándar oficial Chat Completions de OpenAI no admite video nativamente, pero la pasarela BasicRouter lo admite a través de

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

formato de extensión. Este formato es consistente con el formato video_url utilizado por OpenRouter, NVIDIA NIM, vLLM y otras plataformas.

2. create_message — Compatible con Anthropic Messages

Llama al endpoint compatible con Anthropic Messages (sin streaming). Los bloques de contenido soportan text, image, tool_use, tool_result, thinking, redacted_thinking. Las imágenes se pasan mediante bloques de contenido.

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

Entrada multimodal (text / image / video)

La entrada de imagen soporta tres tipos de source:

1. Codificación Base64 (nota: el campo data es una string Base64 pura, sin el prefijo data:); media_type soporta image/jpeg, image/png, image/gif, image/webp:

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

2. Referencia por URL:

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

3. File ID (primero sube la imagen vía la Files API con purpose="vision" para obtener un file_id):

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

El array content de un mensaje puede contener varios bloques image para pasar varias imágenes.

Nota: las imágenes grandes en Base64 producen cadenas muy largas y pueden fallar por un cuerpo de solicitud demasiado grande; se recomienda pasar imágenes por URL.

Entrada de vídeo: la API Anthropic Messages no soporta archivos de vídeo nativamente. Para comprensión de vídeo, primero extrae fotogramas clave con ffmpeg o similar, luego pasa cada fotograma como un bloque de contenido image. Para los modelos que admiten entrada de vídeo en BasicRouter (verifica input_modalities mediante list_models), usa la interfaz chat_completion o create_response para obtener soporte nativo de vídeo.

3. create_response — Compatible con OpenAI Responses

Usa input en lugar de messages, instructions en lugar del mensaje del sistema y text.format en lugar de response_format. Además de texto, también acepta imágenes para comprensión visual (el modelo debe soportar vision) — define input como un array de objetos mensaje cuyo content es un array de bloques de contenido que mezcla texto e imágenes.

Entrada multimodal (text / image / video)

Nota: la Responses API usa los tipos de bloque de contenido input_text / input_image / input_video (no text / image_url / video_url de Chat Completions), y image_url / video_url es un string directo, no un objeto anidado.

Entrada de imagen (URL):

Copiar[{"role": "user", "content": [
  {"type": "input_text", "text": "¿Qué hay en esta imagen?"},
  {"type": "input_image", "image_url": "https://example.com/image.jpg"}
]}]

Entrada de imagen (Base64):

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

Formatos soportados: PNG, JPEG, GIF (solo el primer fotograma), WebP. Límite de tamaño por imagen 20MB.

Nota: las imágenes grandes en Base64 producen cadenas muy largas y pueden fallar por un cuerpo de solicitud demasiado grande; se recomienda pasar imágenes por URL.

Entrada de imagen (File ID):

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

— el file_id se obtiene subiendo la imagen vía la Files API con purpose="vision".

El parámetro detail (opcional, en el objeto input_image) controla la fidelidad del procesamiento: "auto" (predeterminado) / "low" (miniatura 512x512, rápido y barato) / "high" (resolución total, para texto pequeño / detalles) / "original" (resolución original). El array content de un mensaje puede contener varios bloques input_image para varias imágenes.

Entrada de video (URL):

Copiar[{"role": "user", "content": [
  {"type": "input_text", "text": "Describe lo que sucede en este video."},
  {"type": "input_video", "video_url": "https://example.com/video.mp4"}
]}]

Entrada de video (Base64):

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

; Video input (File ID):

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

. Los modelos que admiten entrada de video en BasicRouter incluyen algunos modelos de las series Qwen, Doubao (dola-seed), Kimi, MiniMax — verifica input_modalities devuelto por list_models. El estándar oficial Responses API de OpenAI no admite video nativamente, pero la pasarela BasicRouter lo admite a través de

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

formato de extensión. Este formato es consistente con el formato input_video utilizado por BytePlus/Volcengine y otras plataformas.

2. Modelos y cuenta

4. list_models — Listar modelos disponibles

Devuelve los modelos disponibles para la cuenta actual, con metadatos de proveedor, modalidad, capacidad y precios. Sin parámetros. Cada elemento de la lista incluye un tramo de precio price_tiers — el precio de facturación efectivo del llamador, coincidente con el cargo real (ver Referencia del campo de tramos de precio) (only some newer models).

5. get_model — Obtener los detalles de un modelo

La respuesta incluye un tramo de precio price_tiers (ver Referencia del campo de tramos de precio); devuelve 404 (sin campos de precio) cuando el modelo no existe.

6. get_balance — Consultar el saldo de la cuenta

Devuelve el uso y el saldo actuales de la cuenta. Sin parámetros.

3. Facturación

7. list_usage — Detalles de uso/facturación de modelos

Detalles de facturación por uso de modelos, paginados, ordenados por fecha de creación del pedido en orden descendente. Solo cargos regulares por uso — sin recargas ni ajustes.

8. list_transactions — Transacciones de recarga/paquete

Transacciones pagadas de recarga / compra de paquete, paginadas, ordenadas por fecha de creación en orden descendente.

4. Generación de imágenes

9. list_image_models — Listar modelos de imagen

Devuelve los modelos de generación de imágenes admitidos, con resolución, relación de aspecto, número máximo de imágenes (maxCount) y número máximo de imágenes de referencia (fileMax). Sin parámetros. Consulte esto antes de generar imágenes — solo puede pasar los valores que publica. Cada elemento de la lista incluye un tramo de precio priceTiers (ver Referencia del campo de tramos de precio).

10. create_image_generation — Enviar una tarea de generación de imágenes

Se envía de forma asíncrona y devuelve inmediatamente un taskId; consume crédito de la cuenta.

11. get_image_generation — Sondear una tarea de imagen

Devuelve: status es pending / success / failed; images es un arreglo en formato de cadena JSON de URLs de imágenes; text lleva cualquier salida adicional del modelo (p. ej. salida multimodal de Gemini).

5. Generación de video

12. list_video_models — Listar modelos de video

Devuelve los modelos de generación de video admitidos, con allowedVideoTypes, rango de duración (videoDurationMin/Max), resolución, relación de aspecto y límite de activos de referencia (fileMax). Sin parámetros. Consulte esto antes de generar video. Cada elemento de la lista incluye un tramo de precio priceTiers (ver Referencia del campo de tramos de precio).

13. create_video_generation — Enviar una tarea de generación de video

Se envía de forma asíncrona y devuelve inmediatamente un taskId; consume crédito de la cuenta.

Significado de video_type:

14. get_video_generation — Sondear una tarea de video

Referencia del campo de tramos de precio

Las salidas de estas 4 herramientas de consulta de modelos — list_models, get_model, list_image_models, list_video_models — devuelven el precio de facturación efectivo del llamador (usuario del API Key), que coincide exactamente con el cargo real, e incluyen todos los tramos de precio del modelo.

Diferencia de nomenclatura: list_models / get_model siguen snake_case de OpenAI (price_tiers); list_image_models / list_video_models siguen camelCase (priceTiers). La estructura es la misma.

price_tiers / priceTiers es un array; cada elemento es un tramo de precio:

Los tres tipos de modelo comparten la misma estructura; solo difieren los campos de descripción, y los campos no aplicables son null:

Significado del precio: los inputPrice / outputPrice / cacheReadPrice / cacheWritePrice devueltos, etc., son los precios unitarios finales de facturación para el usuario actual del API Key, resueltos a través de la cadena de precio (chain) → guidance → precio base, y coinciden con el cargo real. El precio unitario que ve el llamador varía según su cadena de precio (reseller / distributor / empresa / configuración de nivel de usuario).

Cargo real = uso ÷ quantity × precio unitario × ratio. Para facturación de vídeo por segundo: cargo real = duration × outputPrice × ratio.

Casos extremos y manejo de errores (un endpoint de solo lectura nunca devuelve 500 por configuración de precio):

Ejemplo de respuesta (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
        }
      ]
    }
  ]
}

Ejemplo de respuesta (list_image_models, modelo de imagen; priceTiers misma estructura, unit es 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 imagen",
          "inputPrice": 0,
          "outputPrice": 0.04,
          "cachePrice": 0,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

Ejemplos

Ejemplo 1: una solicitud de chat simple

Pregunte: "Usa BasicRouter para llamar a claude-sonnet-5 y pregunta qué es el GIL de Python"

La IA llamará a chat_completion con:

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

Ejemplo 2: uso de herramientas mediante el endpoint de Anthropic Messages

Pregunte: "Usa el endpoint Messages de BasicRouter y deja que el modelo decida si consultar el clima"

La IA llamará a create_message, pasando una definición de tools y tool_choice; la respuesta incluirá un bloque de contenido tool_use.

Ejemplo 3: listar los modelos disponibles

Pregunte: "Lista los modelos en mi cuenta de BasicRouter"

La IA llamará a list_models, devolviendo IDs, proveedores, modalidades, precios y más para cada modelo disponible.

Ejemplo 4: consultar saldo y uso

Pregunte: "Consulta mi uso de BasicRouter de este mes"

La IA llamará a get_balance para el saldo, y luego a list_usage (con start_time acotado a este mes) para el desglose de uso.

Ejemplo 5: generar una imagen

Pregunte: "Usa BasicRouter para generar una imagen de una ciudad cyberpunk de noche"

La IA primero llamará a list_image_models para consultar las especificaciones, luego a create_image_generation para obtener un taskId, y después sondeará get_image_generation para obtener la URL de la imagen.

Ejemplo 6: texto a video

Pregunte: "Usa BasicRouter para generar un video de 5 segundos de una nebulosa espacial"

La IA primero llamará a list_video_models para consultar las especificaciones, luego a create_video_generation (video_type=1, duration=5), y tras obtener un taskId, sondeará get_video_generation.

Preguntas frecuentes

La llamada a la herramienta falla con "missing BasicRouter API Key"

• Ejecutó claude mcp add sin --header, o la clave es incorrecta
• Si edita la configuración JSON directamente, el nombre del campo headers es incorrecto (debería ser X-Basicrouter-Api-Key)
• Ejecución local sin la variable de entorno BASICROUTER_API_KEY configurada

La llamada a la herramienta falla con "BasicRouter returned 401 unauthorized"

La propia clave API es incorrecta o expiró — regenérela en la consola de BasicRouter.

Claude no está llamando a las herramientas de BasicRouter — ¿qué hacer?

• Confirme que la conexión muestre ✓ Connected mediante claude mcp list
• Verifique el estado de la conexión: claude mcp get basicrouter
• Intente ser explícito: "Usa la herramienta chat_completion de BasicRouter para llamar a claude-sonnet-5 …"

La generación de imagen/video se queda pendiente para siempre

• Sondee las tareas de imagen con get_image_generation y las de video con get_video_generation — tenga en cuenta que el estado de una tarea de video en curso es "running", no "pending"
• La generación toma tiempo, generalmente de unos segundos a decenas de segundos, más para video
• Si pasó un callback_url, la tarea llamará de vuelta al completarse — no es necesario sondear

Errores en list_image_models / list_video_models

Ninguna de las dos herramientas consume crédito por sí misma — un error suele indicar un problema de clave o de red. Primero confirme que list_models funciona normalmente.

Notas

• Nombre del encabezado:MCP envía la clave mediante X-Basicrouter-Api-Key.
• Consumo de crédito:chat_completion / create_message / create_response / create_image_generation / create_video_generation consumen todos crédito de la cuenta — consulte get_balance primero si desea conocer el saldo con anticipación.
• Consulte las especificaciones antes de generar:Los parámetros de generación de imagen/video como model, resolution, ratio, count, duration y video_type solo deben usar los valores publicados por list_image_models / list_video_models, de lo contrario la llamada fallará con un error.
• Sin streaming:Ninguno de los tres endpoints de chat admite streaming — cada uno devuelve el resultado completo de una sola vez.
• Diseño sin estado:Cada solicitud es independiente y no se almacena ninguna sesión; para conversaciones de varios turnos use previous_response_id de create_response o mantenga el historial usted mismo en messages.