@visa/cli

AI-powered payments over MCP. Exposes Visa-funded paid tools as MCP (Model Context Protocol) tools so your AI assistant can pay for image generation, video, music, onchain data queries, and more. Ordinary paid calls debit prepaid credits through an approved session; card use is reserved for enrollment, top-ups, and explicitly documented direct-card exceptions.

Platform support

| Platform | Credential Storage | Payment Auth | Install | |----------|-------------------|--------------|---------| | macOS | Keychain | Touch ID / Secure Enclave | bash <(curl -fsSL https://visacli.sh/install.sh) or npm i -g @visa/cli | | Windows | ACL-restricted file | Server-verified (restricted limits) | npm i -g @visa/cli or iwr -useb https://visacli.sh/install.ps1 \| iex | | Linux | libsecret (GNOME Keyring / KDE Wallet) | Server-verified (restricted limits) | bash <(curl -fsSL https://visacli.sh/install.sh) or npm i -g @visa/cli |

Install

# one-liner (installs Node.js check + npm install + verification)
bash <(curl -fsSL https://visacli.sh/install.sh)

# or directly via npm
npm install -g @visa/cli

MCP setup

Add to your MCP client config:

{
  "mcpServers": {
    "visa": {
      "command": "visa-cli",
      "args": ["mcp"]
    }
  }
}

Once connected, your assistant will have access to all payment tools. The first time you use a paid tool, you'll be prompted to log in and enroll a card — you'll get $1 in free credits to start.

Enable the spend HUD (recommended)

Keep an eye on what your agents are spending. The HUD shows your balance, active card, and recent tool usage on every prompt.

visa-cli config hud enable

CLI commands

visa-cli login        # GitHub OAuth — opens browser, stores session token
visa-cli add-card     # Enroll a Visa card via VGS secure form
visa-cli status       # Show auth state, enrolled cards, daily spend remaining
visa-cli tokens create my-demo-app
                      # Create an API token for an app or agent
visa-cli history      # Recent transactions with amounts and status
visa-cli config hud enable
                      # Enable the Claude Code statusLine HUD
visa-cli config hud doctor
                      # Diagnose HUD setup
visa-cli config hud disable
                      # Remove the Claude Code statusLine HUD
visa-cli config hud enable claude
                      # Explicitly register the Claude Code statusLine renderer
visa-cli config hud enable shell
                      # Opt-in shell prompt HUD for zsh/bash
visa-cli config statusline
                      # Renderer for statusLine integrations
# MCP (stdio): run the bundled entrypoint (IDE configs use the same path — see getServerEntry in src/clients.ts)
#   node "$(npm root -g)/@visa/cli/dist/mcp-server/index.js"

Authentication

Login is GitHub OAuth. Your session token is stored at ~/.visa-mcp/session-token.

visa-cli login    # opens github.com/login/oauth/authorize in your browser
visa-cli status   # verify you're logged in

Card enrollment

Cards are tokenized via VGS — your raw card number never touches Visa servers. add_card opens a hosted VGS Collect form in your browser. You receive $1 in free credits on your first card enrollment.

visa-cli add-card

Multiple cards can be enrolled. The first becomes the default; you can switch defaults with set_default_card from within your assistant. To remove a card: remove_card (requires authentication).

Credits & referrals

You receive $1 in free credits when you enroll your first card — enough for about 16 AI images. Credits are used automatically before your card is charged.

To add more credits from the CLI, run visa-cli balance topup --amount 5. In MCP clients, the equivalent tool is buy_credits. Both names refer to the same card-funded wallet top-up path and are subject to the same spending controls.

Share your referral link (visible in get_status) and you both get $2 in free credits when your referral enrolls a card.

Payments & Authentication

Every paid tool call requires authentication. On macOS, this is Touch ID (or device password); on Windows and Linux, payments are server-verified with restricted spending limits. Your assistant will show you the amount and merchant before prompting. If you cancel, the payment is aborted — nothing is charged.

Remote CLI/MCP servers can run ordinary paid tools under those server-enforced limits, but card-funded credit top-ups require local biometric attestation. Credits and the biometric preference are account-level: top up from any interactive Touch ID-capable CLI signed into the same account, optionally run visa-cli biometric off there for remote ordinary payments, then use that balance from the remote server. Credit top-ups still require local attestation even when biometric is off. For unattended server workloads, scoped API keys with daily caps are also supported.

You can set hard limits via the update_spending_controls tool, or check your current limits any time:

visa-cli status

API tokens for apps and agents

Approved users can create API tokens from the CLI with their existing login:

visa-cli tokens create my-demo-app --tools fal-flux-pro,or-gpt-4o-mini --daily-cap 5
visa-cli tokens list
visa-cli tokens revoke 1

The create command prints the raw vk_... key once. Store it in your app or agent secret store and send it as X-Api-Key. Paid API-token calls use /v1/api/session-budget/create followed by /v1/api/session-budget/stream/:tool; direct /v1/api/shortcuts/:tool card charges are retired.

MCP tools

Account

| Tool | Description | |------|-------------| | login | GitHub OAuth login — opens browser | | add_card | Enroll a card via VGS tokenization | | get_cards | List enrolled cards (masked) | | remove_card | Remove an enrolled card (authentication required) | | set_default_card | Change the default card (authentication required) | | get_status | Auth, card, spend limits, and budget summary | | start_session | Start a capped approval window for paid tools in this MCP process | | get_session_status | Show the active session cap, estimated spend, and remaining amount | | close_session | Close the active session and return to pay-as-you-go approvals | | update_spending_controls | Set daily and per-transaction limits (authentication required) | | transaction_history | Recent transactions with amounts, merchants, status, and support IDs | | feedback | Submit feedback on a tool result | | reset | Clear auth state and credentials |

Generation

| Tool | Price | Description | |------|-------|-------------| | generate_image | $0.01–$0.08 | Curated image generation tiers | | generate_video | $0.10–$0.20 | Text-to-video (Wan / MiniMax / Kling) | | generate_music | ~$0.02 | Prompt-to-music tracks (ACE-Step) | | generate_audio | ~$0.03–$0.04 | TTS (MetaVoice) or SFX (Stable Audio) | | generate_3d | ~$0.08 | Text-to-3D mesh (Trellis), returns GLB URL | | upscale_image | ~$0.03 | Image upscaling (Aura SR) | | transcribe_audio | ~$0.02 | Speech-to-text (Whisper) |

Data

| Tool | Price | Description | |------|-------|-------------| | run_llm | $0.01–$0.09 | Run a prompt through GPT-4o Mini, Claude, DeepSeek, Perplexity, or Llama | | get_visa_smi | $0.10 | Visa Spending Momentum Index by US state + county (early access — request access) |

Utility

| Tool | Description | |------|-------------| | batch | Execute multiple paid tools in one authentication approval | | discover_tools | Search the dynamic tool catalog | | execute_tool | Run a tool from the dynamic catalog by ID |

Dynamic catalog

The tool catalog is fetched live from the auth server at startup (5-minute TTL). If the server is unreachable, it falls back to the compiled-in baseline from @visa/tools.

To see all available tools with current pricing, ask your assistant:

"What tools do you have available?"

Spending controls

Daily limit         — hard cap on total spend per day
Max per-transaction — hard cap per single tool call

Both limits are enforced server-side. Authentication is always required per payment regardless of limits — this cannot be disabled. On macOS this means Touch ID; on other platforms, server-side verification with restricted spending limits applies.

Sessions

Paid tools are pay-as-you-go by default: each paid call opens a one-shot session, requests payment approval, runs the call, and closes that one-shot session. Receipts still include a session id in pay-as-you-go mode.

To approve a reusable capped window for the current MCP process, use start_session:

start_session capUsd=5

Paid calls then spend from that explicit approval window until the cap is used, close_session is called, the window expires, or the MCP process restarts. After close_session, paid calls return to pay-as-you-go one-shot sessions. Explicit approval windows are not reused across Claude/MCP restarts.

Config & data locations

| Path | Contents | |------|----------| | ~/.visa-mcp/session-token | Session token | | ~/.visa-mcp/catalog-cache.json | Cached tool catalog (24h TTL) | | ~/.visa-mcp/allium-results/ | Large query result CSVs |

Troubleshooting

Touch ID prompt doesn't appear (macOS) Make sure the MCP process (node …/dist/mcp-server/index.js) runs in a foreground TTY with access to the macOS security framework. Running inside some sandboxed environments may prevent Touch ID. On Windows and Linux, biometric prompts are not used for ordinary payments. Buying credits with an enrolled card currently requires local biometric attestation from the CLI; remote servers can spend account balance topped up from any interactive Touch ID-capable CLI signed into the same account.

"Not logged in" after visa-cli login Restart the MCP server after logging in — your MCP client needs to reconnect to pick up the new session.

Card not showing in get_cards Enrollment is only confirmed after you complete the VGS form in the browser. Call get_cards after finishing the form to verify.

Tool returns an error about daily limit Check your remaining budget with visa-cli status or ask your assistant: "What's my remaining budget today?"

Catalog shows stale tools Delete ~/.visa-mcp/catalog-cache.json and restart the MCP server to force a fresh fetch.

Monorepo context

Request routing (MCP vs MPP vs web): docs/agents/ARCHITECTURE.md. Branches and deploy: docs/agents/PIPELINE.md. Contributor workflow: AGENTS.md, doc index: docs/agents/README.md.