MCP Tools

This page provides the complete reference for every MCP tool registered by mcp2p, grouped by payment rail. Each entry includes the tool description, full parameter table, return type, and an example request/response pair.

Tools are only registered for rails enabled in your createMcp2pServer config. If you only enable "spei", the pse_* and pix_* tools will not appear in the tools/list response.

Amount conventions

All amounts are in minor units (centavos / centimos) as integers.
MXN: 50000 centavos = MXN 500.00
COP: 10000000 centavos = COP 100,000.00
BRL: 15000 centavos = BRL 150.00

SPEI

Real-time interbank transfers in Mexico via BANXICO. CLABE routing.

spei_send_payment

SPEI2FA required

Initiate a SPEI interbank transfer to a CLABE account. On the first call (without verificationCode), the SDK sends an SMS via Twilio Verify and returns 2fa_required. On the second call (with verificationCode), it verifies the code and executes the transfer.

Parameters

Name	Type	Required	Description
clabe	string	Yes	18-digit CLABE account number. Must pass modulus-10 checksum.
amount	number	Yes	Amount in centavos (minor units). E.g. 50000 = MXN 500.00. Must be a positive integer.
concept	string	Yes	Transfer concept or description. Max 40 characters.
recipientName	string	Yes	Full legal name of the recipient account holder.
verificationCode	string	No	6-digit OTP received via SMS. Omit on first call to trigger the SMS.

Return type

{ status: "success" | "2fa_required", trackingKey?: string, amount?: number, currency?: "MXN", settledAt?: string }

Example

Request arguments

{
  "name": "spei_send_payment",
  "arguments": {
    "clabe": "014027000005555558",
    "amount": 50000,
    "concept": "Invoice #42",
    "recipientName": "Empresa Demo SA de CV",
    "verificationCode": "847291"
  }
}

Response payload

{
  "data": {
    "status": "success",
    "trackingKey": "2024012614574900000012345678",
    "amount": 50000,
    "currency": "MXN",
    "settledAt": "2024-01-26T14:57:52Z"
  },
  "error": null
}

spei_check_status

SPEINo 2FA

Check the current status of a SPEI transaction using its clave de rastreo (tracking key). Does not require 2FA.

Parameters

Name	Type	Required	Description
trackingKey	string	Yes	The SPEI tracking key (clave de rastreo) returned by spei_send_payment.

Return type

{ status: "pending" | "settled" | "rejected" | "returned", trackingKey: string, amount: number, currency: "MXN", updatedAt: string }

Example

Request arguments

{
  "name": "spei_check_status",
  "arguments": {
    "trackingKey": "2024012614574900000012345678"
  }
}

Response payload

{
  "data": {
    "status": "settled",
    "trackingKey": "2024012614574900000012345678",
    "amount": 50000,
    "currency": "MXN",
    "updatedAt": "2024-01-26T14:57:52Z"
  },
  "error": null
}

spei_request_refund

SPEI2FA required

Request a refund for a completed SPEI transfer. Follows the same 2FA two-turn pattern as spei_send_payment.

Parameters

Name	Type	Required	Description
trackingKey	string	Yes	Tracking key of the original transaction to refund.
reason	string	Yes	Human-readable reason for the refund request.
verificationCode	string	No	6-digit OTP. Omit on first call to trigger SMS.

Return type

{ status: "refund_requested" | "2fa_required", refundTrackingKey?: string }

Example

Request arguments

{
  "name": "spei_request_refund",
  "arguments": {
    "trackingKey": "2024012614574900000012345678",
    "reason": "Duplicate payment",
    "verificationCode": "193847"
  }
}

Response payload

{
  "data": {
    "status": "refund_requested",
    "refundTrackingKey": "2024012615001200000099887766"
  },
  "error": null
}

PSE

Electronic payments in Colombia via ACH Colombia. NIT/CC routing.

pse_send_payment

PSE2FA required

Initiate a PSE electronic payment through ACH Colombia. Requires 2FA authorization via the same two-turn pattern.

Parameters

Name	Type	Required	Description
recipientId	string	Yes	Recipient identifier with type prefix. Format: "NIT:123456789" or "CC:12345678".
bankCode	string	Yes	3-digit ACH Colombia bank code for the receiving institution.
amount	number	Yes	Amount in centavos de peso (minor units). E.g. 10000000 = COP 100,000.00.
description	string	Yes	Payment description. Max 60 characters.
verificationCode	string	No	6-digit OTP. Omit on first call to trigger SMS.

Return type

{ status: "success" | "2fa_required", referenceNumber?: string, amount?: number, currency?: "COP", settledAt?: string }

Example

Request arguments

{
  "name": "pse_send_payment",
  "arguments": {
    "recipientId": "NIT:900123456",
    "bankCode": "001",
    "amount": 10000000,
    "description": "Supplier payment Q1",
    "verificationCode": "391847"
  }
}

Response payload

{
  "data": {
    "status": "success",
    "referenceNumber": "PSE-2024012614574900012345",
    "amount": 10000000,
    "currency": "COP",
    "settledAt": "2024-01-26T14:58:03Z"
  },
  "error": null
}

pse_check_status

PSENo 2FA

