Servidor MCP do TokenLab

O servidor MCP do TokenLab gera ferramentas MCP a partir do contrato OpenAPI público do TokenLab. Agentes compatíveis com MCP podem descobrir modelos e preços, chamar endpoints de LLM nativos e compatíveis com OpenAI, criar mídia multimodal, fazer upload de arquivos e gerenciar tarefas assíncronas. Use-o quando um agente precisar do contrato atual da API do TokenLab em vez de uma lista de ferramentas mantida manualmente. O perfil core padrão expõe 29 ferramentas de endpoint geradas, além de duas ferramentas de descoberta compostas. O perfil full expõe 78 ferramentas de endpoint geradas, além das mesmas duas ferramentas compostas. Esta página mostra como adicionar o TokenLab como servidor de ferramentas no Claude Code, Cursor, VS Code, Codex, Claude Desktop, Cline, Windsurf ou outro cliente MCP. Para chamar o TokenLab diretamente pelo código da aplicação, comece pelo início rápido da API.

As ferramentas de catálogo público e preços não exigem uma chave de API do TokenLab. Defina TOKENLAB_API_KEY para operações de inferência, mídia, áudio, arquivos, tarefas, embeddings, rerank e tradução que exijam credenciais. Nunca coloque uma chave de API nos argumentos das ferramentas.

O que ele oferece

Descoberta de modelos em tempo real a partir de https://api.tokenlab.sh/v1/models.
Consulta de detalhes de modelos a partir de /v1/models/{model}.
Consulta de preços a partir de /v1/models/{model}/pricing.
Visão geral da API legível por agentes a partir de https://api.tokenlab.sh/llms.txt.
Chat Completions e Responses compatíveis com OpenAI, Anthropic Messages e Gemini generateContent sem achatar seus formatos de requisição nativos.
Geração e edição de imagens através de URLs JSON, IDs de arquivo do TokenLab ou arquivos multipart locais.
Vídeo, música, 3D, fala, transcrição, tradução de áudio, embeddings, embeddings multimodais, rerank e tradução de texto.
Resumos de tarefas assíncronas normalizados para operações de imagem, vídeo, música, 3D e geração de mundos.
Uma sincronização diária de contrato que busca o documento OpenAPI público, regenera esquemas de ferramentas, executa testes de endpoint e arquivos, e atualiza a main apenas quando todas as verificações passam.

Início rápido

A forma mais rápida e segura de começar é ativar apenas as seis ferramentas do catálogo público. Não é necessário ter uma chave de API do TokenLab, e você pode habilitar ferramentas autenticadas depois.

Instalar no Cursor

Adicione o perfil público catalog ao Cursor com um clique

Instalar no VS Code

Adicione o perfil público catalog à configuração de usuário do VS Code

Verificar os requisitos

Instale o Node.js 18.17 ou mais recente e confirme que o npx está disponível.

node --version
npx --version

Não é necessário instalar globalmente o pacote MCP nem clonar o repositório.

Escolher um nível de acesso

Objetivo	Chave de API	Perfil
Consultar modelos, detalhes e preços	Não é necessária	`catalog` (6 ferramentas)
Usar operações comuns de inferência, mídia, arquivo e tarefa	Necessária para chamadas pagas	`core` (31 ferramentas, padrão)
Expor todas as operações de desenvolvimento permitidas	Necessária para chamadas pagas	`full` (80 ferramentas)

Crie uma chave em Dashboard → API Keys somente para chamadas autenticadas. Guarde-a no ambiente secreto do cliente e nunca a cole em um prompt ou argumento de ferramenta MCP.

Configurar o cliente

Os exemplos públicos selecionam explicitamente catalog, para que todas as ferramentas expostas funcionem sem chave.

Adicione o TokenLab no escopo do usuário para usá-lo em todos os projetos.

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

Para ativar o perfil core padrão, adicione sua chave de API.

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

Use --scope local apenas no projeto atual ou --scope project para criar um .mcp.json compartilhado. Não envie uma chave real para a configuração do projeto.

Use a instalação com um clique ou salve a configuração em ~/.cursor/mcp.json para todos os projetos ou em .cursor/mcp.json para apenas um projeto.

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

Use a instalação com um clique, execute MCP: Add Server ou salve este arquivo como .vscode/mcp.json.

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

Para uma configuração disponível em todos os projetos, execute MCP: Open User Configuration e adicione o mesmo 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 padrão com chave de API
codex mcp add --env TOKENLAB_API_KEY=your-tokenlab-api-key tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server

Adicione ao objeto padrão mcpServers de claude_desktop_config.json o comando npx e os argumentos -y e @tokenlabai/mcp-server. Se precisar apenas das ferramentas públicas, defina TOKENLAB_MCP_TOOL_PROFILE=catalog.

O Cline CLI pode instalar diretamente o servidor stdio publicado.

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

