TokenLab for Agents: Modelos legíveis por máquina, precificação, SDKs e MCP

Um agente de codificação que escolhe um ID de modelo da memória acabará escolhendo um que não existe mais, e só descobrirá isso após um 404 ou uma fatura surpreendente. O MCP do TokenLab oferece ao agente um catálogo em tempo real para consulta prévia, permitindo verificar o ID, o formato de requisição aceito e o preço antes de escrever qualquer código de integração. Originalmente, descrevemos o servidor como estritamente somente leitura. A documentação observada em 03/10/2026 diz o contrário, portanto, esta versão corrige isso e adiciona um fluxo de trabalho detalhado.

Principais conclusões

• O servidor MCP do TokenLab possui três perfis: catalog (sem chave de API), core e full. Apenas o catalog dispensa chave.
• Com uma chave, ele também pode enviar requisições de modelo, criar mídia, manipular arquivos e verificar tarefas assíncronas. Ele não é somente leitura.
• Utilize as rotas tokenlab.accepted_request_formats, tokenlab.pricing, tokenlab.lifecycle e tokenlab.deliveryAvailability. Não faça hard-code da ordem de recomendação.
• Gemini Files, uploads resumíveis e cachedContents não estão em nenhum perfil MCP.
• Nunca cole uma chave de API em um prompt ou argumento de ferramenta.

O que o servidor MCP do TokenLab oferece a um agente de codificação

De acordo com a documentação do servidor MCP (observada em 03/10/2026), o Servidor MCP do TokenLab permite que um cliente navegue pelos modelos e preços atuais, envie requisições de modelo, crie mídia, trabalhe com arquivos e verifique tarefas assíncronas. A documentação lista estas capacidades:

• listar modelos e ler as capacidades de um modelo específico (list_models, get_model)
• ler preços atuais ou comparar vários modelos
• enviar Chat Completions, Responses, Anthropic Messages ou requisições Gemini
• avaliar decisões tipadas com evaluate_decisions
• criar ou editar imagens; criar vídeo, música, 3D, fala, transcrição ou tradução
• fazer upload e recuperar arquivos através da API /v1/files compatível com OpenAI
• criar embeddings ou rerank de documentos
• verificar e cancelar tarefas assíncronas suportadas (get_task_status para polling)

A documentação não lista nomes de ferramentas para precificação ou visão geral da API nesta versão. Nosso rascunho anterior mencionava get_model_pricing e get_api_overview. Verifique a lista de ferramentas do seu cliente conectado antes de confiar nesses dois nomes.

A disponibilidade das ferramentas depende do perfil:

Perfil	Chave de API	Inclui
catalog	Não necessária	Lista de modelos, detalhes do modelo, preços, comparações, visão geral da API
core	Necessária para chamadas pagas	Ferramentas comuns de chat, decisão, mídia, áudio, arquivo, tarefa, embedding, rerank e tradução
full	Necessária para chamadas pagas	core mais APIs adicionais para desenvolvedores

Comece com o catalog se você deseja apenas uma melhor seleção de modelos. Use o core quando o cliente precisar criar conteúdo ou chamar um modelo.

Instale o servidor MCP do TokenLab no seu cliente

O pacote requer Node.js 18.17 ou superior e npx. Ele roda localmente via stdio, portanto, não é necessária uma instalação global. Faça backup da sua configuração ativa primeiro e adicione apenas a entrada do TokenLab. Estes comandos vêm da documentação, observada em 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 ou .cursor/mcp.json):

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

O VS Code usa .vscode/mcp.json com uma chave servers e "type": "stdio". O Claude Desktop usa o mesmo formato do Cursor em claude_desktop_config.json. Copie ambos da página de documentação.

Para habilitar ferramentas pagas, crie uma chave em Console → API keys e defina ambas as variáveis no ambiente do servidor:

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

