Servidor MCP de TokenLab

El servidor MCP de TokenLab genera herramientas MCP a partir del contrato OpenAPI público de TokenLab. Los agentes compatibles con MCP pueden descubrir modelos y precios, llamar a endpoints de LLM nativos y compatibles con OpenAI, crear medios multimodales, subir archivos y gestionar tareas asíncronas. Úsalo cuando un agente necesite el contrato actual de la API de TokenLab en lugar de una lista de herramientas mantenida manualmente. El perfil core predeterminado expone 29 herramientas de endpoint generadas más dos herramientas de descubrimiento compuestas. El perfil full expone 78 herramientas de endpoint generadas más las mismas dos herramientas compuestas. Esta página explica cómo añadir TokenLab como servidor de herramientas en Claude Code, Cursor, VS Code, Codex, Claude Desktop, Cline, Windsurf u otro cliente MCP. Para llamar a TokenLab directamente desde el código de una aplicación, empieza con el inicio rápido de la API.

Las herramientas de catálogo público y precios no requieren una clave de API de TokenLab. Configura TOKENLAB_API_KEY para operaciones de inferencia, medios, audio, archivos, tareas, embeddings, rerank y traducción que requieran credenciales. Nunca coloques una clave de API en los argumentos de las herramientas.

Lo que ofrece

Descubrimiento de modelos en tiempo real desde https://api.tokenlab.sh/v1/models.
Búsqueda de detalles de modelos desde /v1/models/{model}.
Búsqueda de precios desde /v1/models/{model}/pricing.
Resumen de la API legible por agentes desde https://api.tokenlab.sh/llms.txt.
Chat Completions y Responses compatibles con OpenAI, Anthropic Messages y Gemini generateContent sin aplanar sus estructuras de solicitud nativas.
Generación y edición de imágenes a través de URLs JSON, IDs de archivos de TokenLab o archivos multipart locales.
Video, música, 3D, voz, transcripción, traducción de audio, embeddings, embeddings multimodales, rerank y traducción de texto.
Resúmenes de tareas asíncronas normalizados para operaciones de generación de imágenes, video, música, 3D y mundos.
Una sincronización diaria del contrato que obtiene el documento OpenAPI público, regenera los esquemas de herramientas, ejecuta pruebas de endpoints y archivos, y actualiza main solo cuando todas las comprobaciones pasan.

Inicio rápido

La forma más rápida y segura de empezar es activar solo las seis herramientas del catálogo público. No requiere una clave de API de TokenLab y podrás habilitar las herramientas con credenciales más adelante.

Instalar en Cursor

Añade el perfil público catalog a Cursor con un clic

Instalar en VS Code

Añade el perfil público catalog a la configuración de usuario de VS Code

Comprobar los requisitos

Instala Node.js 18.17 o una versión posterior y confirma que npx esté disponible.

node --version
npx --version

No necesitas instalar globalmente el paquete MCP ni clonar su repositorio.

Elegir un nivel de acceso

Objetivo	Clave de API	Perfil
Consultar modelos, detalles y precios	No se requiere	`catalog` (6 herramientas)
Usar operaciones comunes de inferencia, medios, archivos y tareas	Se requiere para llamadas de pago	`core` (31 herramientas, predeterminado)
Exponer todas las operaciones de desarrollo permitidas	Se requiere para llamadas de pago	`full` (80 herramientas)

Crea una clave en Dashboard → API Keys solo si vas a realizar llamadas autenticadas. Guárdala en el entorno secreto del cliente y nunca la pegues en un prompt ni en los argumentos de una herramienta MCP.

Configurar el cliente

Los ejemplos públicos seleccionan catalog de forma explícita para que todas las herramientas expuestas funcionen sin clave.

Añade TokenLab al ámbito de usuario para utilizarlo en todos tus proyectos.

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

Para activar el perfil core predeterminado, añade en su lugar tu clave de API.

claude mcp add --env TOKENLAB_API_KEY=your-tokenlab-api-key --scope user tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server

Usa --scope local solo para el proyecto actual o --scope project para crear un .mcp.json compartido. No confirmes una clave real en la configuración del proyecto.

