# MCP server (/en/docs/pix-processamento/mcp)
## What it is [#what-it-is]
`payzu-mcp-pix` is a local MCP server. It runs on your machine via `npx` and talks to the AI assistant over stdio. There is also a [hosted version](#hosted-server-no-install) with nothing to install. Either way, the assistant decides which tool to call and the server performs the HTTP call to the Pix Processamento API using your token.
[MCP](https://modelcontextprotocol.io) is the open protocol that lets AI assistants call external tools via JSON-RPC. Use MCP when you want the assistant to run real actions on your account during development or interactive use. If your goal is your production app talking to PayZu, use the [SDK](/docs/pix-processamento/sdks) (`payzu-pix`).
Requires `payzu-mcp-pix` 0.3.0 or higher and Node 20 or higher.
## Before you start [#before-you-start]
Get your API token at [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br):
1. Sign in to your account.
2. Open the credentials area (the API token section).
3. Copy the token. That value goes into `PAYZU_TOKEN`.
The token gives real access to your account: create charges, pay Pix and check balance. Treat it like a password. We recommend approving each agent action before it runs, instead of letting it run unattended.
## Hosted server (no install) [#hosted-server-no-install]
Don't want to install anything? Point any compatible MCP client at the hosted server:
```
https://mcp.payzu.com.br/mcp
```
* **claude.ai and Claude Desktop**: Settings → Connectors → *Add custom connector* → paste the URL. A PayZu page opens asking for your token once (OAuth); the assistant never sees or stores it.
* **Cursor / VS Code**: one-click install:
[](https://cursor.com/en/install-mcp?name=payzu-pix\&config=eyJ1cmwiOiJodHRwczovL21jcC5wYXl6dS5jb20uYnIvbWNwIn0%3D)
[](https://insiders.vscode.dev/redirect/mcp/install?name=payzu-pix\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.payzu.com.br%2Fmcp%22%7D)
* **Claude Code**: `claude mcp add --transport http payzu-pix https://mcp.payzu.com.br/mcp` (the authorization flow opens on first use). No-OAuth alternative: send the `Authorization` header with your API Bearer token: `--header "Authorization: Bearer "`.
* **Claude Desktop (local installer)**: download [payzu-mcp-pix.mcpb](https://github.com/PayZuAI/payzu-mcp/releases/latest) and open the file; Claude only asks for the token.
The hosted server is stateless: it stores no tokens and no account data. Every request is forwarded to the Pix Processamento API with your credential, exactly like a direct call.
**Withdrawals and transfers do not work on the hosted server.** These depend on your account's IP allowlist, and the hosted server is shared (one IP for everyone). To withdraw via AI, use the **local app** (`npx payzu-mcp-pix` or the `.mcpb` installer), which runs from your own IP; or withdraw straight from the dashboard. Queries, balance and charge creation work normally on the hosted server.
## Google Antigravity [#google-antigravity]
In the Antigravity interface:
1. In the agent panel (Agent Manager), click the `...` menu at the top.
2. Choose `MCP Servers`, then `Manage MCP Servers`.
3. Click `View raw config`.
4. Paste the config below, replacing it with your token:
```json
{
"mcpServers": {
"payzu-pix": {
"command": "npx",
"args": ["-y", "payzu-mcp-pix"],
"env": { "PAYZU_TOKEN": "your-token-here" }
}
}
}
```
Paste the literal token inside `env`. Variable expansion `${VAR}` fails in some versions.
The config file lives at:
* `~/.gemini/config/mcp_config.json` on newer versions (Antigravity 2.0).
* `~/.gemini/antigravity/mcp_config.json` on earlier builds.
Save and click `Refresh` on the `Manage MCP Servers` screen.
Antigravity needs `payzu-mcp-pix` 0.3.0 or higher. The dotted tool names from older versions were rejected by the models (Gemini, Claude, GPT) that Antigravity uses.
## Claude Code [#claude-code]
```bash
claude mcp add payzu-pix --env PAYZU_TOKEN=your-token -- npx -y payzu-mcp-pix
```
Use `--scope user` for the server to apply across all projects:
```bash
claude mcp add payzu-pix --scope user --env PAYZU_TOKEN=your-token -- npx -y payzu-mcp-pix
```
## Claude Desktop [#claude-desktop]
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"payzu-pix": {
"command": "npx",
"args": ["-y", "payzu-mcp-pix"],
"env": { "PAYZU_TOKEN": "your-token-here" }
}
}
}
```
Restart Claude Desktop after saving.
## Cursor [#cursor]
Edit `.cursor/mcp.json` in the project or `~/.cursor/mcp.json` to apply everywhere:
```json
{
"mcpServers": {
"payzu-pix": {
"command": "npx",
"args": ["-y", "payzu-mcp-pix"],
"env": { "PAYZU_TOKEN": "your-token-here" }
}
}
}
```
## VS Code (GitHub Copilot) [#vs-code-github-copilot]
Edit `.vscode/mcp.json`. Here the key is `servers` (not `mcpServers`), with `type` set to `stdio`. Use `inputs` with `promptString` and `password` so the token is not committed:
```json
{
"servers": {
"payzu-pix": {
"type": "stdio",
"command": "npx",
"args": ["-y", "payzu-mcp-pix"],
"env": { "PAYZU_TOKEN": "${input:payzu-token}" }
}
},
"inputs": [
{
"id": "payzu-token",
"type": "promptString",
"description": "PayZu API token",
"password": true
}
]
}
```
## Windsurf [#windsurf]
Edit `~/.codeium/windsurf/mcp_config.json`, same `mcpServers` shape:
```json
{
"mcpServers": {
"payzu-pix": {
"command": "npx",
"args": ["-y", "payzu-mcp-pix"],
"env": { "PAYZU_TOKEN": "your-token-here" }
}
}
}
```
## Step by step [#step-by-step]
1. Get your token at [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br).
2. Configure your client (Antigravity, Claude Code, Claude Desktop, Cursor, VS Code or Windsurf) with one of the blocks above.
3. Ask for a charge in plain language, for example:
> "Create a R$ 50.00 Pix charge with reference pedido-001 and callback [https://meusite.com.br/webhook](https://meusite.com.br/webhook)"
4. The agent calls `pix_create` and returns the charge `id` and `qrCodeText`.
5. Ask "what's my balance?" and the agent calls `account_balance` and answers with the number.
### Not working? [#not-working]
* Error `[401]`: invalid or expired token. Generate a new one at [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br).
* Server missing from the tool list: reload or restart the client (in Antigravity, use `Refresh`).
## Tool list (29) [#tool-list-29]
All names in snake\_case. Each tool has a `description` with a direct link to the endpoint page in the docs.
### Pix charges (4) [#pix-charges-4]
| Tool | HTTP |
| ------------- | ---------------------------------- |
| `pix_create` | `POST /pix` |
| `pix_get` | `GET /pix` |
| `pix_qr_code` | `GET /pix/qr-code/{transactionId}` |
| `pix_proof` | `GET /proof/{id}` |
### Pix Payments (6) [#pix-payments-6]
| Tool | HTTP |
| ------------------ | --------------------------- |
| `withdraw_create` | `POST /withdraw` |
| `withdraw_get` | `GET /withdraw` |
| `withdraw_by_qr` | `POST /withdraw/qrcode` |
| `withdraw_read_qr` | `POST /pix/qrcode/read` |
| `withdraw_dict` | `GET /pix/key?pixKey={key}` |
| `withdraw_proof` | `GET /withdraw/proof/{id}` |
### Internal transfer (2) [#internal-transfer-2]
| Tool | HTTP |
| -------------------------- | ------------------------- |
| `internal_transfer_create` | `POST /internal-transfer` |
| `internal_transfer_get` | `GET /internal-transfer` |
### Account (2) [#account-2]
| Tool | HTTP |
| ----------------- | ------------------- |
| `account_profile` | `GET /user` |
| `account_balance` | `GET /user/balance` |
### Reports (6) [#reports-6]
| Tool | HTTP |
| --------------------------- | --------------------------------- |
| `reports_list_transactions` | `GET /user/transactions` |
| `reports_get_transaction` | `GET /user/transactions/{id}` |
| `reports_create_csv` | `POST /user/report` |
| `reports_list_jobs` | `GET /user/report` |
| `reports_get_job` | `GET /user/report/{id}` |
| `reports_download` | `POST /user/report/{id}/download` |
### Callbacks (4) [#callbacks-4]
| Tool | HTTP |
| ----------------------- | --------------------------------------------- |
| `callbacks_list` | `GET /user/callbacks` |
| `callbacks_get` | `GET /user/callbacks/{id}` |
| `callbacks_resend` | `POST /user/callbacks/resend/{transactionId}` |
| `callbacks_resend_bulk` | `POST /user/callbacks/resend` |
### MED infractions (5) [#med-infractions-5]
| Tool | HTTP |
| ---------------------------- | -------------------------------------------------- |
| `infractions_list` | `GET /user/infractions` |
| `infractions_get` | `GET /user/infractions/{id}` |
| `infractions_create_defense` | `POST /user/infractions/{id}/defenses` (multipart) |
| `infractions_list_defenses` | `GET /user/infractions/{id}/defenses` |
| `infractions_get_defense` | `GET /user/infractions/{id}/defenses/{defenseId}` |
## Applied conventions [#applied-conventions]
* Values in decimal BRL. The tool rejects cents: `9990` becomes a validation error, it has to be `99.90`.
* `clientReference` required on creations (idempotency).
* `callbackUrl` required on creations, otherwise nobody tells you the status.
* Auto-retry on 5xx/429 with exponential backoff and jitter (max 3 attempts).
* Errors include `requestId`, copy and paste it into support if needed.
* Zero admin endpoints, only the public and client surface.
### Environment variables [#environment-variables]
| Env var | Required | Default | Description |
| --------------- | -------- | ---------------------------------------- | --------------------------------------------------------------------- |
| `PAYZU_TOKEN` | yes | | Token from [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br) |
| `PAYZU_API_URL` | no | `https://api.payzu.processamento.com/v1` | Override for whitelabel |
## Support [#support]