@visa/cli

AI-powered payments over MCP. Exposes Visa card payment tools as MCP (Model Context Protocol) tools so your AI assistant can pay for image generation, video, music, onchain data queries, and more — charged to a Visa card with authentication confirmation at the point of invocation.

Platform support

Install

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 any generated media URLs
visa-cli config hud enable
                      # Enable the terminal HUD for Codex and regular shells
visa-cli config hud doctor
                      # Diagnose terminal HUD setup
visa-cli config hud disable
                      # Remove the terminal HUD from your shell
visa-cli config hud enable claude
                      # Legacy: register the Claude Code statusLine renderer
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.

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 generate_image_card,run_llm --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 to /v1/api/shortcuts/:tool.

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 requests payment approval. To approve a capped window for the current MCP process, use start_session:

start_session capUsd=5

Paid calls then spend from that approval window until the cap is used, close_session is called, the session expires, or the MCP process restarts. Sessions 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 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.