Check the current status of a PSE transaction by its reference number.

Parameters

Name	Type	Required	Description
referenceNumber	string	Yes	PSE reference number returned by pse_send_payment.

Return type

{ status: "pending" | "approved" | "rejected" | "reversed", referenceNumber: string, amount: number, currency: "COP", updatedAt: string }

Example

Request arguments

{
  "name": "pse_check_status",
  "arguments": {
    "referenceNumber": "PSE-2024012614574900012345"
  }
}

Response payload

{
  "data": {
    "status": "approved",
    "referenceNumber": "PSE-2024012614574900012345",
    "amount": 10000000,
    "currency": "COP",
    "updatedAt": "2024-01-26T14:58:05Z"
  },
  "error": null
}

pse_request_refund

PSE2FA required

Request a reversal for a completed PSE payment. Requires 2FA authorization.

Parameters

Name	Type	Required	Description
referenceNumber	string	Yes	Reference number of the original PSE transaction.
reason	string	Yes	Reason for the refund request.
verificationCode	string	No	6-digit OTP. Omit on first call to trigger SMS.

Return type

{ status: "refund_requested" | "2fa_required", refundReferenceNumber?: string }

Example

Request arguments

{
  "name": "pse_request_refund",
  "arguments": {
    "referenceNumber": "PSE-2024012614574900012345",
    "reason": "Customer request",
    "verificationCode": "748392"
  }
}

Response payload

{
  "data": {
    "status": "refund_requested",
    "refundReferenceNumber": "PSE-REV-2024012615001200099887"
  },
  "error": null
}

PIX

Instant payments in Brazil via Banco Central. Key-based routing.

pix_send_payment

PIX2FA required

Send a PIX instant payment to any registered PIX key. The SDK auto-detects the key type (CPF, CNPJ, email, phone, EVP).

Parameters

Name	Type	Required	Description
pixKey	string	Yes	Recipient PIX key. SDK auto-detects type: CPF (11 digits), CNPJ (14 digits), phone (+55...), email, or UUID v4 (EVP).
amount	number	Yes	Amount in centavos (minor units). E.g. 15000 = BRL 150.00.
description	string	No	Payment description visible to the recipient. Max 140 characters.
verificationCode	string	No	6-digit OTP. Omit on first call to trigger SMS.

Return type

{ status: "success" | "2fa_required", e2eId?: string, amount?: number, currency?: "BRL", settledAt?: string }

Example

Request arguments

{
  "name": "pix_send_payment",
  "arguments": {
    "pixKey": "12345678909",
    "amount": 15000,
    "description": "Lunch split",
    "verificationCode": "583921"
  }
}

Response payload

{
  "data": {
    "status": "success",
    "e2eId": "E90400888202401261458300000000001",
    "amount": 15000,
    "currency": "BRL",
    "settledAt": "2024-01-26T14:58:06Z"
  },
  "error": null
}

pix_check_status

PIXNo 2FA

Check the status of a PIX payment by its end-to-end ID (E2EID).

Parameters

Name	Type	Required	Description
e2eId	string	Yes	End-to-end ID (E2EID) returned by pix_send_payment.

Return type

{ status: "pending" | "settled" | "failed" | "devolved", e2eId: string, amount: number, currency: "BRL", updatedAt: string }

Example

Request arguments

{
  "name": "pix_check_status",
  "arguments": {
    "e2eId": "E90400888202401261458300000000001"
  }
}

Response payload

{
  "data": {
    "status": "settled",
    "e2eId": "E90400888202401261458300000000001",
    "amount": 15000,
    "currency": "BRL",
    "updatedAt": "2024-01-26T14:58:08Z"
  },
  "error": null
}

pix_request_refund

PIX2FA required

Request a PIX Devolução (refund) for a completed payment. Supports partial refunds.

Parameters

Name	Type	Required	Description
e2eId	string	Yes	E2EID of the original PIX payment.
amount	number	No	Amount to refund in centavos. If omitted, refunds the full original amount.
reason	string	Yes	Refund reason code: "FRAUD", "OPERATIONAL_FAULT", or "CUSTOMER_REQUEST".
verificationCode	string	No	6-digit OTP. Omit on first call to trigger SMS.

Return type

{ status: "refund_requested" | "2fa_required", refundE2eId?: string, amount?: number }

Example

Request arguments

{
  "name": "pix_request_refund",
  "arguments": {
    "e2eId": "E90400888202401261458300000000001",
    "amount": 15000,
    "reason": "CUSTOMER_REQUEST",
    "verificationCode": "927384"
  }
}

Response payload

{
  "data": {
    "status": "refund_requested",
    "refundE2eId": "E90400888202401261501100000000002",
    "amount": 15000
  },
  "error": null
}

Error Codes — Full error code reference for all tools
Two-Factor Auth — How the 2FA two-turn flow works
SPEI guide, PSE guide, PIX guide — Rail-specific validation rules and error codes

MCP Tools

Amount conventions

SPEI

spei_send_payment

spei_check_status

spei_request_refund

PSE

pse_send_payment

pse_check_status

pse_request_refund

PIX

pix_send_payment

pix_check_status

pix_request_refund

Related pages