MCP server

Plug VelarumPay into an AI agent

The @velarumpay/mcp-server is a local MCP stdio server. It exposes VelarumPay as a small set of tools any MCP-capable agent (Claude and others) can call. It never holds private keys, signs, or approves payments.

Tools

Tool	What it does
`create_pairing_session`	Start pairing so the user can approve in their wallet.
`create_transaction_context`	Create the human-readable review context.
`create_payment_request`	Propose a payment for the user to sign.
`get_payment_status`	Read the current status of a request.

Only these v0.1 scopes are available: payment.requests.create, payment.requests.read, transaction_contexts.create, transaction_contexts.read. No signing, key, seed, or auto-approval scope is ever exposed.

Run it

export VELARUMPAY_API_BASE_URL=http://127.0.0.1:8787
export VELARUMPAY_CONNECTION_TOKEN=conn_tok_...
npx velarumpay-mcp-server

Tool inputs may also pass base_url and connection_token per call. If a payload includes connection_id, it must match the connection the token belongs to. For local agents, omit connection_id and the Platform API derives it from the token.

Example tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_pairing_session",
    "arguments": {
      "agent": {
        "agent_id": "agt_mcp_local",
        "agent_name": "VelarumPay MCP Local Agent",
        "runtime": "mcp",
        "device_label": "local developer machine"
      }
    }
  }
}

Safety model

The MCP server is a thin client. The Platform API still enforces connection-token checks, scope checks, and risk policy (allowlists, daily limits, idempotency) on every call. The user's wallet is always the place where real payments get approved and signed.