@vaaya/mcp

MCP server for AI agent payments. An agent in Cursor, Claude Code, Claude Desktop, or Codex can call paid APIs (search, scraping, contact data, public records, compute, media, research) from one balance, with a spend ceiling it states on every call, and no vendor keys anywhere in its environment. Billed only on success; a refused or failed call costs nothing.

npx @vaaya/mcp install            # Cursor, Claude Code, Claude Desktop, Codex
claude mcp add --transport http vaaya https://vaaya.ai/mcp

First paid call: consult returns a priced plan; use(service, action, params, max_cost_cents) runs one line of it. If the quoted price is above max_cost_cents, the call is refused before it reaches the provider and the reason is returned. Guides: give an agent a budget, Cursor setup, Claude setup.

Agent-readable docs: vaaya.ai/llms.txt (index, including agent self-serve signup) · vaaya.ai/llms-full.txt (full tool reference).

Buy tokenized shares — including with Instinct

Agents can buy supported tokenized stocks on Base with Vaaya prepaid funds. These are tokenized stocks, not direct brokerage shares. Discover the current supported tickers with stocks({ command: "list" }) (for example Apple AAPLc and NVIDIA NVDAc), then check stocks({ command: "portfolio" }) for buyingPowerCents. Welcome grants and credit lines cannot buy shares.

For a user-authorized $10 Apple purchase:

{ "command": "buy", "symbol": "AAPLc", "amount_cents": 1000, "idempotency_key": "<unique purchase key>" }

Call the dedicated stocks MCP tool with this input; it is separate from consult/use. The amount is the maximum total prepaid spend including fees. Save the returned id, then poll stocks({ command: "order", order_id: "<id>" }). Only confirmed means purchased. Stop on failed or needs_review; reuse the same purchase key on uncertain retries, never place a new order to check status.

Insufficient prepaid balance? With the user's authorization for a $10, $30, or $100 pack, POST https://vaaya.ai/api/v1/topup with JSON { "pack_cents": 1000 } (or 3000 / 10000) using the same account's bearer token. An Instinct agent with access to the user's saved card can pay the returned Stripe Checkout url in its own browser when authorized for that pack amount. For a handoff, provide the URL and authorized amount to the user's Instinct agent; otherwise give the URL to the user. Keep card details and bearer tokens out of the handoff. Vaaya cannot charge a card stored in Instinct directly. A share purchase alone does not authorize an extra card charge.

Poll GET /api/v1/wallet (wallet.prepaid_cents), then recheck stock buying power before resuming the original purchase key. Do not pay again while a payment's outcome is uncertain. Stock availability and account permissions apply.

Full MCP and REST purchase guide · Complete tool reference

Install

// mcp.json
{ "mcpServers": { "vaaya": { "command": "npx", "args": ["-y", "@vaaya/mcp"] } } }

On the first tool call the shim opens a browser tab pointed at Vaaya's OAuth authorize endpoint. After you approve, a refresh token is written to ${env-paths.config}/vaaya/credentials with 0o600 mode and reused across sessions.

Configuration (optional)

| Env var | Default | Purpose | | --- | --- | --- | | VAAYA_BACKEND_URL | https://vaaya.ai | Backend origin (override for self-hosting / preview deploys). | | VAAYA_DEBUG | unset | Set to 1 to print the OAuth authorize URL to stderr. | | VAAYA_NON_INTERACTIVE | unset | Set to 1 to suppress the automatic browser open (you still get the URL on stderr). |

CLI commands

vaaya-mcp install      # wire up every agent on this machine, then print a receipt
vaaya-mcp doctor       # one line per check (agent configs, skill, CLI, credentials,
                       # backend) with the command that fixes it; exit 1 if anything
                       # is broken. --offline skips the backend probe.
vaaya-mcp logout       # forget local credentials
vaaya-mcp reauthorize  # re-run the OAuth flow (e.g. to add scopes)

install ends with a receipt: every file it created or edited, every agent it configured, everything it skipped and why, the same checks doctor prints, and what happens next. --app (macOS) opens the Mac app download after the receipt; --dry-run writes nothing.

Tools exposed to the agent

• consult(intent) — always the first call; describes the goal in plain English and gets back the exact use call(s) to run.
• use(service, action, params, max_cost_cents) — execute a call consult handed you; bills on success. Long jobs return { async: true, job_id }.
• result(job_id) — fetch an async job's status/output (poll instead of re-running use).
• session(session_id, command|code) / close(session_id) — run code in a per-second-billed sandbox; always close when done.
• logout — same as the CLI command.
• reauthorize — same as the CLI command.

The tool list is proxied from the backend, so new server-side tools appear without a shim upgrade.

What you can call (1.8.0 catalog)

Most vendors are pay-per-call on x402 (USDC on Base) or MPP (Stripe SPT or Tempo chain) — the payment IS the auth. fal is on the REST rail (Vaaya holds the key). Either way you supply no per-vendor API keys. Highlights:

• Image & video: fal / generate (REST — Nano Banana Pro 2, GPT Image 2, Seedream v4.5, Kling v3, Seedance 2.0)
• Search: exa / search · contents, parallel / search · extract · task
• Scraping: firecrawl / scrape · crawl · map · search · extract (MPP / Tempo)
• Compute sandboxes: modal / sandbox-{create,status,terminate} (MPP / Tempo)
• Browser automation: browserbase / create_session · …
• Email: agentmail

The shim ships the agent skill alongside the binary — your client will auto-load the single skills/vaaya/SKILL.md, which tells the agent to route every capability gap through consult. There are no per-service files: consult holds the live catalog, so the skill never has to list services, params, or prices.

The installer also wires always-on triggers per client (idempotent, all respect --dry-run):

• Claude Code — a marker-delimited Vaaya section in ~/.claude/CLAUDE.md (<!-- vaaya:begin --> … <!-- vaaya:end --> — content outside the markers is never touched) and a SessionStart hook in ~/.claude/settings.json (matcher startup|clear|compact) that injects a forcing reminder — once per session, re-injected after /clear and compaction — to consult Vaaya on any capability gap instead of refusing or working around it. If the vaaya Claude Code plugin is active, the MCP entry, skill, and hook are skipped — the plugin already provides them.
• Codex — the same forcing reminder as a marker-delimited block in ~/.codex/AGENTS.md (read once per session).
• Cursor — a local plugin at ~/.cursor/plugins/local/vaaya bundling an always-applied rule (rules/vaaya.mdc) with the same reminder, plus the skill.

Revoking a grant

Visit /connected-agents on Vaaya, find the connection, and click Disconnect. The next time the agent makes a request, the shim re-enters the OAuth flow.