MCP server · spec 2025-11-25

Give your assistant a wallet it cannot empty.

The MCP server exposes the wallet as tools over Streamable HTTP. It is an OAuth-protected resource: every call carries a user-consented token, is checked for audience and scope, and is audited. Reading is instant. Moving money produces an approval link, and the owner approves it in the wallet.

Endpoint and transport

URL: http://localhost:8081/mcp, Streamable HTTP in stateless mode. Any replica answers any request; no session pinning.
Spec: pinned to MCP 2025-11-25, built with the official MCP Go SDK.
Discovery: /.well-known/oauth-protected-resource publishes the authorization server, so compliant clients start the OAuth flow by themselves.
Tokens: OAuth 2.1 authorization code with PKCE. Access tokens live 15 minutes; refresh tokens rotate and last 30 days. User tokens are never forwarded to the payment provider or anyone else.

Connect a client

Any MCP client that supports Streamable HTTP and OAuth works. For a desktop assistant, add the server and complete the consent screen in your browser when prompted.

Client configuration (example)

{
  "mcpServers": {
    "ravelo": {
      "type": "streamable-http",
      "url": "http://localhost:8081/mcp"
    }
  }
}

The consent screen lists the requested scopes. Grant the least you need: a reporting assistant needs balances:read and payments:read only.

Scopes

Scope	Grants
balances:read	See balances, fees and statements
payments:read	See payments, refunds and their status
addressbook:read	See saved payout addresses
payments:write	Create payment requests
payouts:prepare	Prepare payouts for a team member to approve
refunds:prepare	Prepare refunds for a team member to approve

Tools

Tools carry read-only or destructive hints, return structured results, and never include unfiltered on-chain memo text, since memos may carry prompt-injection attempts.

Tool	Scope	Effect
list_supported_assets	none	Read-only. Assets and networks the account can take payments in, pay out and refund, with minimums and fees.
get_balances	balances:read	Read-only. Available, pending and held balance per asset, in base units.
quote_fee	balances:read	Read-only. Platform fee and network fee for paying out an amount.
list_payments	payments:read	Read-only. Payment intents, newest first, filtered by status or order reference.
get_payment	payments:read	Read-only. One payment intent with its instructions and matched fundings.
get_operation_status	payments:read	Read-only. Status of a payment, payout or refund by id.
list_address_book	addressbook:read	Read-only. Saved payout addresses; a payout can only go to an active one.
create_payment_intent	payments:write	Creates a payment request and returns the exact address and amount the payer must send. Moves no money.
prepare_payout	payouts:prepare	Reserves the funds for a payout to a saved address and returns an approval link. Nothing is sent until a team member approves.
prepare_refund	refunds:prepare	Prepares a refund of a payment. A team member approves it, then platform operations review it.

What happens when an assistant sends money

The assistant calls prepare_payout with an asset, an amount and a saved address. The server validates limits, balance and cooling-off.
The tool result is { "status": "awaiting_approval", "approval_url": "…" }. Nothing has moved; the assistant cannot change that.
You open the link in the wallet (also listed under Approvals), see who asked, the full address, fees and total, and confirm with a passkey or reject.
The assistant follows up with get_operation_status until it reads completed.

Tool call and result

› prepare_payout({ "address_book_entry_id": "…", "asset_id": "usdt-tron", "amount": "120000000", "request_id": "payout-2026-10-29-a" })

{
  "status": "awaiting_approval",
  "operation_id": "0192f1e0-…",
  "approval_url": "https://app.ravelopay.app/approve/0192f1e0-…",
  "note": "Moves nothing until the owner approves in the wallet."
}

Safety rules

No scope allows approving money out. Approval is a human action in the wallet, with a passkey or authenticator code.
Withdrawals go to saved addresses only. A new address waits 24 hours before it can be used, whoever adds it.
Every tool call is audited with the client, the member who connected it, the tool, what it touched and the outcome. A rate limit applies.
Revoke an app at any time under API & apps; its tokens stop working immediately.