TokenLab MCP Server

Servidor MCP para descoberta de modelos TokenLab, precificação, orientação de endpoints nativos e auxiliares de inferência opcionais.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP TokenLab

CI npm npm downloads

Servidor Model Context Protocol gerado a partir de OpenAPI para descoberta pública de modelos TokenLab, preços, endpoints LLM nativos, decisões tipadas, geração multimodal, tarefas assíncronas, arquivos, embeddings, rerank, tradução, recursos, prompts e a API de desenvolvedor mais ampla.

Ele expõe ferramentas de catálogo público para agentes que precisam escolher modelos, inspecionar formatos de solicitação suportados ou comparar preços antes de chamar APIs TokenLab. Ferramentas com credenciais cobrem inferência de texto, geração e edição de imagens, vídeo, música, 3D, sondagem de tarefas assíncronas, embeddings, rerank, decisões tipadas e tradução de texto.

Perfis de Ferramentas Gerados

O manifesto generated/tools.json verificado é gerado a partir do documento OpenAPI público da TokenLab, mais a pequena sobreposição somente-MCP em contract/mcp-overlay.json. A versão 0.6.24 gera 87 ferramentas de endpoint; com as duas ferramentas compostas de descoberta somente-MCP, o perfil completo retorna 89 ferramentas de tools/list.

PerfilFerramentas de endpointTotal de ferramentas registradasEsquema voltado ao modeloCobertura
catalog46ExatoDescoberta pública de modelos e preços apenas; nenhuma chave de API necessária
core (padrão)3032PortátilCatálogo e preços; Chat Completions, Responses, Anthropic Messages, Gemini generateContent; decisões tipadas System One; imagens, vídeo, música, 3D, fala e transcrição; tarefas assíncronas; arquivos; embeddings, rerank e tradução
full8789PortátilToda operação de API de desenvolvedor permitida no snapshot OpenAPI verificado, incluindo núcleo mais ciclo de vida de resposta, lotes, mundos e descoberta nativa de modelos

A contagem total registrada é o número retornado por tools/list. Todos os perfis incluem compare_models e get_api_overview, produzindo totais de 6, 32 e 89 ferramentas. Operações em tempo real e somente streaming são excluídas porque chamadas de ferramentas MCP stdio retornam um único resultado final. Operações de API que aceitam stream corrigem-no internamente para false sem expor um booleano const aos adaptadores de provedor, e a chave de API da string de consulta Gemini é intencionalmente ocultada dos argumentos da ferramenta.

A projeção portátil mantém cada argumento de nível superior, mas limita formas profundamente aninhadas voltadas ao modelo. O servidor ainda valida chamadas contra o esquema OpenAPI completo gerado antes de emitir uma solicitação de API. Orçamentos de compatibilidade mantêm core em no máximo 60 KB e profundidade 8, e full em no máximo 100 KB e profundidade 8 para a resposta completa de tools/list. Testes também executam o perfil completo através da versão do Google AI SDK usada na falha observada do OpenCode/Gemini.

Defina TOKENLAB_MCP_TOOL_PROFILE=catalog para a menor lista de ferramentas somente públicas ou TOKENLAB_MCP_TOOL_PROFILE=full para a API de desenvolvedor ampla. Defina TOKENLAB_MCP_SCHEMA_MODE=exact somente quando um cliente precisar do JSON Schema aninhado completo e puder aceitar sua carga de ferramenta maior/mais profunda. Use strict para provedores que exigem que cada propriedade seja listada em required e que cada objeto defina additionalProperties: false; argumentos complexos de nível superior são representados como strings codificadas em JSON e decodificados antes da validação canônica. Nomes canônicos de ferramentas, descrições, JSON Schemas de entrada, ligações HTTP, tipos de conteúdo, requisitos de autenticação e comportamento de tarefas podem ser inspecionados em generated/tools.json.

O menor generated/public-contract.json é a projeção legível por máquina usada pelo site da TokenLab e outros consumidores públicos. Ele contém identidade do pacote, contagens de perfil, camadas principais de ferramentas, recursos, prompts e hashes de origem sem copiar todos os esquemas de endpoint.

