TokenLab para agentes: modelos legibles por máquina, precios, SDKs y MCP

Un agente de codificación que elige un ID de modelo desde su memoria eventualmente elegirá uno que ya no existe, y solo se enterará después de un 404 o una factura sorprendente. TokenLab MCP le da al agente un catálogo en vivo para consultar primero, de modo que pueda verificar el ID, el formato de solicitud aceptado y el precio antes de escribir cualquier código de integración. Originalmente describimos el servidor como estrictamente de solo lectura. La documentación observada el 03-10-2026 dice lo contrario, por lo que esta versión corrige eso y añade un flujo de trabajo práctico.

Puntos clave

• El servidor MCP de TokenLab tiene tres perfiles: catalog (sin API key), core y full. Solo catalog no requiere clave.
• Con una clave, también puede enviar solicitudes de modelos, crear contenido multimedia, manejar archivos y verificar tareas asíncronas. No es de solo lectura.
• Dirija las consultas según tokenlab.accepted_request_formats, tokenlab.pricing, tokenlab.lifecycle y tokenlab.deliveryAvailability. No codifique de forma rígida el orden de las recomendaciones.
• Gemini Files, las subidas reanudables y cachedContents no están en ningún perfil de MCP.
• Nunca pegue una API key en un prompt o en un argumento de herramienta.

Qué ofrece el servidor MCP de TokenLab a un agente de codificación

Según la documentación del servidor MCP (observada el 03-10-2026), el servidor MCP de TokenLab permite a un cliente explorar los modelos y precios actuales, enviar solicitudes de modelos, crear contenido multimedia, trabajar con archivos y verificar tareas asíncronas. La documentación nombra estas capacidades:

• listar modelos y leer las capacidades de un modelo (list_models, get_model)
• leer precios actuales o comparar varios modelos
• enviar Chat Completions, Responses, Anthropic Messages o solicitudes de Gemini
• evaluar decisiones tipadas con evaluate_decisions
• crear o editar imágenes; crear video, música, 3D, voz, transcripción o traducción
• subir y recuperar archivos a través de la API /v1/files compatible con OpenAI
• crear embeddings o rerank de documentos
• verificar y cancelar tareas asíncronas compatibles (get_task_status para sondeo)

La documentación no enumera los nombres de las herramientas para precios o la descripción general de la API en esta versión. Nuestro borrador anterior nombraba get_model_pricing y get_api_overview. Verifique la lista de herramientas de su cliente conectado antes de confiar en esos dos nombres.

La disponibilidad de herramientas depende del perfil:

Perfil	API key	Incluye
catalog	No requerida	Lista de modelos, detalles de modelos, precios, comparaciones, descripción general de la API
core	Requerida para llamadas pagas	Herramientas comunes de chat, decisión, multimedia, audio, archivos, tareas, embedding, rerank y traducción
full	Requerida para llamadas pagas	core más APIs adicionales para desarrolladores

Comience con catalog si solo desea una mejor selección de modelos. Use core cuando el cliente deba crear contenido o llamar a un modelo.

Instalar el servidor MCP de TokenLab en su cliente

El paquete requiere Node.js 18.17 o superior y npx. Se ejecuta localmente a través de stdio, por lo que no necesita una instalación global. Haga una copia de seguridad de su configuración activa primero y añada solo la entrada de TokenLab. Estos comandos provienen de la documentación, observada el 03-10-2026.

Claude Code:

claude mcp add \
  --env TOKENLAB_MCP_TOOL_PROFILE=catalog \
  --scope user \
  tokenlab -- \
  npx -y @tokenlabai/mcp-server@0.6.26

Codex:

codex mcp add \
  --env TOKENLAB_MCP_TOOL_PROFILE=catalog \
  tokenlab -- \
  npx -y @tokenlabai/mcp-server@0.6.26

Cursor (~/.cursor/mcp.json o .cursor/mcp.json):

{
  "mcpServers": {
    "tokenlab": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server@0.6.26"],
      "env": {
        "TOKENLAB_MCP_TOOL_PROFILE": "catalog"
      }
    }
  }
}

VS Code usa .vscode/mcp.json con una clave servers y "type": "stdio". Claude Desktop usa la misma estructura que Cursor en claude_desktop_config.json. Copie ambos desde la página de documentación.

