Ferramentas de código

Servidor MCP do TokenLab

Dê ao Claude Code, Cursor, VS Code, Codex e outros clientes MCP acesso aos modelos e APIs do TokenLab

Escolha o que seu agente precisa

  • O MCP adiciona ferramentas da API do TokenLab a um cliente compatível. Comece com a configuração catalog (sem chave) abaixo.
  • TokenLab Agent Skills ensinam ao agente o método para um resultado, como qual modelo escolher e como verificar a saída. Eles não iniciam um servidor MCP, e podem usar essas ferramentas MCP quando ambos estiverem instalados.

Instale a skill de seleção de modelo: npx skills add hedging8563/tokenlab-skills --skill tokenlab-model-picker

tokenlab-skills no GitHub.

Ambos estendem um agente existente. Alterar seu provedor de modelo principal utiliza o guia de configuração do próprio cliente.

Deixe meu agente configurar isso

Copie esta tarefa para um agente já em execução no seu computador:

Read this guide and choose MCP catalog tools or a Skill for my task:
https://tokenlab.sh/docs/pt/integrations/tokenlab-mcp-server
Check my installed version and active configuration first.
Preserve existing accounts, providers, permissions and other settings.
Back up local files and show proposed changes.
Have me enter any API key locally; never ask for, print or paste it in chat.
Check configuration loading first.
Explain any paid request test separately before running it.

O Servidor MCP do TokenLab permite que um cliente MCP navegue pelos modelos e preços atuais, envie solicitações de modelo, crie mídia, trabalhe com arquivos e verifique tarefas assíncronas.

Use o perfil catalog para navegar pelos modelos e preços sem uma chave de API. Adicione TOKENLAB_API_KEY quando o cliente precisar fazer solicitações de modelos pagos ou de mídia.

Mantenha sua chave de API do TokenLab no ambiente do servidor MCP. Nunca a cole em um prompt ou argumento de ferramenta.

Requisitos

Instale o Node.js 18.17 ou mais recente e certifique-se de que o npx esteja disponível:

node --version
npx --version

O pacote npm é executado localmente via stdio. Você não precisa de uma instalação global ou de um checkout do código-fonte.

Escolha o que o cliente pode usar

PerfilChave de APIInclui
catalogNão necessáriaLista de modelos, detalhes de modelos, preços, comparações e visão geral da API
coreNecessária para chamadas pagasFerramentas comuns de chat, decisão, mídia, áudio, arquivo, tarefa, embedding, rerank e tradução
fullNecessária para chamadas pagascore mais APIs adicionais para desenvolvedores

Comece com catalog se você deseja apenas uma melhor seleção de modelos. Use core quando o cliente precisar criar conteúdo ou chamar um modelo. full é para clientes que realmente precisam do conjunto de ferramentas maior.

Adicione o servidor

Faça backup da configuração ativa. Adicione apenas a entrada do TokenLab e preserve os provedores, contas, seleção de modelo padrão e permissões existentes. Se o nome já estiver sendo usado, escolha outro nome e atualize os comandos. Para desfazer a configuração, remova apenas a entrada adicionada ou restaure o backup anterior.

Adicione o catálogo público para sua conta de usuário:

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

Para usar ferramentas pagas, substitua a variável de ambiente do perfil por TOKENLAB_API_KEY e armazene a chave através do seu método normal de gerenciamento de segredos. Use --scope local para um projeto. Nunca faça commit de uma chave real em um .mcp.json compartilhado.

Habilitar ferramentas pagas

Crie uma chave de API em Console → API keys, então defina ambas as variáveis no ambiente do servidor MCP:

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

Use a entrada de segredo do seu cliente quando disponível. Se uma chave real aparecer em um arquivo compartilhado, captura de tela, log ou histórico do shell, revogue-a e crie uma nova chave.

Verificar a conexão

Reinicie ou recarregue o cliente MCP, aprove o servidor local se solicitado e confirme se o tokenlab está conectado.

# Claude Code
claude mcp list

# Codex
codex mcp list

