GUIDA

MCP

vokse ha un server MCP remoto: gli stessi strumenti verificati usati dall'assistente e dall'app, esposti tramite il Model Context Protocol. Un URL, OAuth standard, nessun binario e nessuna chiave API.

L'endpoint

Succede tutto su un unico endpoint Streamable HTTP. Non c'è niente da scaricare e niente da configurare oltre all'URL:

http

https://api.vokse.ai/mcp

Claude (web e desktop) e ChatGPT accettano l'URL come connettore personalizzato nelle impostazioni. I client da riga di comando e da editor lo registrano una volta sola:

Claude Code

bash

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

Autorizzazione

Il server è una risorsa protetta OAuth 2.1. I client scoprono tutto dai metadati standard, senza configurazioni specifiche di vokse:

Il client scarica i metadati della risorsa protetta e trova l'authorization server.
Si identifica con un Client ID Metadata Document (il profilo MCP 2026-07-28); la registrazione dinamica del client resta disponibile come alternativa.
Nel browser si apre la schermata di consenso di vokse: scegli su quali famiglie può agire il client e se solo in lettura o anche in scrittura.
Il client riceve token di accesso a vita breve, legati all'endpoint MCP. Nessun segreto a lunga durata esce mai da vokse.

Discovery

bash

curl https://api.vokse.ai/.well-known/oauth-protected-resource/mcp

Famiglie

Gli strumenti agiscono su una famiglia per chiamata: passa il suo ULID come householdId, oppure omettilo quando la connessione ne copre una sola. Chiama prima list_households per vedere cosa ha autorizzato l'utente: l'insieme viene applicato lato server a ogni chiamata, incrociato con i membri effettivi.

Gli strumenti distruttivi chiedono conferma

Eliminare un movimento, azzerare un mese, spostare soldi nel budget: invece di eseguire, lo strumento risponde con un'azione in sospeso da far approvare all'utente.

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."}

Mostra la richiesta all'utente. Se approva, chiama confirm_action con il pendingActionId (è idempotente: una conferma ripetuta restituisce il risultato già salvato); se rifiuta, chiama cancel_action. Le azioni in sospeso scadono da sole.

Revocare l'accesso

Ogni connessione è elencata in Impostazioni → MCP, con il suo livello di accesso e le sue famiglie. Disconnettendola cancelli il permesso e i suoi token: la chiamata successiva di quel client viene rifiutata.