MCP server Tokia

Conecte qualquer ferramenta MCP-compatible (Claude Desktop, Cursor, Cline, Continue.dev) ao Tokia e use nosso catálogo curado de modelos cobrando do seu saldo BRL.

O que é MCP?

Model Context Protocol é um padrão aberto (JSON-RPC 2.0) pra ferramentas de IA chamarem APIs externas como "tools" estruturadas. Anthropic introduziu em 2024, Cursor/Cline/Continue adotaram em 2025. Resultado: você adiciona o Tokia uma vez na config da ferramenta e ela passa a ter acesso aos nossos modelos + saldo + uso.

Tools expostos

• tokia_chat_completion — chama modelo Tokia (catálogo curado). Cobra do saldo BRL.
  Args: model, messages, max_tokens, temperature
• tokia_list_models — lista 9 modelos do catálogo com markup + categoria + descrição
• tokia_get_balance — retorna saldo BRL atual + total recargas + total gasto

Resources expostos

• tokia://docs/chat — guia rápido Tokia Chat
• tokia://docs/api/reference — docs API reference

Setup Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "tokia": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch", "https://api.usetokia.com/mcp/rpc"],
      "env": {
        "TOKIA_API_KEY": "sk-..."
      }
    }
  }
}

Restart Claude Desktop. Vai aparecer no menu de tools "Tokia" disponível no chat. Pede tipo "Use o tokia_chat_completion com modelo gpt-4o-mini pra responder X" — Claude chama o tool e mostra resultado.

Setup Cursor / Cline / Continue

Cada um tem painel próprio "MCP Servers" em settings. Adiciona:

• Name: Tokia
• URL: https://api.usetokia.com/mcp/rpc
• Auth header: Authorization: Bearer sk-... (sua API key Tokia)
• Optional header: x-tokia-client: mcp-cursor (ou similar pra tracking)

Auth

Mesma sk-... key que você usa em integrações OpenAI-compat. Crie em /dashboard/keys. Cada call MCP é autenticada via Authorization Bearer header igual chamada API normal.

Custos

Cada tokia_chat_completion consome saldo BRL no markup decrescente do modelo escolhido (mesma tabela /docs/pricing). Usar test-free (gpt-oss-120b) pra desenvolvimento: custo R$ 0,00.

Tools tokia_list_models e tokia_get_balance são gratuitos (read-only metadata).

Tracking

Toda chamada MCP é identificada por header x-tokia-client: mcp no gateway. Aparece separada em /dashboard/usage e (admin) /dashboard/admin/chat na seção "Por API key (origem)".

Limites

• 120 req/min por API key (rate limit Sprint 325)
• Hard cap saldo: sem saldo BRL = sem chamada
• Modelos disponíveis: 9 do catálogo + free tier

Troubleshooting

• 401 invalid_authorization: key Tokia inválida ou revogada. Crie nova em /dashboard/keys.
• 402 exhausted_balance: saldo BRL zerou — recarregue via PIX em /dashboard/billing.
• 404 method: ferramenta MCP cliente desatualizada — use versão recente (Claude Desktop 0.7+, Cursor 0.42+).
• 500 internal: abre ticket em contato@usetokia.com com tool name + payload.

Implementação: apps/api/src/routes/mcp.ts no monorepo inael/usetokia. Spec MCP completo: modelcontextprotocol.io.