No Windsurf, salve a configuração padrão mcpServers em ~/.codeium/windsurf/mcp_config.json. Outros clientes stdio usam o mesmo comando e argumentos, sem diretório de trabalho.

Reiniciar e verificar

Reinicie ou recarregue o cliente MCP, aprove o servidor local quando solicitado e confirme que tokenlab-model-catalog está conectado.

claude mcp list
codex mcp list

Depois, peça ao agente para chamar list_models. Uma lista de modelos não vazia confirma a inicialização do servidor, a descoberta MCP e o acesso ao catálogo público do TokenLab. Essa verificação não requer chave de API.

Referência de configuração

Em qualquer cliente stdio local, use o nome tokenlab-model-catalog, o comando npx, os argumentos separados -y e @tokenlabai/mcp-server, e deixe o diretório de trabalho vazio. Use @tokenlabai/mcp-server@0.6.17 para fixar a versão atualmente verificada. Configuração padrão para ferramentas autenticadas:

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

O VS Code usa um objeto servers no nível superior. Se o cliente espera um único objeto de servidor, copie apenas o objeto interno com command, args e env.

Variável de ambiente	Padrão	Finalidade
`TOKENLAB_API_BASE`	`https://api.tokenlab.sh`	Alterar a URL base da API, sem barra final.
`TOKENLAB_API_KEY`	Não definida	Necessária para chamadas autenticadas de inferência, mídia, arquivo, tarefa, embedding, rerank e tradução.
`TOKENLAB_MCP_TOOL_PROFILE`	`core`	Escolher `catalog`, `core` ou `full`.
`TOKENLAB_MCP_SCHEMA_MODE`	Padrão do perfil	Escolher `portable`, `exact` ou `strict`; normalmente mantenha `portable`.
`TOKENLAB_REQUEST_TIMEOUT_MS`	`120000`	Tempo limite da solicitação de API em milissegundos.
`TOKENLAB_MCP_MAX_FILE_BYTES`	`104857600`	Tamanho máximo em bytes de cada arquivo local enviado.
`TOKENLAB_MCP_INLINE_BYTES`	`2097152`	Tamanho máximo de um resultado binário ou JSON retornado em linha.
`TOKENLAB_ARTIFACT_DIR`	Diretório temporário do sistema	Local de gravação de artefatos de resposta maiores.

Não publique capturas de tela, logs, histórico do shell ou arquivos de configuração que contenham uma chave de API real. Prefira entradas secretas ou variáveis de ambiente do cliente, use marcadores em exemplos compartilhados e troque qualquer chave exposta.

Instalação pelo código-fonte

Use uma cópia do código-fonte apenas para auditar ou desenvolver o servidor MCP. A configuração normal do cliente deve usar o pacote npm publicado mostrado acima.

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

Os perfis core e full publicam por padrão esquemas portable com limites de tamanho e profundidade, enquanto o servidor valida cada chamada com a definição OpenAPI completa. Use exact para esquemas aninhados completos ou strict quando o provedor do modelo exigir objetos fechados e todas as propriedades em required.

Perfis de Ferramentas Geradas

Perfil	Ferramentas expostas	Cobertura
`catalog`	6	Quatro ferramentas públicas geradas de catálogo e preços, mais `compare_models` e `get_api_overview`. Não requer chave de API.
`core` (padrão)	31	29 ferramentas de endpoint geradas mais `compare_models` e `get_api_overview`. Cobre catálogo, preços, endpoints de LLM nativos, imagens, vídeo, música, 3D, áudio, tarefas, arquivos, embeddings, rerank e tradução.
`full`	80	78 ferramentas de endpoint geradas mais as duas ferramentas de descoberta compostas. Adiciona ciclo de vida de resposta, lotes, mundos, descoberta de modelos nativos e outras operações de desenvolvedor permitidas.

Nomes de ferramentas, descrições, esquemas de entrada, métodos HTTP, caminhos, tipos de conteúdo, requisitos de autenticação e comportamento de tarefas são gerados a partir do snapshot OpenAPI registrado. Uma camada exclusiva para MCP fornece aliases de ferramentas estáveis, associação de perfil, semântica de tarefas assíncronas, variantes multipart, omissão de segredos e restrições de não-streaming. A versão 0.6.0 também retorna JSON por meio de structuredContent do MCP, publica três recursos de contrato e oferece dois modelos de prompt para seleção de modelos e construção de solicitações nativas. As ferramentas geradas e compostas incluem anotações de risco padrão para que clientes compatíveis possam aplicar políticas de aprovação mais seguras. Ferramentas comuns do core incluem:

