About mcp-dlocal
mcp-dlocal is an MCP server for dLocal that handles cross-border payments, payouts and refunds across more than 15 LatAm countries through one API. It is aimed at merchants and developers who need local payment methods in several Latin American markets.
Key features
- 01Pay-ins with local payment methods across LatAm
- 02Payment, refund and payout query and management
- 03Outgoing payouts to beneficiaries in LatAm countries
- 04Per-country payment method listing at runtime
- 05Tax document validation and FX rate queries
Use cases
- 01Accepting payments in several LatAm countries with local methods
- 02Sending payouts to suppliers or beneficiaries in the region
- 03Querying available payment methods per country instead of hard-coding them
MCP support
This is an MCP server that exposes dLocal payment, refund, payout and lookup tools to MCP clients. Requests are signed automatically with V2 HMAC-SHA256.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y @codespar/mcp-dlocalDLOCAL_LOGINdLocal API Login (X-Login header)DLOCAL_TRANS_KEYSecretdLocal API Trans-Key (X-Trans-Key header)DLOCAL_SECRET_KEYSecretdLocal API Secret Key used to sign V2 HMAC-SHA256 requestsDLOCAL_BASE_URLdLocal API base URL. Defaults to https://api.dlocal.com (prod). Use https://sandbox.dlocal.com for sandbox.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
18Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| card | object | No | For DIRECT card flow only — tokenized card object. Omit for REDIRECT. |
| payer | object | Yes | Payer identification |
| payer.name | string | Yes | Payer full name |
| payer.email | string | Yes | Payer email |
| payer.document | string | Yes | Local tax ID (CPF/CNPJ for BR, RFC for MX, DNI for AR, etc) |
| payer.user_reference | string | No | Merchant-side stable user ID |
| amount | number | Yes | Amount in the country's currency, major units (e.g. 100 = 100 BRL, not cents) |
| country | string | Yes | ISO-3166 alpha-2 country code (BR, MX, AR, CO, CL, PE, UY, EC, BO, CR, GT) |
| currency | string | Yes | ISO-4217 currency code (BRL, MXN, ARS, COP, CLP, PEN, USD, etc) |
| order_id | string | Yes | Merchant-side order reference (appears in reports) |
| description | string | No | Human-readable description for the payer |
| callback_url | string | No | Browser redirect target after REDIRECT flow completes |
| notification_url | string | No | Webhook URL dLocal calls on status changes |
| payment_method_id | string | Yes | Method id from /payments-methods (e.g. CARD, PIX, OX, PSE, SPEI). Use list_payment_methods to enumerate for a country. |
| payment_method_flow | enum | Yes | DIRECT for tokenized card; REDIRECT for hosted flow (OXXO voucher, Pix QR, PSE bank select)DIRECT | REDIRECT |
Details
From the project README@codespar/mcp-dlocal
MCP server for dLocal — LatAm cross-border payments.
One API, 15+ LatAm countries, local payment methods (Pix, OXXO, PSE, SPEI, Boleto, cards). The abstraction that per-country PSP servers cannot provide on their own.
Tools (18)
| Tool | Purpose |
|---|---|
create_payment | Create a payment (pay-in) in a LatAm country using a local payment method. |
get_payment | Get payment status and full detail by dLocal payment id. |
get_payment_by_order_id | Get a payment by the merchant-side order_id supplied at creation time. |
list_payments | List payments with optional date / country / status filters. |
capture_payment | Capture an AUTHORIZED card payment. |
cancel_payment | Cancel an authorized-but-not-captured payment, or void a PENDING payment. |
create_refund | Refund a captured payment. |
get_refund | Get refund status by refund id. |
list_refunds | List refunds, optionally scoped to a payment_id. |
create_payout | Send money out to a beneficiary in a LatAm country. |
get_payout | Get payout status by dLocal payout id. |
get_payout_by_external_id | Get a payout by the merchant external_id / order_id supplied at creation time. |
list_payouts | List payouts with optional date / country / status filters. |
list_payment_methods | List all payment methods available for a given country. |
get_balance | Get the merchant's current available balance per currency. |
get_exchange_rate | Query the dLocal FX rate for a destination country/currency pair. |
create_card_token | Tokenize a card for use in DIRECT-flow create_payment. |
validate_document | Validate a LatAm tax/identity document (CPF or CNPJ in BR, CUIT/CUIL/DNI in AR, RUT in CL/UY, RFC/CURP in M... |
Install
npm install @codespar/mcp-dlocal
Environment
DLOCAL_LOGIN="..." # X-Login header value
DLOCAL_TRANS_KEY="..." # X-Trans-Key header value
DLOCAL_SECRET_KEY="..." # HMAC secret used to sign V2 requests
DLOCAL_BASE_URL="..." # Optional. Defaults to https://api.dlocal.com. Use https://sandbox.dlocal.com for sandbox.
Authentication
Every request signs with V2 HMAC-SHA256:
X-Date: <ISO-8601 UTC>
X-Login: <login>
X-Trans-Key: <trans_key>
Authorization: V2-HMAC-SHA256, Signature: <hex(hmac_sha256(login + x_date + body, secret_key))>
The server handles signing automatically — you only configure the three env vars.
Run
# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-dlocal
# HTTP (for server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-dlocal
Countries covered
Argentina, Bolivia, Brazil, Chile, Colombia, Costa Rica, Ecuador, Guatemala, Mexico, Peru, Uruguay, and more. Use list_payment_methods to enumerate available methods per country at runtime rather than hard-coding.
Enterprise
Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds 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.