@vaaya/mcp

Stdio MCP server for Vaaya, the agent payment system. Lets an MCP client (Codex CLI, opencode, or any other stdio MCP host) call paid APIs through Vaaya's proxy endpoints on the user's behalf — the agent never sees upstream URLs or API keys.

Agent-readable docs: vaaya.ai/llms.txt (index, including agent self-serve signup) · vaaya.ai/llms-full.txt (full 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 logout       # forget local credentials
vaaya-mcp reauthorize  # re-run the OAuth flow (e.g. to add scopes)

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-apps on Vaaya, find the connection, and click Disconnect. The next time the agent makes a request, the shim re-enters the OAuth flow.