Usa la instalación con un clic o guarda la configuración en ~/.cursor/mcp.json para todos los proyectos o en .cursor/mcp.json para uno solo.

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

Usa la instalación con un clic, ejecuta MCP: Add Server o guarda este archivo como .vscode/mcp.json.

{
  "servers": {
    "tokenlab-model-catalog": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"],
      "env": { "TOKENLAB_MCP_TOOL_PROFILE": "catalog" }
    }
  }
}

Para una configuración disponible en todos los proyectos, ejecuta MCP: Open User Configuration y añade allí el mismo objeto de servidor.

# Catálogo público
codex mcp add --env TOKENLAB_MCP_TOOL_PROFILE=catalog tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server

# Perfil core predeterminado con clave de API
codex mcp add --env TOKENLAB_API_KEY=your-tokenlab-api-key tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server

Añade al objeto estándar mcpServers de claude_desktop_config.json el comando npx y los argumentos -y y @tokenlabai/mcp-server. Si solo necesitas herramientas públicas, configura TOKENLAB_MCP_TOOL_PROFILE=catalog.

Cline CLI puede instalar directamente el servidor stdio publicado.

cline mcp add tokenlab --yes -- npx -y @tokenlabai/mcp-server

En Windsurf, guarda la configuración estándar mcpServers en ~/.codeium/windsurf/mcp_config.json. Los demás clientes stdio usan el mismo comando y los mismos argumentos, sin directorio de trabajo.

Reiniciar y verificar

Reinicia o recarga el cliente MCP, aprueba el servidor local cuando se solicite y confirma que tokenlab-model-catalog esté conectado.

claude mcp list
codex mcp list

Después pide al agente que llame a list_models. Una lista de modelos no vacía confirma el inicio del servidor, el descubrimiento MCP y el acceso al catálogo público de TokenLab. Esta comprobación no requiere una clave de API.

Referencia de configuración

En cualquier cliente stdio local usa el nombre tokenlab-model-catalog, el comando npx, los argumentos separados -y y @tokenlabai/mcp-server, y deja vacío el directorio de trabajo. Usa @tokenlabai/mcp-server@0.6.17 para fijar la versión verificada actualmente. Configuración estándar para herramientas autenticadas:

{
  "mcpServers": {
    "tokenlab-model-catalog": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"],
      "env": {
        "TOKENLAB_API_KEY": "<TOKENLAB_API_KEY>",
        "TOKENLAB_MCP_TOOL_PROFILE": "core"
      }
    }
  }
}

VS Code usa un objeto servers en el nivel superior. Si el cliente espera un único objeto de servidor, copia solo el objeto interno con command, args y env.

Variable de entorno	Valor predeterminado	Finalidad
`TOKENLAB_API_BASE`	`https://api.tokenlab.sh`	Cambiar la URL base de la API, sin barra final.
`TOKENLAB_API_KEY`	Sin definir	Necesaria para llamadas autenticadas de inferencia, medios, archivos, tareas, embeddings, rerank y traducción.
`TOKENLAB_MCP_TOOL_PROFILE`	`core`	Elegir `catalog`, `core` o `full`.
`TOKENLAB_MCP_SCHEMA_MODE`	Valor del perfil	Elegir `portable`, `exact` o `strict`; normalmente conserva `portable`.
`TOKENLAB_REQUEST_TIMEOUT_MS`	`120000`	Tiempo de espera de la solicitud API en milisegundos.
`TOKENLAB_MCP_MAX_FILE_BYTES`	`104857600`	Tamaño máximo en bytes de cada archivo local subido.
`TOKENLAB_MCP_INLINE_BYTES`	`2097152`	Tamaño máximo de un resultado binario o JSON devuelto en línea.
`TOKENLAB_ARTIFACT_DIR`	Directorio temporal del sistema	Ubicación para escribir artefactos de respuesta grandes.

No publiques capturas, registros, historial del shell ni archivos de configuración que contengan una clave de API real. Usa las entradas secretas o variables de entorno del cliente, conserva marcadores en los ejemplos compartidos y rota cualquier clave expuesta.

