About mcp-wompi
mcp-wompi is an MCP server for Wompi, the Colombian payment gateway operated by Bancolombia. It suits developers who need agents to handle cards, PSE bank transfers and Nequi payments in Colombia. It exposes 22 tools covering transactions, payment links, tokenization, refunds and webhook signature validation.
Key features
- 01Transaction handling for cards, PSE and Nequi
- 02Payment link creation and management
- 03Card and Nequi tokenization with payment sources
- 04Refund creation and lookup
- 05Customer profiles and PSE bank listing
- 06Webhook event signature validation
Use cases
- 01Letting an agent create payment links for orders and track transaction status
- 02Finding transactions by merchant reference and voiding or refunding them
- 03Creating customer profiles and reusable payment sources
MCP support
This project is an MCP server that exposes 22 Wompi payment tools to MCP clients.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y @codespar/mcp-wompiWOMPI_PUBLIC_KEYSecretPublic key for WompiWOMPI_PRIVATE_KEYSecretPrivate key for WompiWOMPI_EVENTS_SECRETSecretEvents/webhook secret for signature validationLocal servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
22Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| currency | string | Yes | Currency code (COP) |
| reference | string | Yes | Unique transaction reference |
| customer_data | object | No | Customer data |
| customer_data.legal_id | string | No | Legal ID (cedula) |
| customer_data.full_name | string | No | Full name |
| customer_data.phone_number | string | No | Phone number |
| customer_data.legal_id_type | string | No | Legal ID type (CC, NIT, CE) |
| customer_email | string | Yes | Customer email |
| payment_method | object | Yes | Payment method details |
| payment_method.type | string | Yes | Payment type (CARD, NEQUI, PSE, BANCOLOMBIA_TRANSFER) |
| payment_method.token | string | No | Tokenized card token (for CARD) |
| payment_method.user_type | number | No | User type: 0=Natural, 1=Legal (for PSE) |
| payment_method.installments | number | No | Number of installments (for CARD) |
| payment_method.phone_number | string | No | Phone number (for NEQUI) |
| payment_method.payment_description | string | No | Description (for PSE) |
| payment_method.financial_institution_code | string | No | Bank code (for PSE) |
| amount_in_cents | number | Yes | Amount in cents (COP) |
| acceptance_token | string | No | Acceptance token from get_acceptance_token |
Details
From the project README@codespar/mcp-wompi
MCP server for Wompi, the Colombian payment gateway by Bancolombia, supporting cards, PSE bank transfers, Nequi, and Bancolombia transfers
Quick Start
# Set your credentials
export WOMPI_PUBLIC_KEY="pub_test_..."
export WOMPI_PRIVATE_KEY="prv_test_..."
export WOMPI_SANDBOX="true"
# Run via stdio
npx -y @codespar/mcp-wompi
# Run via HTTP
MCP_HTTP=true MCP_PORT=3000 npx -y @codespar/mcp-wompi
Environment Variables
| Variable | Required | Description |
|---|---|---|
WOMPI_PUBLIC_KEY | Yes | Public key from Wompi dashboard |
WOMPI_PRIVATE_KEY | Yes | Private key for server-side operations |
WOMPI_SANDBOX | No | Set to "true" for sandbox environment |
MCP_HTTP | No | Set to "true" to enable HTTP transport |
MCP_PORT | No | HTTP port (default: 3000) |
Tools (22)
| Tool | Purpose |
|---|---|
create_transaction | Create a payment transaction |
get_transaction | Get transaction details by ID |
list_transactions | List transactions |
search_transaction_by_reference | Find transaction(s) by merchant reference |
void_transaction | Void a transaction |
create_payment_link | Create a payment link |
get_payment_link | Get payment link details |
update_payment_link | Update a payment link |
list_payment_links | List payment links |
list_payment_methods | List available payment methods for the merchant |
get_acceptance_token | Get merchant acceptance token (required for transactions) |
create_tokenized_card | Tokenize a credit/debit card |
create_tokenized_nequi | Tokenize a Nequi wallet (start async tokenization by phone number) |
get_tokenization_status | Query async tokenization status (Nequi etc.) by tokenization id |
create_payment_source | Create a reusable payment source (CARD/NEQUI/PSE) linked to a customer email |
create_customer | Create a customer profile |
get_customer | Get customer by ID |
list_financial_institutions | List PSE banks (financial institutions) |
create_refund | Create a refund for a transaction |
get_refund | Get refund details by ID |
get_merchant | Get merchant information |
validate_webhook_signature | Validate a Wompi event signature. |
Auth
Uses Bearer token authentication with the private key. The public key is used for client-side tokenization and merchant queries.
API Reference
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.
Authentication
Set these environment variables before launching the server:
WOMPI_PUBLIC_KEY(required) — Public key for WompiWOMPI_PRIVATE_KEY(required, secret) — Private key for WompiWOMPI_EVENTS_SECRET(secret) — Events/webhook secret for signature validation
Issue credentials at the provider's developer portal: https://docs.wompi.co.
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.