Recursos MCP Nativos

  • Respostas JSON de ferramentas incluem structuredContent enquanto retêm texto serializado para clientes mais antigos.
  • Erros HTTP retêm o texto original da resposta (até 4.000 caracteres), incluindo dicas públicas de correção, junto com status estruturado, ID de solicitação e tempo de nova tentativa. Apenas o ID de solicitação e cabeçalhos de nova tentativa são expostos; solicitações de geração com falha nunca são reenviadas automaticamente.
  • Ferramentas geradas expõem títulos legíveis por humanos, anotações padrão somente leitura/destrutivas/idempotentes/mundo aberto e IDs de solicitação de resposta quando disponíveis.
  • Esquemas de ferramentas são publicados e validados diretamente como JSON Schema. O runtime não faz ida e volta de esquemas de ferramentas gerados através de Zod; o modo exact é equivalente em forma de bytes ao esquema canônico gerado.
  • Três recursos expõem a visão geral da API ao vivo, o snapshot OpenAPI do pacote e o contrato público MCP compacto.
  • Prompts choose_tokenlab_model e build_tokenlab_request orientam agentes a usar a verdade do modelo ao vivo e preservar formas nativas de endpoint.
  • Instruções do servidor dizem aos clientes para confirmar operações faturáveis ou destrutivas e tratar saída externa de modelo/API como conteúdo não confiável.

Execução

npm install
npm start

Instale a partir do npm:

npx -y @tokenlabai/mcp-server

Instaladores assistidos por agente podem seguir llms-install.md para uma configuração segura de credenciais e fluxo de verificação.

Execute em Docker:

docker build -t tokenlab-mcp-server .
docker run --rm -i tokenlab-mcp-server

Adicione -e TOKENLAB_API_KEY ao usar ferramentas de API com credenciais. Ferramentas de catálogo público não exigem chave.

Configuração estilo Claude Desktop:

{
  "mcpServers": {
    "tokenlab-model-catalog": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"],
      "env": {
        "TOKENLAB_API_BASE": "https://api.tokenlab.sh"
      }
    }
  }
}

Nenhuma chave de API TokenLab é necessária para operações públicas de catálogo e preços. Defina TOKENLAB_API_KEY quando ferramentas com credenciais devem chamar APIs TokenLab. Ferramentas geradas preservam a forma de solicitação OpenAPI para endpoints compatíveis com OpenAI e nativos em vez de achatá-los em um formato de prompt compartilhado.

Operações multipart aceitam caminhos de arquivo locais. Pequenas respostas de imagem e áudio são retornadas como conteúdo MCP nativo; respostas binárias maiores ou outras são gravadas em TOKENLAB_ARTIFACT_DIR e retornadas como caminho com tipo MIME e contagem de bytes.

Resultados de Mídia Síncronos e Assíncronos

Ferramentas de criação de vídeo, música e 3D sempre retornam uma tarefa assíncrona. Geração e edição de imagens podem retornar um resultado concluído ou uma tarefa assíncrona dependendo do modelo e solicitação selecionados.

Ferramentas de mídia preservam a resposta completa da API TokenLab sob response e adicionam um resumo normalizado delivery:

{
  "delivery": {
    "mode": "async",
    "task_id": "ldtask_...",
    "status": "pending",
    "poll_url": "/v1/tasks/ldtask_...",
    "terminal": false,
    "next_tool": "get_task_status"
  },
  "response": {}
}

Use delivery.mode em vez de assumir que todas as solicitações de imagem são síncronas. Para tarefas assíncronas, chame get_task_status com { "id": delivery.task_id } até que delivery.terminal seja true. A conclusão é determinada a partir de status, não de um campo de progresso opcional.

Ambiente

  • TOKENLAB_API_BASE: opcional, padrão https://api.tokenlab.sh
  • TOKENLAB_API_KEY: opcional; necessário para inferência de texto, geração multimodal, tarefa assíncrona, embedding, rerank, decisão e ferramentas de tradução
  • TOKENLAB_MCP_TOOL_PROFILE: opcional, catalog, core (padrão) ou full
  • TOKENLAB_MCP_SCHEMA_MODE: opcional, portable, exact ou strict; padrão para o modo testado do perfil selecionado
  • TOKENLAB_REQUEST_TIMEOUT_MS: tempo limite de solicitação opcional em milissegundos, padrão 120000
  • TOKENLAB_MCP_MAX_FILE_BYTES: tamanho máximo opcional de upload local por arquivo, padrão 104857600 (100 MiB)
  • TOKENLAB_MCP_INLINE_BYTES: tamanho máximo opcional de resposta binária/JSON retornada inline, padrão 2097152 (2 MiB)
  • TOKENLAB_ARTIFACT_DIR: diretório de saída opcional para artefatos de resposta não inline, padrão para o diretório temporário do SO sob tokenlab-mcp