Instalación desde el código fuente

Usa una copia del código fuente solo para auditar o desarrollar el servidor MCP. La configuración normal del cliente debe utilizar el paquete npm publicado que se muestra arriba.

git clone https://github.com/hedging8563/tokenlab-mcp-server.git
cd tokenlab-mcp-server
npm install
npm test
npm start

Los perfiles core y full publican por defecto esquemas portable con límites de tamaño y profundidad, mientras el servidor valida cada llamada con la definición OpenAPI completa. Usa exact para esquemas anidados completos o strict cuando el proveedor del modelo exija objetos cerrados y todas las propiedades en required.

Perfiles de herramientas generados

Perfil	Herramientas expuestas	Cobertura
`catalog`	6	Cuatro herramientas públicas generadas de catálogo y precios, más `compare_models` y `get_api_overview`. No requiere clave de API.
`core` (predeterminado)	31	29 herramientas de endpoint generadas más `compare_models` y `get_api_overview`. Cubre catálogo, precios, endpoints de LLM nativos, imágenes, video, música, 3D, audio, tareas, archivos, embeddings, rerank y traducción.
`full`	80	78 herramientas de endpoint generadas más las dos herramientas de descubrimiento compuestas. Añade ciclo de vida de respuestas, lotes, mundos, descubrimiento de modelos nativos y otras operaciones de desarrollador permitidas.

Los nombres de las herramientas, descripciones, esquemas de entrada, métodos HTTP, rutas, tipos de contenido, requisitos de autenticación y comportamiento de las tareas se generan a partir de la instantánea de OpenAPI registrada. Una capa exclusiva de MCP proporciona alias de herramientas estables, pertenencia a perfiles, semántica de tareas asíncronas, variantes multipart, omisión de secretos y restricciones de no transmisión (non-streaming). La versión 0.6.0 también devuelve JSON mediante structuredContent de MCP, publica tres recursos de contrato y ofrece dos plantillas de prompts para seleccionar modelos y construir solicitudes nativas. Las herramientas generadas y compuestas incluyen anotaciones de riesgo estándar para que los clientes compatibles puedan aplicar políticas de aprobación más seguras. Las herramientas core comunes incluyen:

Familia	Herramientas representativas
Catálogo y precios	`list_models`, `get_model`, `get_model_pricing`, `get_pricing`, `compare_models`
Endpoints de LLM nativos	`create_chat_completion`, `create_response`, `create_anthropic_message`, `create_gemini_content`
Imágenes	`create_image`, `create_image_file`, `edit_image`, `edit_image_file`
Video, música y 3D	`create_video`, `create_music`, `create_3d_model`
Audio	`create_speech`, `transcribe_audio`, `translate_audio`
Embeddings y texto	`create_embedding`, `create_multimodal_embedding`, `rerank_documents`, `translate_text`
Archivos y tareas	`upload_file`, `list_files`, `retrieve_file`, `retrieve_file_content`, `delete_file`, `get_task_status`, `cancel_task`

Las llamadas a herramientas MCP devuelven un resultado final. Las operaciones de solo transmisión y tiempo real están excluidas; el servidor fija internamente los argumentos stream admitidos en false sin exponer una constante booleana a los adaptadores del provider. Las respuestas pequeñas de imagen y audio devuelven contenido MCP nativo; las respuestas binarias más grandes se escriben en TOKENLAB_ARTIFACT_DIR y se devuelven con su ruta local, tipo MIME y recuento de bytes.

Resultados de medios asíncronos

La creación de video, música y 3D devuelve resúmenes de tareas asíncronas. La generación y edición de imágenes puede devolver un resultado completado o una tarea asíncrona, dependiendo del modelo y la solicitud seleccionados. Cuando delivery.mode es async, llama a get_task_status con { "id": delivery.task_id } hasta que delivery.terminal sea true. Determina la finalización a partir de status; progress es opcional y no debe usarse como condición terminal.

Flujo de trabajo recomendado para agentes