Para habilitar herramientas pagas, cree una clave en Console → API keys y establezca ambas variables en el entorno del servidor:

{
  "env": {
    "TOKENLAB_API_KEY": "<TOKENLAB_API_KEY>",
    "TOKENLAB_MCP_TOOL_PROFILE": "core"
  }
}

Luego reinicie el cliente y ejecute claude mcp list o codex mcp list. Pídale al agente que llame a list_models. Una lista no vacía confirma que el paquete se inició y llegó a TokenLab. Si una clave real termina en un archivo compartido, registro o historial de shell, revóquela y cree una nueva.

Flujo de un agente: descubrir, verificar, llamar

Este es el flujo que utilizamos. Imagine que a un agente se le pide añadir generación de imágenes a una aplicación de Node.js. Cada valor a continuación proviene de la documentación y las páginas de modelos en vivo observadas el 03-10-2026.

1. Descubrir. Solicite la lista corta actual, con la herramienta MCP o HTTP simple:

{ "tool": "list_models", "arguments": { "recommended_for": "image" } }

curl "https://api.tokenlab.sh/v1/models?recommended_for=image"

Los valores válidos para recommended_for son image, video, music, 3d, tts, stt, embedding, rerank y translation. Supongamos que el agente elige nano-banana-pro.

2. Verificar formatos y precio. Llame a get_model, o GET /v1/models/nano-banana-pro (API del modelo en vivo, observada el 03-10-2026). Informa:

• formatos de solicitud aceptados: gemini_generate_content, que mapea a /v1beta/models/{model}:generateContent
• capacidades: image-edit, image-to-image, text-to-image
• precio: per_request de 0.067 USD, con un rango de precios de 0.067 a 0.12 (precios actualizados el 02-10-2026T16:53:30.068Z)

Un agente que asumiera Chat Completions habría escrito el código incorrecto. Compare gpt-image-2 (API del modelo en vivo). No enumera formatos de solicitud aceptados y tiene un precio por token de 3.5 USD de entrada y 21 USD de salida por cada 1M de tokens. La estructura de precios difiere según el modelo, por lo que el agente debe leerla por modelo.

3. Realizar la llamada. Para un modelo de chat, la verificación de formato decide el endpoint. gpt-5.6-terra acepta openai_chat_completions y openai_responses (API del modelo en vivo, observada el 03-10-2026), por lo que el SDK estándar funciona:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
)

response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Reply only with OK."}],
)
print(response.choices[0].message.content)

Envíe el ID del modelo elegido explícitamente. La documentación establece que TokenLab no lo reemplaza silenciosamente. El cliente debe solicitar aprobación antes de una llamada paga si el precio o la elección del modelo aún no están confirmados.

Para una estimación de costos, gpt-5.6-terra cobra 0.6 USD por cada 1M de tokens de entrada hasta 272K tokens de entrada. Un prompt de 10,000 tokens cuesta aproximadamente 10,000 / 1,000,000 × 0.6 = 0.006 USD por entrada (estimación, antes de la salida). Por encima de los 272K tokens de entrada, toda la solicitud pasa al nivel superior a 1.2 USD de entrada y 5.4 USD de salida.

Campos de la API de modelos en los que un agente debería confiar para el enrutamiento

Lea estos desde GET /v1/models/{model} (Get a Model, observado el 03-10-2026):

Campo	Qué significa para el enrutamiento
tokenlab.accepted_request_formats	Qué familia de endpoints usar: openai_chat_completions es /v1/chat/completions, openai_responses es /v1/responses, anthropic_messages es /v1/messages
tokenlab.pricing / pricing_unit	Precio público actual y su unidad de facturación, como per_token o per_image
tokenlab.max_input_tokens, max_output_tokens	Límites de contexto y salida. Para gpt-5.6-terra: 1,050,000 y 128,000
tokenlab.supported_operations	Operaciones como text-to-image o image-to-video
tokenlab.lifecycle	Disponibilidad, fecha de lanzamiento, fecha de obsolescencia, modelo de reemplazo
tokenlab.deliveryAvailability	Soporte configurado como verified y official. Un campo faltante significa desconocido

