> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kviria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect and pay

> Connect an MCP client in one click, or send a Kviria key, and top up the account's balance with x402 when the free turns run out.

Every call to Kviria belongs to a Kviria account. An account has no email
and no password. You get one in one of two ways:

* **Connect an MCP client** such as Claude, ChatGPT, Claude Code, Cursor
  or VS Code. The client signs in with OAuth and opens Kviria's connect
  page, where you allow it.
* **Get a Kviria key** at [api.kviria.com/key](https://api.kviria.com/key),
  for voice platforms, scripts and SDKs that send a fixed header.

A call with neither gets a `401` with `unauthorized`. Its
`WWW-Authenticate` header points MCP clients to Kviria's OAuth metadata,
and its message says where a key comes from.

## Connect an MCP client

Add Kviria as a remote MCP server with this URL:

```text theme={null}
https://api.kviria.com/mcp
```

* **Claude and ChatGPT:** add a custom connector with the URL.

* **Claude Code:** `claude mcp add --transport http kviria https://api.kviria.com/mcp`

* **Cursor** (`~/.cursor/mcp.json`):

  ```json theme={null}
  { "mcpServers": { "kviria": { "url": "https://api.kviria.com/mcp" } } }
  ```

* **VS Code** (`.vscode/mcp.json`):

  ```json theme={null}
  { "servers": { "kviria": { "type": "http", "url": "https://api.kviria.com/mcp" } } }
  ```

The client opens Kviria's connect page in your browser. It shows the app,
who publishes it, and where its access goes. When the access goes to an
app on your computer, such as Claude Code, the page says so. Choose
**Allow**. The client keeps its access fresh on its own. Access an app has
not renewed for 90 days ends, and the app asks you again.

## Get a Kviria key

1. Open [api.kviria.com/key](https://api.kviria.com/key) and choose
   **Create a key**. A quick automatic check runs first.
2. Copy the key. It starts with `kvr_` and is shown only once. Kviria
   keeps only a fingerprint of it, so it can't show or send it again.
3. Send it on every call:

```bash theme={null}
curl -X POST "https://api.kviria.com/v1/agent?agent=my-agent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KVIRIA_KEY" \
  -d '{ "request": "search", "kind": "cafe", "state": "", "anchor": { "lat": 37.76326, "lng": -122.4152 } }'
```

The same key works on the [MCP server](https://docs.kviria.com/api/mcp.md), for clients that send a
fixed header.

* **Keep it secret.** Anyone with the key uses your account and its
  balance.
* **Replace it** on the key page with **Replace a key you have**. The new
  key belongs to the same account, and the old one stops working.
* **Lost it?** Open the key page in the browser you made it in: it knows
  your account and gives you a new key for it. Otherwise write to
  [hello@kviria.com](mailto:hello@kviria.com).

The browser you use on the connect or key page remembers your account for
400 days, so a key you make there and an app you allow there share one
account and one balance.

## Pay

1. **The wall.** When an account's free turns for the day are used up, a
   call gets a `402` with `free_daily_limit_exhausted`. The payment
   requirements are in the `PAYMENT-REQUIRED` header, as base64 JSON.
2. **Top up.** Send any turn with your key or token and a
   `PAYMENT-SIGNATURE` header: an x402 payment in USDC on Base, for any
   amount from one turn's price up. Kviria verifies and settles it
   onchain, adds it to your account's balance, and then runs the turn.
3. **Keep going.** While the account has a balance, each turn is paid
   from it, with a higher minute limit.

The wallet only pays. The balance belongs to the account, so any wallet
can top it up, and every turn the account makes can spend it. A payment
needs an account: a call with a payment and no key or token gets the
`401`.

To read the price and the payment requirements before any call:

```bash theme={null}
curl https://api.kviria.com/v1/x402
```

The prices and the limits are in [Payments](https://docs.kviria.com/api/payments.md) and
[Rate limits](https://docs.kviria.com/api/rate-limits.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.