@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

Install

curl -fsSL https://app.visacli.sh/cli | bash

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 setup        # First run: register MCP server, GitHub OAuth, enroll a card
visa-cli status       # Show auth state, enrolled cards, wallet balance, daily spend remaining

# Cards
visa-cli cards add            # Enroll a Visa card via the VGS secure form
visa-cli cards list           # List enrolled cards
visa-cli cards default <id>   # Set the default payment card
visa-cli cards remove <id>    # Remove an enrolled card

# Balance & credits
visa-cli balance show               # Prepaid balance + recent ledger entries
visa-cli balance topup --amount 5   # Top up balance from your default card (Touch ID)

# Visa Keys for apps and agents
visa-cli keys create my-demo-app  # Create a Visa Key (prints the VisaKey_... key once)
visa-cli keys list                # List Visa Keys
visa-cli keys revoke <id>         # Revoke a Visa Key

# Run merchant tools
visa-cli tools                              # List all available merchant tools
visa-cli tools --merchant fal               # Scope to a single merchant
visa-cli tools --category image             # Filter by category
visa-cli tools --query "text to image"      # Semantic search
visa-cli describe <tool>                    # Show schema, price, and examples
visa-cli generate image|video|music|speech|3d   # Generate media with merchant tools
visa-cli run-llm                    # Chat-completion via an OpenRouter-backed LLM
visa-cli merchants list             # Discover paid platform merchants
visa-cli merchants fal tools        # List tools for a specific merchant
visa-cli merchants fal describe flux-pro   # Show schema + price for one tool
visa-cli merchants fal run flux-pro        # Run a tool scoped to a merchant

# Spend HUD & config
visa-cli config hud enable          # Enable the Claude Code statusLine HUD (claude is the default surface)
visa-cli config hud enable shell    # Opt-in shell prompt HUD for zsh/bash
visa-cli config hud disable         # Remove the HUD
visa-cli config hud doctor          # Diagnose HUD setup
visa-cli config statusline          # Renderer for statusLine integrations
visa-cli config biometric off       # Toggle Touch ID enforcement for remote payments

# Maintenance
visa-cli update                     # Update Visa CLI to the latest stable version
visa-cli config reset --local-only  # Clear local credentials only, useful when switching GitHub accounts
visa-cli uninstall                  # Remove the MCP server from an AI client
visa-cli feedback                   # Submit feedback about Visa CLI

# 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"

Transaction history with amounts, merchants, and status is available through the transaction_history MCP tool (ask your assistant), or as a recent ledger via visa-cli balance show. There is no standalone history subcommand.

Authentication

Login is GitHub OAuth and runs as part of visa-cli setup. Your session token is stored at ~/.visa-mcp/session-token.

visa-cli setup    # registers the MCP server, then 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. visa-cli cards add (or the add_card MCP tool) opens a hosted VGS Collect form in your browser. You receive $1 in free credits on your first card enrollment.

visa-cli cards add

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 config 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

Visa Keys for apps and agents

Approved users can create Visa Keys from the CLI with their existing login:

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

The create command prints the raw VisaKey_... key once. Store it in your app or agent secret store and send it as X-Api-Key. Paid Visa Key calls use /v1/api/tools/:tool/execute for direct JSON execution. Direct /v1/api/shortcuts/:tool card charges are retired. Use --daily-cap USD and --total-cap USD to keep key spend bounded.

Public docs: apps/web/content/docs/visa-key-api.md. Reviewer handoff: docs/api/visa-key-api-review-handoff.md.

MCP tools

Account

Generation

Data

Utility

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

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 setup 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.