Família	Ferramentas representativas
Catálogo e preços	`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`
Imagens	`create_image`, `create_image_file`, `edit_image`, `edit_image_file`
Vídeo, música e 3D	`create_video`, `create_music`, `create_3d_model`
Áudio	`create_speech`, `transcribe_audio`, `translate_audio`
Embeddings e texto	`create_embedding`, `create_multimodal_embedding`, `rerank_documents`, `translate_text`
Arquivos e tarefas	`upload_file`, `list_files`, `retrieve_file`, `retrieve_file_content`, `delete_file`, `get_task_status`, `cancel_task`

As chamadas de ferramentas MCP retornam um resultado final. Operações exclusivas de streaming e em tempo real são excluídas; o servidor fixa internamente os argumentos stream suportados como false sem expor uma constante booleana aos adaptadores do provider. Respostas pequenas de imagem e áudio retornam conteúdo MCP nativo; respostas binárias maiores são gravadas em TOKENLAB_ARTIFACT_DIR e retornadas com seu caminho local, tipo MIME e contagem de bytes.

Resultados de Mídia Assíncrona

A criação de vídeo, música e 3D retorna resumos de tarefas assíncronas. A geração e edição de imagens podem retornar um resultado concluído ou uma tarefa assíncrona, dependendo do modelo e da requisição selecionados. Quando delivery.mode for async, chame get_task_status com { "id": delivery.task_id } até que delivery.terminal seja true. Determine a conclusão a partir de status; progress é opcional e não deve ser usado como condição terminal.

Fluxo de Trabalho Recomendado para Agentes

Chame list_models quando o usuário não tiver nomeado um modelo.
Use recommended_for para tarefas que não sejam de chat, como imagem, vídeo, música, 3D, TTS, STT, embeddings, rerank ou tradução.
Chame get_model antes de criar uma requisição que não seja de chat, tentar novamente uma requisição falha ou alternar famílias de endpoints.
Chame get_model_pricing quando o custo do modelo afetar a escolha do usuário.
Use compare_models quando a escolha depender de vários candidatos.
Chame a ferramenta gerada que corresponde ao contrato de API necessário, ou use get_api_overview para um mapa compacto das famílias de API do TokenLab.

Orientação sobre Endpoints Nativos

O TokenLab suporta rotas compatíveis com OpenAI e famílias de endpoints nativos. O servidor MCP ajuda um agente a escolher a rota certa antes de escrever o código:

Família	Rota comum
Chat compatível com OpenAI	`/v1/chat/completions`
Respostas	`/v1/responses`
Anthropic Messages	`/v1/messages`
Gemini nativo	`/v1beta/models/{model}:generateContent`
Imagens	`/v1/images/generations`, `/v1/images/edits`
Vídeo	`/v1/videos/generations`
Música	`/v1/music/generations`
3D	`/v1/3d/generations`
Áudio	`/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations`
Embeddings e rerank	`/v1/embeddings`, `/v1/rerank`
Tradução de texto	`/v1/translations`

Explorador de Modelos Hospedado

Clientes que suportam HTTP Streamable podem se conectar a:

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

O explorador hospedado é público e expõe open_tokenlab_model_explorer, compare_tokenlab_models e generate_tokenlab_endpoint_example. Use o servidor npm local acima quando precisar dos perfis core/full gerados, uploads de arquivos locais ou operações de API com credenciais.

Use com Habilidades (Skills) do TokenLab

O servidor MCP é útil em tempo de execução, enquanto o repositório de habilidades do TokenLab ensina agentes de codificação a gerar e reparar código de integração. Use ambos quando disponíveis:

Servidor MCP: descubra modelos atuais, preços e detalhes de endpoints.
Habilidade tokenlab-api-integration: gere exemplos de API executáveis e lide com erros estruturados do TokenLab.
Habilidade tokenlab-model-picker: escolha modelos robustos para a tarefa do usuário.
Habilidade tokenlab-native-endpoints: decida quando usar rotas de Responses, Anthropic Messages, Gemini, mídia, áudio, embedding, rerank ou tradução.

Solução de Problemas

O cliente não consegue iniciar o servidor

Confirme que o Node.js está na versão 18.17 ou superior e que o cliente encontra npx. Execute npx -y @tokenlabai/mcp-server no terminal para mostrar erros de npm ou rede. Uma inicialização stdio bem-sucedida aguarda silenciosamente mensagens MCP; encerre com Ctrl+C após a verificação.

O servidor está configurado, mas nenhuma ferramenta aparece

Reinicie o cliente e aprove o servidor local. No Claude Code, verifique claude mcp list ou /mcp; no VS Code, MCP: List Servers e Show Output; no Cursor, Settings → Tools & MCP.

O Claude Code mostra Pending approval

Servidores .mcp.json do projeto exigem confiança no workspace e aprovação explícita. Inicie o Claude Code de forma interativa no projeto, aceite a confiança e aprove tokenlab-model-catalog em /mcp. Use --scope user para uma configuração privada disponível em todos os projetos.

A lista de modelos está vazia

