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. It is not a hosted server and has no URL: 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.

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

Withdrawals (6)

Internal transfer (2)

Account (2)

Reports (6)

Callbacks (4)

MED infractions (5)

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

Support