Llama a list_models cuando el usuario no haya nombrado un modelo.
Usa recommended_for para tareas que no sean de chat, como imágenes, video, música, 3D, TTS, STT, embeddings, rerank o traducción.
Llama a get_model antes de crear una solicitud que no sea de chat, reintentar una solicitud fallida o cambiar de familia de endpoints.
Llama a get_model_pricing cuando el costo del modelo afecte la elección del usuario.
Usa compare_models cuando la elección dependa de varios candidatos.
Llama a la herramienta generada que coincida con el contrato de API requerido, o usa get_api_overview para obtener un mapa compacto de las familias de la API de TokenLab.

Guía de endpoints nativos

TokenLab admite rutas compatibles con OpenAI y familias de endpoints nativos. El servidor MCP ayuda a un agente a elegir la ruta correcta antes de escribir código:

Familia	Ruta común
Chat compatible con OpenAI	`/v1/chat/completions`
Respuestas	`/v1/responses`
Anthropic Messages	`/v1/messages`
Gemini nativo	`/v1beta/models/{model}:generateContent`
Imágenes	`/v1/images/generations`, `/v1/images/edits`
Video	`/v1/videos/generations`
Música	`/v1/music/generations`
3D	`/v1/3d/generations`
Audio	`/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations`
Embeddings y rerank	`/v1/embeddings`, `/v1/rerank`
Traducción de texto	`/v1/translations`

Explorador de modelos alojado

Los clientes que admiten HTTP transmitible pueden conectarse a:

https://tokenlab-model-explorer.vercel.app/mcp

El explorador alojado es público y expone open_tokenlab_model_explorer, compare_tokenlab_models y generate_tokenlab_endpoint_example. Usa el servidor npm local anterior cuando necesites los perfiles core/full generados, subidas de archivos locales u operaciones de API con credenciales.

Úsalo con las habilidades de TokenLab

El servidor MCP es útil en tiempo de ejecución, mientras que el repositorio de habilidades de TokenLab enseña a los agentes de codificación cómo generar y reparar código de integración. Úsalos ambos cuando estén disponibles:

Servidor MCP: descubre modelos actuales, precios y detalles de endpoints.
Habilidad tokenlab-api-integration: genera ejemplos de API ejecutables y maneja errores estructurados de TokenLab.
Habilidad tokenlab-model-picker: elige modelos sólidos para la tarea del usuario.
Habilidad tokenlab-native-endpoints: decide cuándo usar rutas de Responses, Anthropic Messages, Gemini, medios, audio, embedding, rerank o traducción.

Solución de problemas

El cliente no puede iniciar el servidor

Confirma que Node.js sea al menos 18.17 y que el cliente encuentre npx. Ejecuta npx -y @tokenlabai/mcp-server en una terminal para mostrar errores de npm o de red. Un inicio stdio correcto espera silenciosamente mensajes MCP; termina con Ctrl+C después de comprobarlo.

El servidor está configurado pero no aparecen herramientas

Reinicia el cliente y aprueba el servidor local. En Claude Code revisa claude mcp list o /mcp; en VS Code, MCP: List Servers y Show Output; en Cursor, Settings → Tools & MCP.

Claude Code muestra Pending approval

Los servidores .mcp.json de proyecto requieren confianza en el workspace y aprobación explícita. Inicia Claude Code de forma interactiva en el proyecto, acepta la confianza y aprueba tokenlab-model-catalog en /mcp. Usa --scope user para una configuración privada disponible en todos los proyectos.

La lista de modelos está vacía

Verifica que la máquina pueda acceder a https://api.tokenlab.sh/v1/models. Si anulas TOKENLAB_API_BASE, asegúrate de que no incluya una barra diagonal al final.

El agente sigue eligiendo IDs de modelos obsoletos

Pide al agente que llame a list_models o get_model antes de codificar un nombre de modelo. Emparejar el servidor MCP con tokenlab-model-picker da mejores resultados.

¿Puede este servidor llamar a APIs de inferencia de pago de TokenLab?

Sí. Configura TOKENLAB_API_KEY, luego usa las herramientas generadas de LLM, medios, audio, tareas, archivos, embedding, rerank o traducción. Las herramientas de catálogo y precios siguen estando disponibles sin una clave.

