mcp-nupay — Claude Code MCP server: what it does, how to install
Connects AI assistants to the NuPay merchant checkout by Nubank. It handles Pix transactions, manages shopper refunds, and configures recurring billing flows.
claude mcp add --env NUPAY_MERCHANT_KEY=<NUPAY_MERCHANT_KEY> --env NUPAY_MERCHANT_TOKEN=<NUPAY_MERCHANT_TOKEN> --env NUPAY_CLIENT_ID=<NUPAY_CLIENT_ID> --env NUPAY_CLIENT_SECRET=<NUPAY_CLIENT_SECRET> --env NUPAY_ENV=<NUPAY_ENV> --transport stdio nupay -- npx -y @codespar/mcp-nupayWhat mcp-nupay does
The server exposes 22 distinct tools directly tied to NuPay checkout endpoints. Assistants can initiate transactions, look up payment states via pspReferenceId, void pending requests, and issue partial or full refunds. It also covers merchant settlement reports and recipient registration for regulatory payment splits.
Two authentication modes exist. Standard actions need NUPAY_MERCHANT_KEY alongside NUPAY_MERCHANT_TOKEN. Reusable tokens and recurring checkouts rely on OAuth2 CIBA workflows with one-time passwords. Signing the JWT client_assertion must happen on your side before invoking exchange_token.
What it helps with
- create checkout charges via Pix and mobile wallet
- inspect payment progress using
pspReferenceId - issue full or partial customer refunds
- initiate recurring authorization flows with one-time passwords
Example prompts for the agent
- Generate a NuPay payment for 120 BRL and retrieve its status
- Issue a partial refund for payment reference
pspReferenceId - Initiate buyer pre-authorization using
backchannel_start
How to install mcp-nupay
Platform CLI
claude mcp add --env NUPAY_MERCHANT_KEY=<NUPAY_MERCHANT_KEY> --env NUPAY_MERCHANT_TOKEN=<NUPAY_MERCHANT_TOKEN> --env NUPAY_CLIENT_ID=<NUPAY_CLIENT_ID> --env NUPAY_CLIENT_SECRET=<NUPAY_CLIENT_SECRET> --env NUPAY_ENV=<NUPAY_ENV> --transport stdio nupay -- npx -y @codespar/mcp-nupayReplace <…> with your own values
Platform CLI
codex mcp add nupay --env NUPAY_MERCHANT_KEY=<NUPAY_MERCHANT_KEY> --env NUPAY_MERCHANT_TOKEN=<NUPAY_MERCHANT_TOKEN> --env NUPAY_CLIENT_ID=<NUPAY_CLIENT_ID> --env NUPAY_CLIENT_SECRET=<NUPAY_CLIENT_SECRET> --env NUPAY_ENV=<NUPAY_ENV> -- npx -y @codespar/mcp-nupayReplace <…> with your own values
Config file
{
"mcpServers": {
"nupay": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-nupay"
],
"env": {
"NUPAY_MERCHANT_KEY": "<NUPAY_MERCHANT_KEY>",
"NUPAY_MERCHANT_TOKEN": "<NUPAY_MERCHANT_TOKEN>",
"NUPAY_CLIENT_ID": "<NUPAY_CLIENT_ID>",
"NUPAY_CLIENT_SECRET": "<NUPAY_CLIENT_SECRET>",
"NUPAY_ENV": "<NUPAY_ENV>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"nupay": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-nupay"
],
"env": {
"NUPAY_MERCHANT_KEY": "<NUPAY_MERCHANT_KEY>",
"NUPAY_MERCHANT_TOKEN": "<NUPAY_MERCHANT_TOKEN>",
"NUPAY_CLIENT_ID": "<NUPAY_CLIENT_ID>",
"NUPAY_CLIENT_SECRET": "<NUPAY_CLIENT_SECRET>",
"NUPAY_ENV": "<NUPAY_ENV>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e NUPAY_MERCHANT_KEY=<NUPAY_MERCHANT_KEY> -e NUPAY_MERCHANT_TOKEN=<NUPAY_MERCHANT_TOKEN> -e NUPAY_CLIENT_ID=<NUPAY_CLIENT_ID> -e NUPAY_CLIENT_SECRET=<NUPAY_CLIENT_SECRET> -e NUPAY_ENV=<NUPAY_ENV> nupay npx -y @codespar/mcp-nupayReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-nupay
How to install mcp-nupay in Claude Code?
Run `claude mcp add mcp-nupay -e NUPAY_MERCHANT_KEY=<NUPAY_MERCHANT_KEY> -e NUPAY_MERCHANT_TOKEN=<NUPAY_MERCHANT_TOKEN> -e NUPAY_CLIENT_SECRET=<NUPAY_CLIENT_SECRET> -- npx -y @codespar/mcp-nupay. You can pass optional parameters like NUPAY_ENV or NUPAY_CLIENT_ID` in the same format.
What does mcp-nupay do?
It allows language models to operate NuPay checkout operations in Brazil. Agents can issue charges, query settlements, perform refunds, and register split beneficiaries.
Does mcp-nupay sign JWT client assertions automatically?
No, generating and signing the JWT client_assertion remains the caller's duty. The exchange_token endpoint requires an already signed assertion header.
