Saltar para o conteúdo
vokse.
Explorar a referência
Voltar à referência da API
GUIA

MCP

O vokse tem um servidor MCP remoto: o mesmo conjunto de ferramentas auditadas que o assistente e a aplicação chamam, agora em Model Context Protocol. Um URL, OAuth padrão, sem binários e sem chaves de API.

O endpoint

Passa-se tudo num único endpoint Streamable HTTP. Não há nada para descarregar nem nada para configurar além do URL:

http
https://api.vokse.ai/mcp

O Claude (na web e no computador) e o ChatGPT aceitam o URL como conector personalizado nas definições. Os clientes de linha de comandos e de editor registam-no uma vez:

Claude Code
bash
claude mcp add --transport http vokse https://api.vokse.ai/mcp

Autorização

O servidor é um recurso protegido por OAuth 2.1. Os clientes descobrem tudo a partir dos metadados padrão, sem configuração específica do vokse:

  1. O cliente obtém os metadados do recurso protegido e encontra o servidor de autorização.
  2. Identifica-se com um Client ID Metadata Document (o perfil MCP 2026-07-28); o registo dinâmico de clientes continua disponível como alternativa.
  3. O seu navegador abre o ecrã de consentimento do vokse: escolhe sobre que agregados o cliente pode agir e se fica só de leitura ou também pode escrever.
  4. O cliente recebe tokens de acesso de curta duração, associados ao endpoint MCP. Nenhum segredo de longa duração sai alguma vez do vokse.
Descoberta
bash
curl https://api.vokse.ai/.well-known/oauth-protected-resource/mcp

Agregados

As ferramentas atuam sobre um agregado de cada vez: passe o respetivo ULID em householdId, ou omita-o quando a ligação abranger apenas um. Chame primeiro list_households para ver o que foi autorizado; o conjunto é validado no servidor em cada chamada, cruzado com a lista de membros em vigor.

As ferramentas destrutivas pedem confirmação

Eliminar um movimento, repor um mês, mover dinheiro entre categorias: em vez de executar, a ferramenta devolve uma ação em espera, para a pessoa aprovar.

json
{  "status": "confirmation_required",  "tool": "soft_delete_transaction",  "pendingActionId": "01JC…",  "prompt": "Delete the €42.50 transaction at Migros on 2026-08-12?",  "expiresAt": "2026-08-18T18:00:00.000Z",  "hint": "Show the prompt to the user. If they approve, call confirm_action           with { pendingActionId }; if they decline, call cancel_action."}

Mostre o pedido ao utilizador. Se aprovar, chame confirm_action com o pendingActionId (é idempotente: uma confirmação repetida devolve o resultado guardado); se recusar, chame cancel_action. As ações em espera expiram sozinhas.

Revogar o acesso

Todas as ligações estão listadas em Definições → MCP, com o nível de acesso e os agregados respetivos. Desligar elimina a autorização e os seus tokens; a chamada seguinte desse cliente é recusada.