MCP server

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 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 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 (payzu-pix).

Before you start

Get your API token at 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.

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:

• 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 <your-token>".
• Claude Desktop (local installer): download payzu-mcp-pix.mcpb 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.

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:

{
  "mcpServers": {
    "payzu-pix": {
      "command": "npx",
      "args": ["-y", "payzu-mcp-pix"],
      "env": { "PAYZU_TOKEN": "your-token-here" }
    }
  }
}

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.

Claude Code

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:

claude mcp add payzu-pix --scope user --env PAYZU_TOKEN=your-token -- npx -y payzu-mcp-pix

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "payzu-pix": {
      "command": "npx",
      "args": ["-y", "payzu-mcp-pix"],
      "env": { "PAYZU_TOKEN": "your-token-here" }
    }
  }
}

Restart Claude Desktop after saving.

Cursor

Edit .cursor/mcp.json in the project or ~/.cursor/mcp.json to apply everywhere:

{
  "mcpServers": {
    "payzu-pix": {
      "command": "npx",
      "args": ["-y", "payzu-mcp-pix"],
      "env": { "PAYZU_TOKEN": "your-token-here" }
    }
  }
}

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:

{
  "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

Edit ~/.codeium/windsurf/mcp_config.json, same mcpServers shape:

{
  "mcpServers": {
    "payzu-pix": {
      "command": "npx",
      "args": ["-y", "payzu-mcp-pix"],
      "env": { "PAYZU_TOKEN": "your-token-here" }
    }
  }
}

Step by step

1. Get your token at 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"

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?

• Error [401]: invalid or expired token. Generate a new one at abrirconta.payzu.com.br.
• Server missing from the tool list: reload or restart the client (in Antigravity, use Refresh).

Tool list (48)

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 Payments (6)

Refunds (1)

Webhooks (8)

Internal transfer (2)

Account (3)

Reports (11)

Callbacks (8)

MED infractions (5)

¹ Disabled on the hosted server, for the reason in the warning above: they register as stubs and answer that the operation is unavailable. They work in the local app (npx payzu-mcp-pix or the .mcpb installer).

Applied conventions

• Values in decimal BRL, never in cents: R$ 99.90 is 99.90.
• clientReference required on creations (idempotency).
• callbackUrl is optional on creations. Without it that transaction has no delivery of its own; registered webhooks still receive the events, and the status is also available through the query tool.
• Auto-retry only on read requests (GET, HEAD, OPTIONS) and only on statuses 408, 429, 500, 502, 503 and 504, with exponential backoff and jitter, up to 3 retries. Creations are never retried: a failed POST does not become a duplicate charge.
• Errors include requestId, copy and paste it into support if needed.
• Zero admin endpoints, only the public and client surface.

Environment variables

Support