# MCP with a key — purchases by an AI agent

> How to connect the ZRAZU MCP server with an API key: the agent registers and renews domains, orders SSL from the balance and hands a top-up link.

URL: https://zrazu.com/en/docs/api-mcp-account/

This MCP server works on behalf of your organization with an [API key](https://zrazu.com/en/docs/api-keys.md). The agent sees only the tools the key has rights for and pays only from the balance. The rules are the same as in [purchases via the API](https://zrazu.com/en/docs/api-orders.md): IP list, limits, the key's daily limit and the action log.

The open domain passport server without a key is described in [MCP for AI agents](https://zrazu.com/en/docs/api-mcp.md).

## Connect

Server address: `https://api.zrazu.com/v1/mcp`. The key goes in the `Authorization: Bearer` header.

**Claude Code:**

```sh
claude mcp add --transport http zrazu-account https://api.zrazu.com/v1/mcp --header "Authorization: Bearer zr_live_..."
```

**Cursor, VS Code and other clients with JSON configuration:**

```json
{ "mcpServers": { "zrazu-account": { "type": "http", "url": "https://api.zrazu.com/v1/mcp", "headers": { "Authorization": "Bearer zr_live_..." } } } }
```

A key that spends money works only from addresses on its list. So connect the server in an agent that runs on your computer or server. Cloud assistants call from their provider's addresses, and such a key refuses them.

## Tools

| Tool | What it does | Right |
|---|---|---|
| `whoami` | the key's rights, domains, addresses and term | any |
| `balance_get` | organization balance | `billing.read` |
| `domains_list` | organization domains | `domain.read` |
| `owners_list` | who can be the owner of a new domain | `domain.register` |
| `domain_register` | register a domain | `domain.register` |
| `domain_renew` | renew a domain; `expires_at` from `domains_list` is required — no second renewal | `domain.renew` |
| `ssl_catalog` | certificates and prices | `ssl.read` |
| `ssl_order` | order a certificate | `ssl.order` |
| `order_get` | order state, with `wait` up to 60 s | any order right |
| `order_payment_link` | a new top-up link | a purchase right |
| `order_pay` | pay the order from the balance | a purchase right |

A tool answer is the same as in the API: status and body. Errors have the same codes, see [purchases via the API](https://zrazu.com/en/docs/api-orders.md).

## How the agent buys

1. Every purchase has an `idempotency_key` — any unique string. When retrying the same purchase after a dropped connection, the agent passes the same string, and nothing is charged twice.
2. If money is short, the answer has `payment_url`. This is not an error: the agent gives the link to a person and then waits with `order_get` and `wait` until the order is `paid` and `fulfilled`.
3. For registration the agent takes the owner from `owners_list`. The first call returns `documents_required` with the registry documents and `documents_hash`. The agent shows the documents to a person. If your organization lets the agent agree without a person, the repeat call with that hash is the organization's own consent, like the checkbox in the account.

## If it did not work

- **Almost no tools.** The agent sees only what the key has rights for. Check the rights with `whoami`.
- **`403 ip_not_allowed`.** The agent does not call from an address on the key's list. Check where it runs.
- **`400` or `413`.** The request has more than 10 JSON-RPC messages or a body over 256 KB. Send less.
- **`401`.** The key was not passed, or it is revoked or expired.
- **A `403` answer without JSON-RPC.** The request came from a browser page. The key works only from programs.