<p><img src="https://vaaya.ai/icon.png" width="64" height="64" alt="Vaaya" /></p>

# @vaaya/mcp

Research, create and shop with Vaaya from Cursor, Claude Code, Claude Desktop,
or Codex. Find products with OneSearch and buy from supported stores with your
approval. Your agent can also 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.

```bash
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](https://vaaya.ai/blog/give-an-ai-agent-a-budget),
[Cursor setup](https://vaaya.ai/blog/cursor-agent-mcp-payments),
[Claude setup](https://vaaya.ai/blog/claude-mcp-payments).

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

## Find it and buy it with Vaaya

Tell your agent what you need, or share a product link. Vaaya can find matching
items with **OneSearch**, check the details, and handle checkout at supported
stores with your approval. For example: “Find standard AeroPress paper filters,
350 count, for under $15.”

The MCP `buy` tool covers the whole flow: `search` finds products (5¢ per search),
`purchase` starts an authorized purchase, and `status` tracks the same order.
If approval is still needed, `propose` returns a review link. Vaaya asks for
sign-in or payment steps through secure checkout links when needed.
These are MCP commands available to your agent, not CLI subcommands.

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

```json
{ "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 $14, $40,
or $60 pack, POST `https://vaaya.ai/api/v1/topup` with JSON
`{ "pack_cents": 1400 }` (or 4000 / 6000) 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](https://vaaya.ai/llms.txt) ·
[Complete tool reference](https://vaaya.ai/llms-full.txt)


## Install

```jsonc
// 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`](https://vaaya.ai/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.