Una herramienta autenticada devuelve un error de autenticación

Configura TOKENLAB_API_KEY en el entorno del servidor MCP, nunca en los argumentos de la herramienta ni en el prompt, y reinicia el cliente tras el cambio. Rota cualquier clave expuesta en un archivo compartido, imagen, registro o historial del shell.

El cliente rechaza los esquemas o carga demasiadas herramientas

Usa TOKENLAB_MCP_TOOL_PROFILE=catalog para 6 herramientas de descubrimiento o el perfil core predeterminado para 31. Mantén normalmente portable; usa exact para el anidamiento completo y strict para objetos cerrados con todas las propiedades en required.

¿Cómo fijo o actualizo la versión del paquete?

Usa @tokenlabai/mcp-server@0.6.17 para fijar la versión actualmente verificada. Para cambiarla, actualiza el argumento del paquete, reinicia el servidor y revisa el repositorio público antes de adoptar una versión más reciente.

Recursos

TokenLab MCP

Descripción del producto y opciones de conexión para los conjuntos Core 31 y Full 80

Repositorio de GitHub

Código fuente e instrucciones de configuración local

Habilidades de TokenLab

Habilidades de agente mantenidas para integraciones de TokenLab

API de catálogo de modelos

Endpoint de descubrimiento de modelos públicos

llms.txt

Resumen de la API de TokenLab legible por agentes

Servidor MCP de Glama

Ver el listado verificado del servidor MCP de TokenLab

Explorador de modelos de Glama

Explora modelos, precios y ejemplos de endpoints nativos

Listado en MCP.so

Descubre TokenLab en el directorio de IA y Agentes

Explorador de modelos alojado

Abre el explorador de modelos público y el endpoint MCP remoto

Guía MCP de Claude Code

Ámbitos, aprobaciones, comprobaciones de estado y configuración MCP

Guía MCP de Cursor

Ubicaciones de configuración, control de herramientas y seguridad

Guía MCP de VS Code

Configuración de usuario y workspace, confianza, registros y gestión de servidores

Matriz de compatibilidad

Herramientas de código

SDKs nativos

Frameworks y plataformas

Apps de chat

Servidor MCP de TokenLab

Lo que ofrece

Inicio rápido

Instalar en Cursor

Instalar en VS Code

Referencia de configuración

Instalación desde el código fuente

Perfiles de herramientas generados

Resultados de medios asíncronos

Flujo de trabajo recomendado para agentes

Guía de endpoints nativos

Explorador de modelos alojado

Úsalo con las habilidades de TokenLab

Solución de problemas

Recursos

TokenLab MCP

Repositorio de GitHub

Habilidades de TokenLab

API de catálogo de modelos

llms.txt

Servidor MCP de Glama

Explorador de modelos de Glama

Listado en MCP.so

Explorador de modelos alojado

Guía MCP de Claude Code

Guía MCP de Cursor

Guía MCP de VS Code

​Lo que ofrece

​Inicio rápido

Instalar en Cursor

Instalar en VS Code

​Referencia de configuración

​Instalación desde el código fuente

​Perfiles de herramientas generados

​Resultados de medios asíncronos

​Flujo de trabajo recomendado para agentes

​Guía de endpoints nativos

​Explorador de modelos alojado

​Úsalo con las habilidades de TokenLab

​Solución de problemas

​Recursos

TokenLab MCP

Repositorio de GitHub

Habilidades de TokenLab

API de catálogo de modelos

llms.txt

Servidor MCP de Glama

Explorador de modelos de Glama

Listado en MCP.so

Explorador de modelos alojado

Guía MCP de Claude Code

Guía MCP de Cursor

Guía MCP de VS Code

Lo que ofrece

Inicio rápido

Referencia de configuración

Instalación desde el código fuente

Perfiles de herramientas generados

Resultados de medios asíncronos

Flujo de trabajo recomendado para agentes

Guía de endpoints nativos

Explorador de modelos alojado

Úsalo con las habilidades de TokenLab

Solución de problemas

Recursos