mcpField
M
mcp-kushki

mcp-kushki

Local
github.com/codesparFinance275Updated 4w ago
Repository

About mcp-kushki

mcp-kushki is an MCP server for Kushki, a PSP operating in Mexico, Colombia, Chile, Peru and Ecuador. It exposes card charges, preauthorization, PSE/SPEI bank transfers, cash vouchers and subscriptions through one REST API. It suits developers and agents handling LATAM payments.

Key features

  1. 01Card tokenization and one-step charges
  2. 02Two-step preauthorization with partial capture
  3. 03PSE and SPEI bank transfer collection
  4. 04Cash voucher payments
  5. 05Recurring card subscriptions with cancellation

Use cases

  1. 01Letting an agent tokenize a test card and charge it
  2. 02Collecting COP payments with IVA tax breakdown
  3. 03Creating or cancelling recurring charges for a subscription service

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "codespar-mcp-kushki": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-kushki"
      ],
      "env": {
        "KUSHKI_PUBLIC_MERCHANT_ID": "<KUSHKI_PUBLIC_MERCHANT_ID>",
        "KUSHKI_PRIVATE_MERCHANT_ID": "<KUSHKI_PRIVATE_MERCHANT_ID>",
        "KUSHKI_ENV": "<KUSHKI_ENV>"
      }
    }
  }
}
Run commandnpx -y @codespar/mcp-kushki
Environment variables to set
KUSHKI_PUBLIC_MERCHANT_IDSecretKushki public merchant id (card/transfer tokenization)
KUSHKI_PRIVATE_MERCHANT_IDSecretKushki private merchant id (charges, captures, voids, subscriptions)
KUSHKI_ENVEnvironment: 'sandbox' (api-uat) or 'production'. Defaults to '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.

Packages
npm@codespar/mcp-kushki0.1.0

Tools

10

Saved tool list · updated 2w ago

ParameterTypeRequiredDescription
cardobjectYesCard data
card.cvvstringYesSecurity code
card.namestringYesCardholder name
card.numberstringYesCard number (PAN)
card.expiryYearstringYesYY
card.expiryMonthstringYesMM
currencystringYesMXN | COP | CLP | PEN | USD
totalAmountnumberYesTotal amount the token will charge

Details

From the project README

@codespar/mcp-kushki

MCP server for Kushki — the omnichannel PSP spanning Mexico, Colombia, Chile, Peru and Ecuador: card tokenization + one-step/two-step charges, bank transfer-in (PSE / SPEI), cash networks and subscriptions, all on one REST API.

npm License: MIT

Quick Start

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kushki": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-kushki"],
      "env": {
        "KUSHKI_PUBLIC_MERCHANT_ID": "your-public-merchant-id",
        "KUSHKI_PRIVATE_MERCHANT_ID": "your-private-merchant-id",
        "KUSHKI_ENV": "sandbox"
      }
    }
  }
}
Claude Code
claude mcp add kushki --env KUSHKI_PUBLIC_MERCHANT_ID=... --env KUSHKI_PRIVATE_MERCHANT_ID=... -- npx -y @codespar/mcp-kushki
Cursor / VS Code

Add the same block to .cursor/mcp.json or .vscode/mcp.json.

Tools (10)

ToolEndpointWhat it does
tokenize_cardPOST /card/v1/tokensRaw card → single-use token (public id)
create_chargePOST /card/v1/chargesOne-step card charge
create_preauthorizationPOST /card/v1/preAuthorizationHold funds (two-step, step 1)
capture_preauthorizationPOST /card/v1/captureCapture a preauth (step 2, partial OK)
void_chargeDELETE /card/v1/charges/{ticket}Void (same-day) or refund (settled)
create_transfer_tokenPOST /transfer/v1/tokensToken for PSE (CO) / SPEI (MX) transfer-in
create_transfer_chargePOST /transfer/v1/initStart the bank transfer; returns redirect URL
create_cash_chargePOST /cash/v1/chargesCash voucher for OXXO-style networks
create_subscriptionPOST /card/v1/subscriptionsRecurring card charge on a periodicity
cancel_subscriptionDELETE /card/v1/subscriptions/{id}Stop future charges

Authentication

Two merchant ids with distinct powers:

VariableRequiredDescription
KUSHKI_PUBLIC_MERCHANT_IDyesTokenization only — safe for client-side use
KUSHKI_PRIVATE_MERCHANT_IDyesMoney movement — server-side only
KUSHKI_ENVnosandbox (api-uat, default) or production

Amounts use Kushki's per-country tax shape: { subtotalIva, subtotalIva0, iva, currency } — currencies MXN, COP, CLP, PEN, USD.

Example

"Tokenize this test card and charge COP 85,000 with 19% IVA."

The agent calls tokenize_card, then create_charge with { subtotalIva: 85000, subtotalIva0: 0, iva: 16150, currency: "COP" }.

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.

Managed tier

This open-source server calls Kushki's API directly with your credentials. CodeSpar's managed tier routes one interface across every LATAM provider with automatic failover, governance, audit and a credential vault: codespar.dev/agents.

License

MIT

Comments

Markdown supported

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.