Em seguida, reinicie o cliente e execute claude mcp list ou codex mcp list. Peça ao agente para chamar list_models. Uma lista não vazia confirma que o pacote iniciou e alcançou o TokenLab. Se uma chave real for parar em um arquivo compartilhado, log ou histórico de shell, revogue-a e crie uma nova.

Fluxo de um agente: descobrir, verificar, chamar

Aqui está o fluxo que usamos. Imagine um agente solicitado a adicionar geração de imagens a um aplicativo Node.js. Cada valor abaixo vem da documentação e das páginas de modelos ao vivo observadas em 03/10/2026.

1. Descobrir. Peça a lista atual, com a ferramenta MCP ou HTTP simples:

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

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

Os valores válidos para recommended_for são image, video, music, 3d, tts, stt, embedding, rerank e translation. Digamos que o agente escolha nano-banana-pro.

2. Verificar formatos e preço. Chame get_model ou GET /v1/models/nano-banana-pro (API de modelo ao vivo, observada em 03/10/2026). Ele relata:

• formatos de requisição aceitos: gemini_generate_content, que mapeia para /v1beta/models/{model}:generateContent
• capacidades: image-edit, image-to-image, text-to-image
• preço: per_request de 0,067 USD, com uma faixa de preço de 0,067 a 0,12 (precificação atualizada em 02/10/2026 às 16:53:30.068Z)

Um agente que assumisse Chat Completions teria escrito o código errado. Compare com gpt-image-2 (API de modelo ao vivo). Ele não lista formatos de requisição aceitos e é precificado por token a 3,5 USD de entrada e 21 USD de saída por 1 milhão de tokens. O formato de preço difere por modelo, então o agente deve lê-lo para cada modelo.

3. Fazer a chamada. Para um modelo de chat, a verificação de formato decide o endpoint. gpt-5.6-terra aceita openai_chat_completions e openai_responses (API de modelo ao vivo, observada em 03/10/2026), portanto, o SDK padrão 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)

Envie o ID do modelo escolhido explicitamente. A documentação afirma que o TokenLab não o substitui silenciosamente. O cliente deve pedir aprovação antes de uma chamada paga se o preço ou a escolha do modelo ainda não estiverem confirmados.

Para uma estimativa de custo, gpt-5.6-terra cobra 0,6 USD por 1 milhão de tokens de entrada até 272 mil tokens de entrada. Um prompt de 10.000 tokens custa cerca de 10.000 / 1.000.000 × 0,6 = 0,006 USD para entrada (estimativa, antes da saída). Acima de 272 mil tokens de entrada, toda a requisição passa para a camada superior a 1,2 USD de entrada e 5,4 USD de saída.

Quais campos da API de modelo um agente deve confiar para roteamento

Leia estes campos de GET /v1/models/{model} (Get a Model, observado em 03/10/2026):

Campo	O que significa para o roteamento
tokenlab.accepted_request_formats	Qual família de endpoint usar: openai_chat_completions é /v1/chat/completions, openai_responses é /v1/responses, anthropic_messages é /v1/messages
tokenlab.pricing / pricing_unit	Preço público atual e sua unidade de cobrança, como per_token ou per_image
tokenlab.max_input_tokens, max_output_tokens	Limites de contexto e saída. Para gpt-5.6-terra: 1.050.000 e 128.000
tokenlab.supported_operations	Operações como text-to-image ou image-to-video
tokenlab.lifecycle	Disponibilidade, data de lançamento, data de depreciação, modelo substituto
tokenlab.deliveryAvailability	Suporte configurado como verified e official. Um campo ausente significa desconhecido

Duas precauções se aplicam. Primeiro, um formato aceito confirma o endpoint, mas ferramentas e campos individuais ainda podem variar por modelo. Segundo, deliveryAvailability é um suporte configurado, não uma garantia em tempo real. Trate os resultados de recommended_for como uma lista de sugestões, pois a documentação diz para não fixar a ordem deles.

