MCP server Tokia: use Claude Desktop, Cursor, Cline com saldo BRL

Model Context Protocol (MCP) é o padrão aberto que Anthropic lançou em 2024 pra ferramentas de IA chamarem APIs externas como tools estruturados. Em 2025 Cursor, Cline e Continue.dev adotaram. Agora Tokia é MCP server — você adiciona uma vez e qualquer cliente MCP ganha acesso aos modelos Tokia cobrando do seu saldo BRL.

O que é MCP, em 1 parágrafo

JSON-RPC 2.0 padronizado. Cliente MCP (Claude Desktop, Cursor, etc) faz tools/list pra descobrir o que o server expõe, depois tools/call pra executar. Sem SDK proprietário, sem REST custom — qualquer cliente fala com qualquer server. Spec completo →

Tools que Tokia expõe

1. tokia_chat_completion — chama qualquer modelo do catálogo curado Tokia (gpt-4o-mini, claude-sonnet-46, deepseek-v3, gemini-flash, llama-3-3-70b, test-free). Cobra do saldo BRL com markup decrescente.
2. tokia_list_models — lista 9 modelos com markup + categoria + descrição. Gratuito (metadata read-only).
3. tokia_get_balance — retorna saldo BRL + total recargas + total gasto. Gratuito.

E 2 resources: tokia://docs/chat + tokia://docs/api/reference.

Setup Claude Desktop (2 minutos)

Edita o config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop. Aparece "Tokia" no menu de tools. Peça algo 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.dev

Cada um tem painel MCP Servers em settings:

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

Por que isso importa

• Sem lock-in: seu cliente MCP funciona com qualquer server que fale o protocolo. Tokia é mais um. Trocou de cliente? Setup vai junto.
• Cobrança em BRL: chamadas MCP cobram do mesmo saldo Tokia. Sem cartão internacional, sem IOF.
• Catálogo curado: os mesmos 9 modelos que você usa via API normal. Inclui test-free (gpt-oss-120b) pra desenvolvimento custo R$ 0,00.
• Observability nativa: toda chamada MCP é taggeada x-tokia-client: mcp no gateway. Aparece em /dashboard/usage agregada e (admin) /dashboard/admin/chat. Tracking sem código extra.
• Auth simples: mesma sk-... que você usa em integrações OpenAI- compat. Sem OAuth dance, sem refresh tokens.

Tracking

Toda chamada MCP é identificada por header x-tokia-client: mcp no gateway. Aparece separada em /dashboard/usage. Se você é admin, /dashboard/admin/chat mostra breakdown por origem (web, mcp, sdk, terminal).

Limites

• 120 req/min por API key (rate limit padrão Tokia)
• Hard cap saldo: sem BRL = sem chamada
• Modelos disponíveis: 9 do catálogo + test-free

Troubleshooting

• 401 invalid_authorization: key Tokia inválida ou revogada → cria nova em /dashboard/keys.
• 402 exhausted_balance: saldo zerou → recarrega PIX em /dashboard/billing.
• 404 method: cliente MCP desatualizado → use versão recente (Claude Desktop 0.7+, Cursor 0.42+, Cline atual).
• 500 internal: abra ticket em contato@usetokia.com com tool name + payload.

Docs completos: /docs/mcp. Implementação: apps/api/src/routes/mcp.ts no monorepo.