Peça ao cliente para chamar list_models. Uma lista não vazia confirma que o pacote iniciou e alcançou o TokenLab. O perfil catalog não precisa de uma chave de API.

Ferramentas úteis

A disponibilidade das ferramentas depende do perfil selecionado. Tarefas comuns incluem:

  • listar modelos e ler as capacidades de um modelo
  • ler preços atuais do TokenLab ou comparar vários modelos
  • enviar Chat Completions, Responses, Anthropic Messages ou solicitaçõ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
  • criar embeddings ou reclassificar (rerank) documentos
  • verificar e cancelar tarefas assíncronas suportadas

O cliente deve solicitar aprovação antes de uma chamada paga quando o preço ou a escolha do modelo ainda não tiverem sido confirmados.

As ferramentas de arquivo MCP usam a API /v1/files compatível com OpenAI. Gemini Files, uploads retomáveis e cachedContents atualmente exigem chamadas HTTP e não estão incluídos nos perfis MCP. Veja Gemini Files and cache.

Modelos de decisão

Use core ou full para chamar um modelo de decisão System One. Primeiro, chame list_models com {"category":"decision"} e get_model com o ID do modelo selecionado. Mantenha o modelo de chat principal do agente configurado separadamente.

Para o Jev 1.13, chame a ferramenta com state e questions nativos:

{
  "name": "evaluate_decisions",
  "arguments": {
    "model": "jev-1.13",
    "state": { "ticket": "Please refund the duplicate payment." },
    "questions": {
      "refund_requested": {
        "type": "noul",
        "instructions": "Does the customer explicitly request a refund?"
      }
    }
  }
}

Verifique isError, então leia structuredContent.answers e structuredContent.usage. Uma resposta Noul é um número de probabilidade, não um booleano. Preserve o ID da solicitação de _meta quando disponível. A ferramenta retorna um resultado síncrono; ela não usa o fluxo de polling de tarefas assíncronas.

Com o tempo limite de solicitação do servidor padrão de 120.000 ms, permita pelo menos 150.000 ms para a chamada da ferramenta do cliente. Se você alterar TOKENLAB_REQUEST_TIMEOUT_MS, mantenha o tempo limite do cliente maior. Um tempo limite deixa o resultado incerto; inspecione a solicitação antes de reenviar uma chamada paga. Valide as decisões em relação aos seus próprios casos rotulados antes de usá-las para conduzir ações.

Mídia assíncrona

Ferramentas de vídeo, música e 3D retornam uma tarefa em vez de um arquivo finalizado. Ferramentas de imagem podem retornar um resultado concluído ou uma tarefa, dependendo do modelo.

Quando um resultado inclui uma delivery assíncrona, chame get_task_status com seu ID de tarefa até que o status esteja concluído ou falho. Não crie uma segunda tarefa porque uma verificação de status expirou.

Configurações opcionais

VariávelPadrãoUso
TOKENLAB_API_BASEhttps://api.tokenlab.shHost da API do TokenLab personalizado; omita a barra final
TOKENLAB_MCP_TOOL_PROFILEcorecatalog, core ou full
TOKENLAB_REQUEST_TIMEOUT_MS120000Tempo limite da solicitação em milissegundos
TOKENLAB_MCP_MAX_FILE_BYTES104857600Tamanho máximo de upload local por arquivo
TOKENLAB_ARTIFACT_DIRDiretório temporário do SOOnde arquivos grandes baixados são salvos

Use os padrões, a menos que seu cliente ou implantação tenha um requisito específico.

Solução de problemas

Explorador de modelos hospedado

Clientes que suportam HTTP Streamable podem usar o explorador de modelos público em:

https://mcp.tokenlab.sh/mcp

Use o servidor npm local para chamadas de API pagas, uploads de arquivos locais ou os perfis core e full.

Configure notificações de tarefas com a API de gerenciamento de Webhooks, autenticada com um Management Token mt-…. O MCP full usa TOKENLAB_MANAGEMENT_TOKEN. Pare de fazer polling de tarefas terminais em caso de erros 401/403/404 ou erros que não podem ser repetidos.

Nesta página