Verifique se a máquina consegue acessar https://api.tokenlab.sh/v1/models. Se você substituir TOKENLAB_API_BASE, certifique-se de que não inclua uma barra final.

O agente ainda escolhe IDs de modelos obsoletos

Peça ao agente para chamar list_models ou get_model antes de codificar um nome de modelo. Combinar o servidor MCP com a tokenlab-model-picker gera melhores resultados.

Este servidor pode chamar APIs de inferência pagas do TokenLab?

Sim. Defina TOKENLAB_API_KEY e, em seguida, use as ferramentas geradas de LLM, mídia, áudio, tarefas, arquivos, embedding, rerank ou tradução. As ferramentas de catálogo e preços permanecem disponíveis sem uma chave.

Uma ferramenta autenticada retorna erro de autenticação

Defina TOKENLAB_API_KEY no ambiente do servidor MCP, nunca nos argumentos da ferramenta ou no prompt, e reinicie o cliente após a alteração. Troque qualquer chave exposta em arquivo compartilhado, imagem, log ou histórico do shell.

O cliente rejeita schemas ou carrega ferramentas demais

Use TOKENLAB_MCP_TOOL_PROFILE=catalog para 6 ferramentas de descoberta ou o perfil core padrão para 31. Normalmente mantenha portable; use exact para aninhamento completo e strict para objetos fechados com todas as propriedades em required.

Como fixar ou atualizar a versão do pacote?

Use @tokenlabai/mcp-server@0.6.17 para fixar a versão atualmente verificada. Para alterar, atualize o argumento do pacote, reinicie o servidor e revise o repositório público antes de adotar uma versão mais recente.

Recursos

TokenLab MCP

Visão geral do produto e opções de conexão para os conjuntos Core 31 e Full 80

Repositório GitHub

Código-fonte e instruções de configuração local

Habilidades do TokenLab

Habilidades de agente mantidas para integrações com TokenLab

API de Catálogo de Modelos

Endpoint público de descoberta de modelos

llms.txt

Visão geral da API do TokenLab legível por agentes

Servidor MCP Glama

Veja a listagem verificada do servidor MCP do TokenLab

Explorador de Modelos Glama

Explore modelos, preços e exemplos de endpoints nativos

Listagem MCP.so

Descubra o TokenLab no diretório de IA e Agentes

Explorador de Modelos Hospedado

Abra o explorador de modelos público e o endpoint MCP remoto

Guia MCP do Claude Code

Escopos, aprovações, verificações de status e configuração MCP

Guia MCP do Cursor

Locais de configuração, controle de ferramentas e segurança

Guia MCP do VS Code

Configuração de usuário e workspace, confiança, logs e gerenciamento de servidores

Matriz de compatibilidade

Ferramentas de código

SDKs nativos

Frameworks e plataformas

Apps de chat

Servidor MCP do TokenLab

O que ele oferece

Início rápido

Instalar no Cursor

Instalar no VS Code

Referência de configuração

Instalação pelo código-fonte

Perfis de Ferramentas Geradas

Resultados de Mídia Assíncrona

Fluxo de Trabalho Recomendado para Agentes

Orientação sobre Endpoints Nativos

Explorador de Modelos Hospedado

Use com Habilidades (Skills) do TokenLab

Solução de Problemas

Recursos

TokenLab MCP

Repositório GitHub

Habilidades do TokenLab

API de Catálogo de Modelos

llms.txt

Servidor MCP Glama

Explorador de Modelos Glama

Listagem MCP.so

Explorador de Modelos Hospedado

Guia MCP do Claude Code

Guia MCP do Cursor

Guia MCP do VS Code

​O que ele oferece

​Início rápido

Instalar no Cursor

Instalar no VS Code

​Referência de configuração

​Instalação pelo código-fonte

​Perfis de Ferramentas Geradas

​Resultados de Mídia Assíncrona

​Fluxo de Trabalho Recomendado para Agentes

​Orientação sobre Endpoints Nativos

​Explorador de Modelos Hospedado

​Use com Habilidades (Skills) do TokenLab

​Solução de Problemas

​Recursos

TokenLab MCP

Repositório GitHub

Habilidades do TokenLab

API de Catálogo de Modelos

llms.txt

Servidor MCP Glama

Explorador de Modelos Glama

Listagem MCP.so

Explorador de Modelos Hospedado

Guia MCP do Claude Code

Guia MCP do Cursor

Guia MCP do VS Code

O que ele oferece

Início rápido

Referência de configuração

Instalação pelo código-fonte

Perfis de Ferramentas Geradas

Resultados de Mídia Assíncrona

Fluxo de Trabalho Recomendado para Agentes

Orientação sobre Endpoints Nativos

Explorador de Modelos Hospedado

Use com Habilidades (Skills) do TokenLab

Solução de Problemas

Recursos