Un agente de codificación que elige un ID de modelo desde la memoria eventualmente elegirá uno que ya no existe. Se entera a través de un error 404 o una factura sorprendente. TokenLab ofrece a los agentes un catálogo público y en vivo para consultar primero: la API de modelos, un servidor MCP y archivos de texto plano. Con ellos, un agente puede verificar el ID, el formato de solicitud y el precio antes de escribir cualquier código de integración. Esta guía cubre el servidor MCP, los campos de modelo en los que un agente puede confiar para el enrutamiento, y un flujo de descubrimiento, verificación y llamada.
Puntos clave
- El servidor MCP de TokenLab tiene tres perfiles:
catalog(sin API key),coreyfull. Navegar por modelos y precios no requiere una clave en ningún perfil. Las llamadas pagas encoreyfullsí la necesitan. - Con una clave y el perfil
coreofull, el servidor también puede enviar solicitudes de modelos, crear contenido multimedia, manejar archivos y verificar tareas asíncronas. - Enrute basándose en
tokenlab.accepted_request_formats,tokenlab.request_format_summary,tokenlab.pricing,tokenlab.lifecycleytokenlab.deliveryAvailability. No codifique de forma rígida el orden de las recomendaciones. - Gemini Files, las cargas reanudables y
cachedContentsno están en ningún perfil MCP. - Nunca pegue una API key en un prompt o en un argumento de herramienta.
Qué le ofrece el servidor MCP de TokenLab a un agente de codificación
El servidor MCP de TokenLab permite a un cliente MCP navegar por los modelos y precios actuales, enviar solicitudes de modelos, crear contenido multimedia, trabajar con archivos y verificar tareas asíncronas. Sus herramientas se dividen en tres capas:
| Capa | Requiere clave | Herramientas |
|---|---|---|
| Descubrimiento (Discover) | No | list_models, get_model, get_pricing, get_model_pricing, compare_models, get_api_overview |
| Creación (Create) | Sí | create_chat_completion, create_response, create_anthropic_message, create_gemini_content, evaluate_decisions, create_image, edit_image, create_video, create_music, create_3d_model, create_speech, transcribe_audio, translate_audio |
| Operación (Operate) | Sí | upload_file, list_files, retrieve_file, get_task_status, cancel_task, create_embedding, rerank_documents, translate_text |
Algunas herramientas quedan fuera de la tabla, como las variantes de imagen basadas en archivos. Qué herramientas ve un cliente depende del perfil:
| Perfil | API key | Incluye |
|---|---|---|
catalog |
No requerida | Lista de modelos, detalles de modelos, precios, comparaciones, resumen de la API |
core |
Solo para llamadas pagas | Herramientas comunes de chat, decisión, multimedia, audio, archivos, tareas, embedding, rerank y traducción |
full |
Solo 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. La guía del catálogo de modelos MCP muestra los mensajes MCP detrás de las herramientas de descubrimiento.
Instale 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. Los comandos a continuación provienen de la documentación del servidor MCP. La versión 0.6.45 es la más reciente en npm al 11-11-2026.
Claude Code:
claude mcp add \
--env TOKENLAB_MCP_TOOL_PROFILE=catalog \
--scope user \
tokenlab -- \
npx -y @tokenlabai/mcp-server@0.6.45
Codex:
codex mcp add \
--env TOKENLAB_MCP_TOOL_PROFILE=catalog \
tokenlab -- \
npx -y @tokenlabai/mcp-server@0.6.45
Cursor (~/.cursor/mcp.json o .cursor/mcp.json):
{
"mcpServers": {
"tokenlab": {
"command": "npx",
"args": ["-y", "@tokenlabai/mcp-server@0.6.45"],
"env": {
"TOKENLAB_MCP_TOOL_PROFILE": "catalog"
}
}
}
}
VS Code utiliza .vscode/mcp.json con una clave servers y "type": "stdio". Claude Desktop utiliza la misma estructura que Cursor en claude_desktop_config.json. La página de documentación tiene ambos.
Para habilitar las herramientas pagas, cree una clave en Console → API keys y configure ambas variables en el entorno del servidor:
{
"env": {
"TOKENLAB_API_KEY": "<TOKENLAB_API_KEY>",
"TOKENLAB_MCP_TOOL_PROFILE": "core"
}
}
Reinicie el cliente y ejecute claude mcp list o codex mcp list. Luego, 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, un registro o el historial de la terminal, revóquela y cree una nueva.
Un flujo de agente: Descubrir, Verificar, Llamar
Tomemos un agente que debe añadir generación de imágenes a una aplicación Node.js. Cada valor a continuación se leyó de la API de modelos en vivo el 11-11-2026.
1. Descubrir. Solicite la lista corta actual. Llame a list_models con estos argumentos, o use HTTP plano:
{ "recommended_for": "image" }
curl "https://api.tokenlab.sh/v1/models?recommended_for=image"
Los valores válidos de recommended_for son image, video, music, 3d, tts, stt, embedding, rerank, translation y decision. Supongamos que el agente elige nano-banana-pro.
2. Verificar el endpoint y el precio. Llame a get_model, o GET /v1/models/nano-banana-pro (API de modelos en vivo). Para este modelo, informa:
- estado
active, con disponibilidad de entrega tanto Verified como Official. - operaciones:
text-to-image,image-to-imageyimage-edit. - endpoint de solicitud para cada operación, en
tokenlab.request_format_summary.request_endpoint_by_operation:/v1/images/generationspara los tres. - precio: por imagen. El precio Verified es de $0.067 para la solicitud predeterminada de 1k text-to-image. Entre resoluciones y operaciones, varía de $0.067 a $0.12. El rango Official es de $0.134 a $0.24.
El endpoint es específico para cada modelo. gpt-image-2 envía text-to-image a /v1/images/generations pero image-edit a /v1/images/edits, y se cobra por token, por ejemplo $3.50 por cada 1M de tokens de entrada de texto y $21.00 por cada 1M de tokens de salida de imagen (Verified). Un agente que asumiera un único endpoint y una única estructura de precios para cada modelo de imagen escribiría código incorrecto. Lea los campos por modelo.
3. Realizar la llamada. Envíe el ID del modelo elegido explícitamente. 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 no han sido confirmados. Una solicitud construida a partir de los campos anteriores, siguiendo la referencia de Crear Imagen:
curl https://api.tokenlab.sh/v1/images/generations \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "nano-banana-pro",
"prompt": "A red bicycle leaning on a white wall",
"operation": "text-to-image",
"aspect_ratio": "1:1",
"resolution": "1k"
}'
Algunas solicitudes de imagen devuelven la imagen final en la respuesta y esperan a que se genere, así que establezca un tiempo de espera (timeout) del cliente de al menos 120 segundos. Si la respuesta tiene task_id o poll_url, consulte GET /v1/tasks/{id}.
Para un modelo de chat, el formato aceptado decide el endpoint. gpt-5.6-terra acepta openai_chat_completions y openai_responses (API de modelos en vivo), por lo que el SDK estándar de OpenAI 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)
Para una estimación de costos, gpt-5.6-terra cobra $0.60 por cada 1M de tokens de entrada (Verified) hasta 272K tokens de entrada. Un prompt de 10,000 tokens cuesta entonces aproximadamente 10,000 / 1,000,000 × $0.60 = $0.006 por entrada, antes de la salida. Por encima de los 272K tokens de entrada, toda la solicitud pasa a un nivel superior a $1.20 de entrada y $5.40 de salida por cada 1M de tokens.
Qué campos de la API de modelos debe confiar un agente para el enrutamiento
Lea estos campos desde GET /v1/models/{model} (Obtener un modelo):
| Campo | Qué significa para el enrutamiento |
|---|---|
tokenlab.accepted_request_formats |
Qué familia de endpoints utiliza un modelo de chat: openai_chat_completions es /v1/chat/completions, openai_responses es /v1/responses, anthropic_messages es /v1/messages, gemini_generate_content es /v1beta/models/{model}:generateContent |
tokenlab.request_format_summary |
Para modelos que no son de chat: el endpoint para cada operación, los parámetros admitidos, valores aceptados y límites. Léalo antes de construir una solicitud. |
tokenlab.pricing, official_pricing, pricing_unit |
El precio Verified, el precio Official y la unidad de facturación, como per_token o per_image. Los campos Verified son null cuando el modelo no tiene una oferta Verified. |
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 deprecación, modelo de reemplazo |
tokenlab.deliveryAvailability |
Soporte configurado 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 TokenLab indica no depender de su orden.
Solo para precios, GET /v1/models/{model}/pricing es el endpoint exclusivo de precios. Algunos modelos tienen niveles. seedance-2.0, por ejemplo, tiene precios de salida que dependen de la resolución y de si la solicitud incluye entrada de video. Varían de $2.28 a $7.315 por cada 1M de tokens (Verified), y de $2.40 a $7.70 al precio Official. El endpoint de precios para seedance-2.0 enumera cada nivel. Precios leídos el 11-11-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 enumera campos opcionales como did_you_mean, suggestions, hint, retryable y retry_after. Maneje primero el estado HTTP y el code. Un 400 model_not_found puede incluir did_you_mean. Muéstreselo 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
- No cambia el proveedor de modelos principal de su cliente. Use la guía de configuración propia de ese cliente.
- No cubre Gemini Files, cargas reanudables o
cachedContents. Estos requieren llamadas HTTP. Consulte Gemini Files y caché. - No es la Skill. Las instrucciones de instalación de TokenLab Agent Skills con
npx skills addno inician ningún servidor MCP. - Si una verificación de estado para una tarea asíncrona expira, no cree una segunda tarea. Verifique la primera nuevamente.
- No hace que una decisión sea confiable por sí misma. Una respuesta Noul de
evaluate_decisionses una probabilidad, no un booleano. Valídela 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. Las herramientas de video, música y 3D siempre devuelven tareas.
HTTP plano y superficies de archivos
Para agentes que no usan MCP, TokenLab también publica archivos legibles por máquina. https://api.tokenlab.sh/llms.txt es un resumen compacto de la API con una primera solicitud, endpoints comunes, filtros de modelos y guía de errores. https://tokenlab.sh/llms-full.txt enumera los endpoints nativos y los archivos de descubrimiento con más detalle. El Centro de Datos de Modelos documenta los archivos del catálogo público catalog.json, latest.json y summary.md. Para ver el estado y los precios en vivo, consulte el catálogo de Modelos.
Preguntas frecuentes (FAQ)
¿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 pagas o de contenido multimedia requieren TOKENLAB_API_KEY en el entorno del servidor, con el perfil core o full.
¿Con qué perfil 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 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 o request_format_summary 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 tiempo real.
¿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. Gemini Files, las cargas 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.
Fuentes
Precio observado el 2026-11-11
- TokenLab docs: TokenLab MCP ServerObservado el 2026-11-11
- TokenLab MCP server on GitHubObservado el 2026-11-11
- TokenLab docs: Errors agents can act onObservado el 2026-11-11
- TokenLab docs: Get a ModelObservado el 2026-11-11
- TokenLab docs: Create ImageObservado el 2026-11-11
- TokenLab model API: nano-banana-proObservado el 2026-11-11
- TokenLab model API: gpt-image-2Observado el 2026-11-11
- TokenLab model API: gpt-5.6-terraObservado el 2026-11-11



