About mcp-pomelo
mcp-pomelo is an MCP server for Pomelo, a card issuing service covering several Latin American countries. It suits applications that issue virtual or physical cards and manage their lifecycle across Argentina, Brazil, Mexico, Colombia, Peru and Chile.
Key features
- 01Card-holder user creation and updates
- 02VIRTUAL and PHYSICAL card issuance
- 03Card status changes for lifecycle management
- 04Card and transaction record queries
- 05Automatic idempotency keys on mutating calls
Use cases
- 01Issuing a virtual card for a new contractor and blocking an old one
- 02Querying card transaction records from an agent workflow
- 03Testing card issuance flows in the sandbox environment
MCP support
This project is an MCP server that exposes 9 tools to MCP clients for managing card-holder users, cards and transaction records.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y @codespar/mcp-pomeloPOMELO_CLIENT_IDSecretOAuth2 client idPOMELO_CLIENT_SECRETSecretOAuth2 client secretPOMELO_ENVEnvironment: 'sandbox' or 'production'. Defaults to 'sandbox'.POMELO_BASE_URLAPI base URL override. Defaults per environment.POMELO_AUTH_URLSecretAuth base URL override. Defaults per environment.POMELO_AUDIENCEOAuth2 audience override. Defaults per environment.Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
9Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Given name |
| string | No | Email address | |
| extra | object | No | Any additional Pomelo user fields, merged into the payload |
| phone | string | No | Phone in international format |
| gender | string | No | MALE | FEMALE | OTHER (country-dependent requirement) |
| address | object | No | Residential address: street_name, street_number, zip_code, city, region, country (ISO-3) |
| surname | string | Yes | Family name |
| birthdate | string | No | YYYY-MM-DD |
| idempotency_key | string | No | Optional idempotency key. Auto-generated when omitted. |
| operation_country | string | Yes | ISO-3 country of operation (e.g. ARG, BRA, MEX, COL) |
| identification_type | string | Yes | Country document type (e.g. DNI, CPF, CURP, CC) |
| identification_value | string | Yes | Document number |
Details
From the project README@codespar/mcp-pomelo
MCP server for Pomelo — pan-LATAM card issuing as a service: card-holder users, virtual and physical Visa/Mastercard issuance, lifecycle management, and the transactions feed. Argentina, Brazil, Mexico, Colombia, Peru, Chile.
Quick Start
Claude Desktop
Add to ~/.config/claude/claude_desktop_config.json:
{
"mcpServers": {
"pomelo": {
"command": "npx",
"args": ["-y", "@codespar/mcp-pomelo"],
"env": {
"POMELO_CLIENT_ID": "your-client-id",
"POMELO_CLIENT_SECRET": "your-client-secret",
"POMELO_ENV": "sandbox"
}
}
}
}
Claude Code
claude mcp add pomelo -- npx @codespar/mcp-pomelo
Cursor / VS Code
Add to .cursor/mcp.json or .vscode/mcp.json:
{
"servers": {
"pomelo": {
"command": "npx",
"args": ["-y", "@codespar/mcp-pomelo"],
"env": {
"POMELO_CLIENT_ID": "your-client-id",
"POMELO_CLIENT_SECRET": "your-client-secret",
"POMELO_ENV": "sandbox"
}
}
}
}
Environment
| Variable | Required | Description |
|---|---|---|
POMELO_CLIENT_ID | yes | OAuth2 client id |
POMELO_CLIENT_SECRET | yes | OAuth2 client secret |
POMELO_ENV | no | sandbox (default) or production |
POMELO_BASE_URL | no | API base override (default https://api-stage.pomelo.la in sandbox, https://api.pomelo.la in production) |
POMELO_AUTH_URL | no | Auth base override; the token call is {AUTH_URL}/oauth/token (default: the same host as the API, per Pomelo's docs) |
POMELO_AUDIENCE | no | OAuth2 audience override (defaults per env) |
Authentication is OAuth2 client-credentials; the server exchanges and caches the Bearer token automatically.
Tools (9)
| Tool | What it does |
|---|---|
create_user | Create a card-holder identity (POST /users/v1) |
get_user | Fetch a user by id |
update_user | Patch user fields (status, contact, address) |
create_card | Issue a VIRTUAL or PHYSICAL card (POST /cards/v1) |
get_card | Fetch a card (masked PAN, status, program) |
list_cards | List cards, filterable by user/status |
update_card_status | ACTIVE / BLOCKED / DISABLED lifecycle changes |
list_transactions | Search the card-transactions feed |
get_transaction | Fetch one transaction by id |
Mutating calls carry an x-idempotency-key (auto-generated, overridable per call via idempotency_key).
Example
"Issue a virtual card for the new contractor and freeze the old one."
The agent calls create_user (if needed) → create_card (card_type: "VIRTUAL") → update_card_status (status: "BLOCKED", status_reason: "CLIENT_INTERNAL_REASON").
Notes
- Card credentials (full PAN/CVV) are never returned by these tools; Pomelo exposes sensitive data only through its PCI-scoped widgets.
- Authorization decisioning (approving each swipe in real time) is a webhook you host, not an API call — pair this server with CodeSpar's governed authorizer if you want mandate checks per transaction.
Authentication
OAuth2 client-credentials: the server exchanges POMELO_CLIENT_ID / POMELO_CLIENT_SECRET for a Bearer token at {AUTH_URL}/oauth/token and caches it until shortly before expiry. Mutating calls carry an x-idempotency-key.
Enterprise
Need governance, budget limits, and audit trails for agent-driven card issuing on Pomelo? CodeSpar Enterprise adds a policy engine, payment routing, and compliance templates on top of these MCP servers.
License
MIT
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.