Para entradas de imagem Chat Completions, prefira URLs de dados precisos em bytes, como data:image/png;base64,.... Se um chamador MCP rotular uma carga PNG, JPEG, WebP ou GIF reconhecida como application/octet-stream, o servidor corrige esse MIME genérico antes de encaminhar. Uma carga binária genérica não reconhecida é rejeitada localmente com um erro de entrada preciso.

Sincronização de Contrato

O documento OpenAPI público é a fonte do contrato de API. A sobreposição contém apenas escolhas específicas de MCP: exposição de perfil, aliases estáveis de ferramentas, omissão de segredos, restrições de não streaming, variantes de tipo de conteúdo, semântica de tarefas assíncronas e a projeção pública compacta consumida pelo site e portões de documentação.

npm run contract:source-check # compare the snapshot with the live canonical OpenAPI (read-only)
npm run contract:check        # check generated output against the checked-in snapshot (offline)
npm run contract:sync         # fetch OpenAPI and regenerate; refuses dirty outputs or a stale branch
npm test                      # compile profiles and test exact/portable/strict schemas, provider conversion, routing, tasks, files, and binary output

Sempre execute git pull --ff-only antes de uma sincronização manual de contrato. contract:check prova consistência interna apenas; contract:source-check prova atualização contra a fonte canônica. O fluxo de trabalho agendado Sync TokenLab OpenAPI contract executa a sequência completa de escrita e confirma apenas o snapshot OpenAPI verificado e o manifesto gerado para main. Uma busca com falha, branch local desatualizado, saída gerada suja, erro de geração, erro de compilação de esquema ou teste deixa o contrato rastreado inalterado.

Metadados do Registro MCP

Este repositório inclui server.json para o Registro MCP oficial.

Metadados de lançamento:

  • pacote npm: @tokenlabai/mcp-server@0.6.24
  • nome do registro MCP: io.github.hedging8563/tokenlab
  • package.json.mcpName: io.github.hedging8563/tokenlab

Para um novo lançamento:

  1. Aumente as versões correspondentes em package.json, package-lock.json e server.json.
  2. Envie uma tag correspondente, como v0.6.0.
  3. O fluxo de trabalho de publicação testa e publica npm através de publicação confiável, depois publica a entrada do Registro MCP através de GitHub Actions OIDC.

O mesmo fluxo de trabalho pode ser executado manualmente a partir de main para republicar apenas os metadados atuais do Registro MCP. Nenhum token npm ou Registro MCP é armazenado no GitHub.

Segurança

Use o perfil catalog quando nenhuma ferramenta com credenciais for necessária. Mantenha TOKENLAB_API_KEY no ambiente secreto do cliente MCP local, habilite confirmação humana para chamadas faturáveis e destrutivas e revise anotações de ferramentas antes de conceder aprovação persistente. Não envie uma chave de API TokenLab para um servidor MCP hospedado não confiável.

Links

Gerenciamento de webhooks

Use o perfil full para configurar webhooks de workspace com list_webhooks, create_webhook, get_webhook, update_webhook, delete_webhook, rotate_webhook_secret, test_webhook e list_webhook_deliveries.

Defina TOKENLAB_MANAGEMENT_TOKEN=mt-... separadamente de TOKENLAB_API_KEY=sk-.... Crie o token de gerenciamento em Dashboard → API → Management Tokens. Ele autoriza operações de gerenciamento apenas dentro do seu workspace e não é limitado a webhooks. A chave de inferência não pode substituí-lo; o whsec_... retornado pela criação/rotação é apenas para verificação de assinatura do receptor. Mantenha todas as credenciais fora de argumentos de ferramentas e prompts.

Notificações de webhook evitam sondagem contínua de tarefas. Em um fallback de sondagem, pare em status terminal, 401/403/404 ou retryable: false; recue em falhas transitórias. Veja o guia completo de webhooks para cargas, assinatura, deduplicação e histórico de entrega.