> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Servidor MCP do TokenLab

> Conecte clientes MCP à descoberta de modelos, preços, chat compatível com OpenAI e endpoints de inferência nativos do TokenLab.

O [servidor MCP do TokenLab](https://github.com/hedging8563/tokenlab-mcp-server) oferece aos agentes compatíveis com MCP descoberta de modelos em tempo real, preços, Chat Completions compatível com OpenAI e ferramentas de inferência nativas.

Use-o quando um agente precisar comparar modelos, inspecionar formatos de solicitação, consultar preços ou chamar o TokenLab por OpenAI Chat Completions, Responses, Anthropic Messages ou Gemini generateContent.

<Note>
  As ferramentas do catálogo público não exigem uma chave de API do TokenLab. Defina `TOKENLAB_API_KEY` para usar as quatro ferramentas de inferência pagas.
</Note>

## 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`.
* Orientação sobre famílias de endpoints para chat compatível com OpenAI, Responses, Anthropic Messages, Gemini, mídia, áudio, embeddings, rerank e tradução.
* Inferência opcional por Chat Completions compatível com OpenAI, Responses, Anthropic Messages e Gemini generateContent.

## Instalação a partir do GitHub

Clone o repositório público e instale as dependências:

```bash theme={null}
git clone https://github.com/hedging8563/tokenlab-mcp-server.git
cd tokenlab-mcp-server
npm install
npm test
```

Inicie o servidor via stdio:

```bash theme={null}
npm start
```

A variável de ambiente opcional `TOKENLAB_API_BASE` tem como padrão `https://api.tokenlab.sh`.

## Instalar no Codex

Adicione o servidor de catálogo público à configuração do Codex:

```bash theme={null}
codex mcp add tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server
```

Inicie uma nova sessão do Codex depois de adicionar o servidor. As ferramentas de catálogo público não exigem `TOKENLAB_API_KEY`.

Para ativar as ferramentas de inferência, inclua sua chave de API do TokenLab ao adicionar o servidor:

```bash theme={null}
codex mcp add --env TOKENLAB_API_KEY=your-tokenlab-api-key tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server
```

## Instalar no Cline

Instale o servidor stdio publicado com a CLI do Cline:

```bash theme={null}
cline mcp add tokenlab --yes -- npx -y @tokenlabai/mcp-server
```

O comando foi verificado com a CLI do Cline e termina sem avisos de configuração. As ferramentas públicas de catálogo funcionam imediatamente; defina `TOKENLAB_API_KEY` no ambiente do Cline para usar as ferramentas de inferência.

## Configuração do Claude Desktop

Adicione o pacote npm publicado à configuração do seu cliente MCP:

```json theme={null}
{
  "mcpServers": {
    "tokenlab-model-catalog": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"]
    }
  }
}
```

Reinicie o cliente MCP após salvar a configuração.

## Cursor, Windsurf e outros clientes MCP

Use o mesmo comando e argumentos em qualquer cliente que suporte servidores MCP via stdio:

```json theme={null}
{
  "command": "npx",
  "args": ["-y", "@tokenlabai/mcp-server"],
  "env": {
    "TOKENLAB_API_BASE": "https://api.tokenlab.sh"
  }
}
```

Se o seu cliente armazenar servidores nomeados, use `tokenlab-model-catalog` como o nome do servidor.

## Ferramentas

| Ferramenta                 | Objetivo                                                                                                                                       |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_models`              | Lista modelos públicos do TokenLab. Opcionalmente, filtre com `recommended_for` como `image`, `video`, `embedding`, `rerank` ou `translation`. |
| `get_model`                | Busca detalhes públicos e o formato de solicitação suportado de um modelo.                                                                     |
| `get_model_pricing`        | Busca detalhes de preços públicos de um modelo.                                                                                                |
| `compare_models`           | Compara detalhes e preços de vários IDs de modelo.                                                                                             |
| `create_chat_completion`   | Chama o endpoint compatível com OpenAI `/v1/chat/completions`, com mensagens multimodais e chamadas de ferramentas. Exige `TOKENLAB_API_KEY`.  |
| `create_response`          | Chama o endpoint `/v1/responses`. Exige `TOKENLAB_API_KEY`.                                                                                    |
| `create_anthropic_message` | Chama o endpoint Anthropic Messages `/v1/messages`. Exige `TOKENLAB_API_KEY`.                                                                  |
| `create_gemini_content`    | Chama o endpoint nativo do Gemini `generateContent`. Exige `TOKENLAB_API_KEY`.                                                                 |
| `get_api_overview`         | Busca a visão geral `llms.txt` do TokenLab para orientação de endpoint legível por agentes.                                                    |

As ferramentas de inferência retornam resultados JSON normais. O streaming é desativado intencionalmente em chamadas de ferramentas MCP.

## Fluxo de trabalho recomendado para agentes

1. Chame `list_models` quando o usuário não tiver nomeado um modelo.
2. 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.
3. Chame `get_model` antes de criar uma solicitação que não seja de chat, tentar novamente uma solicitação com falha ou alternar famílias de endpoints.
4. Chame `get_model_pricing` quando o custo do modelo afetar a escolha do usuário.
5. Use `compare_models` quando a escolha depender de vários candidatos.
6. Chame a ferramenta de inferência correspondente ao contrato de API necessário ou use `get_api_overview` para ver 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 o agente a escolher a rota correta antes de escrever o código:

| Família                    | Rota comum                                                               |
| -------------------------- | ------------------------------------------------------------------------ |
| Chat compatível com OpenAI | `/v1/chat/completions`                                                   |
| Responses                  | `/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 com suporte a Streamable HTTP podem se conectar a:

```text theme={null}
https://tokenlab-model-explorer.vercel.app/mcp
```

O explorador hospedado é público e oferece `open_tokenlab_model_explorer`, `compare_tokenlab_models` e `generate_tokenlab_endpoint_example`. Use o servidor npm local acima para todas as nove ferramentas ou inferência com credenciais.

## Use com as Skills do TokenLab

O servidor MCP é útil em tempo de execução, enquanto o [repositório de skills do TokenLab](https://github.com/hedging8563/tokenlab-skills) 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.
* Skill `tokenlab-api-integration`: gere exemplos de API executáveis e lide com erros estruturados do TokenLab.
* Skill `tokenlab-model-picker`: escolha modelos robustos para a tarefa do usuário.
* Skill `tokenlab-native-endpoints`: decida quando usar rotas de Responses, Anthropic Messages, Gemini, mídia, áudio, embedding, rerank ou tradução.

## Solução de problemas

<AccordionGroup>
  <Accordion title="O cliente não consegue iniciar o servidor">
    Confirme que o Node.js seja 18.17 ou superior e execute `npx -y @tokenlabai/mcp-server` uma vez no terminal para ver erros de npm ou rede.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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 o `tokenlab-model-picker` gera melhores resultados.
  </Accordion>

  <Accordion title="Este servidor pode chamar APIs de inferência pagas do TokenLab?">
    Sim. Defina `TOKENLAB_API_KEY` e use `create_chat_completion`, `create_response`, `create_anthropic_message` ou `create_gemini_content`. As ferramentas de catálogo e preços continuam disponíveis sem chave.
  </Accordion>
</AccordionGroup>

## Recursos

<CardGroup cols={2}>
  <Card title="Repositório GitHub" icon="github" href="https://github.com/hedging8563/tokenlab-mcp-server">
    Código-fonte e instruções de configuração local
  </Card>

  <Card title="Skills do TokenLab" icon="sparkles" href="https://github.com/hedging8563/tokenlab-skills">
    Skills de agente mantidas para integrações com o TokenLab
  </Card>

  <Card title="API do Catálogo de Modelos" icon="list" href="https://api.tokenlab.sh/v1/models">
    Endpoint de descoberta de modelos públicos
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    Visão geral da API do TokenLab legível por agentes
  </Card>

  <Card title="Servidor MCP Glama" icon="globe" href="https://glama.ai/mcp/servers/hedging8563/tokenlab-mcp-server">
    Veja a listagem verificada do TokenLab MCP Server
  </Card>

  <Card title="Explorador de Modelos Glama" icon="search" href="https://glama.ai/mcp/servers/hedging8563/tokenlab-openai-apps-model-explorer">
    Explore modelos, preços e exemplos de endpoints nativos
  </Card>

  <Card title="Listagem MCP.so" icon="compass" href="https://mcp.so/servers/tokenlab-mcp-server">
    Descubra o TokenLab no diretório AI & Agents
  </Card>

  <Card title="Explorador de modelos hospedado" icon="rocket" href="https://tokenlab-model-explorer.vercel.app">
    Abra o explorador público e o endpoint MCP remoto
  </Card>
</CardGroup>