Skip to content
vokse.
Browse the reference
Back to the API reference
GUIDE

MCP

vokse ships a remote MCP server: the same audited tools the assistant and the app call, spoken over the Model Context Protocol. One URL, standard OAuth, no binaries, no API keys.

The endpoint

Everything happens at a single Streamable HTTP endpoint. There is nothing to download and nothing to configure beyond the URL:

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

Claude (web and desktop) and ChatGPT take the URL as a custom connector in their settings. Command-line and editor clients register it once:

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

Authorization

The server is an OAuth 2.1 protected resource. Clients discover everything from standard metadata, no vokse-specific setup:

  1. The client fetches the protected-resource metadata and finds the authorization server.
  2. It identifies itself with a Client ID Metadata Document (the MCP 2026-07-28 profile); dynamic client registration remains available as a fallback.
  3. Your browser opens the vokse consent screen: you pick which households the client may act on, and whether it is read-only or may write.
  4. The client receives short-lived access tokens bound to the MCP endpoint. No long-lived secrets ever leave vokse.
Discovery
bash
curl https://api.vokse.ai/.well-known/oauth-protected-resource/mcp

Households

Tools act on one household per call: pass its ULID as householdId, or omit it when the connection covers exactly one. Call list_households first to see what the user granted, the set is enforced server-side on every call, intersected with live membership.

Destructive tools confirm

Deleting a transaction, resetting a month, moving budget money: instead of executing, the tool answers with a parked action for the user to approve.

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

Show the prompt to the user. On approval call confirm_action with the pendingActionId (idempotent, a repeated confirm returns the stored result); on rejection call cancel_action. Parked actions expire on their own.

Revoking access

Every connection is listed under Settings → MCP, with its access level and households. Disconnecting deletes the grant and its tokens; the next call from that client is refused.