Apenas para preços, GET /v1/models/{model}/pricing é o endpoint exclusivo de precificação. Entradas complexas podem conter níveis. seedance-2.0, por exemplo, tem preços de saída dependentes de resolução e entrada de vídeo, variando de 2,04 a 6,545 USD por 1 milhão de tokens (API de modelo ao vivo, observada em 03/10/2026).

Campos de erro que orientam a recuperação

Em erros de Chat Completions e Responses compatíveis com OpenAI, o guia de erros (observado em 03/10/2026) lista campos opcionais: did_you_mean, suggestions, hint, retryable e retry_after. Trate o status HTTP e o code primeiro. Um 400 model_not_found pode conter did_you_mean. Mostre isso ao usuário em vez de trocar de modelo silenciosamente. Um 503 all_channels_failed pode ter retryable: false, e repetir a requisição não ajudará. Anthropic Messages e Gemini mantêm seus formatos de erro nativos.

O que o servidor MCP não faz

A documentação afirma estes limites:

• Ele não altera o provedor de modelo principal do seu cliente. Use o guia de configuração do próprio cliente.
• Ele não cobre Gemini Files, uploads resumíveis ou cachedContents. Esses exigem chamadas HTTP, conforme Gemini Files and cache.
• Ele não é a Skill. A TokenLab Skill instala instruções com npx skills add e não inicia nenhum servidor MCP.
• Ele não faz polling para você em caso de timeout. Se uma verificação de status expirar, não crie uma segunda tarefa.
• Ele não torna as decisões confiáveis por si só. Uma resposta "Noul" de evaluate_decisions é uma probabilidade, não um booleano. Valide contra seus próprios casos rotulados.

O perfil catalog não pode fazer chamadas pagas. Ferramentas de imagem retornam um resultado ou uma tarefa, dependendo do modelo. Vídeo, música e 3D sempre retornam tarefas.

Onde você ainda precisa das superfícies HTTP simples

Em nosso pipeline, mantivemos os endpoints de descoberta HTTP junto com o MCP para agentes não-MCP. https://api.tokenlab.sh/llms.txt é uma visão geral compacta com uma primeira requisição, endpoints comuns e orientação de erro. A documentação observada em 03/10/2026 não cobre o arquivo llms-full.txt ou os arquivos de snapshot model-data do nosso rascunho anterior. Verifique essas URLs antes de depender delas. Para status e custos ao vivo, consulte o catálogo de modelos público.

FAQ

Preciso de uma chave de API para usar o servidor MCP do TokenLab?

Não, não para navegar. O perfil catalog lista modelos, detalhes, preços e comparações sem uma chave. Requisições de modelos pagos ou mídia precisam de TOKENLAB_API_KEY no ambiente do servidor, com o perfil core ou full.

Com qual perfil MCP devo começar?

Comece com catalog se você deseja apenas uma melhor seleção de modelos. Mude para core quando o cliente precisar chamar modelos ou criar mídia. Use full apenas se o agente realmente precisar das APIs extras para desenvolvedores.

Em quais campos de modelo um agente deve confiar ao escolher um modelo?

Confie em accepted_request_formats para o endpoint, pricing com sua unidade para custo, limites de tokens, supported_operations e lifecycle. Trate deliveryAvailability como suporte configurado, não disponibilidade em tempo real.

Por que meu agente recebeu um erro 503 all_channels_failed?

A operação pode não ter suprimento na camada de entrega selecionada. Quando retryable for false, não repita a requisição. Verifique a disponibilidade com GET /v1/models e escolha outro modelo com a aprovação do usuário.

O servidor MCP suporta Gemini Files ou cachedContents?

Não. A documentação diz que Gemini Files, uploads resumíveis e cachedContents atualmente exigem chamadas HTTP. As ferramentas de arquivo do MCP usam a API /v1/files compatível com OpenAI.

Crie uma chave em Console → API keys, então adicione o perfil catalog ao seu cliente com os comandos acima.