Se aplican dos precauciones. Primero, un formato aceptado confirma el endpoint, pero las herramientas y campos individuales aún pueden variar según el modelo. Segundo, deliveryAvailability es soporte configurado, no una garantía en tiempo real. Trate los resultados de recommended_for como una lista corta, porque la documentación dice que no se debe fijar su orden.

Para precios solamente, GET /v1/models/{model}/pricing es el endpoint exclusivo de precios. Las entradas complejas pueden tener niveles. seedance-2.0, por ejemplo, tiene precios de salida dependientes de la resolución y la entrada de video desde 2.04 a 6.545 USD por 1M de tokens (API del modelo en vivo, observada el 03-10-2026).

Campos de error que guían la recuperación

En errores de Chat Completions y Responses compatibles con OpenAI, la guía de errores (observada el 03-10-2026) enumera campos opcionales como did_you_mean, suggestions, hint, retryable y retry_after. Maneje el estado HTTP y el code primero. Un 400 model_not_found puede incluir did_you_mean. Muéstrelo al usuario en lugar de cambiar de modelo silenciosamente. Un 503 all_channels_failed puede tener retryable: false, y repetirlo no ayudará. Anthropic Messages y Gemini mantienen sus formatos de error nativos.

Lo que el servidor MCP no hace

La documentación establece estos límites:

• No cambia el proveedor de modelos principal de su cliente. Use la propia guía de configuración de ese cliente.
• No cubre Gemini Files, subidas reanudables o cachedContents. Esos requieren llamadas HTTP, según Gemini Files and cache.
• No es el Skill. El TokenLab Skill instala instrucciones con npx skills add y no inicia ningún servidor MCP.
• No realiza sondeos por usted en caso de tiempo de espera. Si una verificación de estado agota el tiempo de espera, no cree una segunda tarea.
• No hace que las decisiones sean confiables por sí mismas. Una respuesta Noul de evaluate_decisions es una probabilidad, no un booleano. Valide contra sus propios casos etiquetados.

El perfil catalog no puede realizar llamadas pagas en absoluto. Las herramientas de imagen devuelven un resultado o una tarea, dependiendo del modelo. Video, música y 3D siempre devuelven tareas.

Donde todavía necesita las superficies HTTP simples

En nuestro pipeline mantuvimos los endpoints de descubrimiento HTTP junto a MCP para agentes que no son MCP. https://api.tokenlab.sh/llms.txt es una descripción general compacta con una primera solicitud, endpoints comunes y guía de errores. La documentación observada el 03-10-2026 no cubre el archivo llms-full.txt ni los archivos de instantáneas model-data de nuestro borrador anterior. Verifique esas URLs usted mismo antes de depender de ellas. Para el estado en vivo y los costos, consulte el catálogo de modelos público.

Preguntas frecuentes

¿Necesito una API key para usar el servidor MCP de TokenLab?

No, no para navegar. El perfil catalog enumera modelos, detalles, precios y comparaciones sin una clave. Las solicitudes de modelos pagos o multimedia requieren TOKENLAB_API_KEY en el entorno del servidor, con el perfil core o full.

¿Con qué perfil de MCP debería comenzar?

Comience con catalog si solo desea una mejor selección de modelos. Pase a core cuando el cliente deba llamar a modelos o crear contenido multimedia. Use full solo si el agente realmente necesita las APIs adicionales para desarrolladores.

¿En qué campos de modelo debería confiar un agente al elegir un modelo?

Confíe en accepted_request_formats para el endpoint, pricing con su unidad para el costo, los límites de tokens, supported_operations y lifecycle. Trate deliveryAvailability como soporte configurado, no como disponibilidad en vivo.

¿Por qué mi agente recibió un error 503 all_channels_failed?

Es posible que la operación no tenga suministro en el nivel de entrega seleccionado. Cuando retryable es false, no repita la solicitud. Verifique la disponibilidad con GET /v1/models y elija otro modelo con la aprobación del usuario.

¿El servidor MCP admite Gemini Files o cachedContents?

No. La documentación dice que Gemini Files, las subidas reanudables y cachedContents actualmente requieren llamadas HTTP. Las herramientas de archivos MCP utilizan la API /v1/files compatible con OpenAI.

Cree una clave en Console → API keys, luego añada el perfil catalog a su cliente con los comandos anteriores.