Getting Started

This guide takes you from zero to a working MCP payment server in under 10 minutes. You will install the SDK, configure a payment rail, connect your server to Claude Desktop, and send a test payment through the conversational 2FA flow.

Prerequisites

  • Node.js 20+ — The SDK uses native fetch and requires ES2022+ runtime support.
  • Package manager — npm, pnpm, yarn, or bun. Examples in this guide use pnpm.
  • MCP client — Claude Desktop (or any MCP-compatible client). Download from claude.ai/download.
  • mcp2p account — Sign up at app.mcp2p.dev to get your sandbox license key.
  • Twilio Verify — A Twilio account with a Verify service configured. Needed for the 2FA step.

Step 1 — Create an account and get your license key

Sign up at app.mcp2p.dev and create your organization. A sandbox license key is generated automatically. You can find it in the dashboard under Settings → License Keys.

Sandbox keys have the prefix mcp2p_test_ and allow unlimited transactions against mock rails only. No real funds move in sandbox mode.

Copy the key and store it in your project's .env file:

MCP2P_LICENSE_KEY=mcp2p_test_your_key_here
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_VERIFY_SERVICE_SID=VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 2 — Install the SDK

Install @mcp2p/sdk into your project:

# pnpm
pnpm add @mcp2p/sdk

# npm
npm install @mcp2p/sdk

# yarn
yarn add @mcp2p/sdk

# bun
bun add @mcp2p/sdk
TypeScript types are bundled with the package. No separate @types/ package is needed.

Step 3 — Create your server

Create a new file server.ts at the root of your project. This is the entry point for your MCP payment server:

import { createMcp2pServer } from "@mcp2p/sdk";

const server = createMcp2pServer({
  licenseKey: process.env.MCP2P_LICENSE_KEY!,

  // Enable the SPEI payment rail (Mexico)
  rails: ["spei"],

  // Your bank aggregator or direct bank connector
  bankConnector: {
    provider: "your-aggregator",
    credentials: {
      apiKey: process.env.BANK_API_KEY!,
    },
  },

  // Twilio Verify for conversational 2FA
  twoFactor: {
    provider: "twilio-verify",
    accountSid: process.env.TWILIO_ACCOUNT_SID!,
    authToken: process.env.TWILIO_AUTH_TOKEN!,
    verifyServiceSid: process.env.TWILIO_VERIFY_SERVICE_SID!,
    // Phone number of the person authorizing payments
    phoneNumber: "+525512345678",
  },
});

server.start();

Configuration options

  • licenseKey — Required. Your mcp2p license key. Always read from an environment variable, never hardcode.
  • rails — Array of payment rails to enable. Options: "spei", "pse", "pix". Your license tier determines which rails are available.
  • bankConnector — Configuration for your bank aggregator. The SDK delegates payment execution here.
  • twoFactor — 2FA provider configuration. See the Two-Factor Auth guide for all options.

Step 4 — Start the server

Run the server with tsx (or compile first with tsc):

# Install tsx if you don't have it
pnpm add -D tsx

# Start the server
npx tsx server.ts

On startup you will see license validation output, followed by the MCP server listening on its configured transport (stdio by default):

[mcp2p] License validated: sandbox, rails=["spei"]
[mcp2p] MCP server ready — listening on stdio

Step 5 — Connect to Claude Desktop

Open Claude Desktop's settings and edit the MCP configuration file. On macOS it is located at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp2p-payments": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/your/server.ts"],
      "env": {
        "MCP2P_LICENSE_KEY": "mcp2p_test_your_key_here",
        "TWILIO_ACCOUNT_SID": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "TWILIO_AUTH_TOKEN": "your_auth_token",
        "TWILIO_VERIFY_SERVICE_SID": "VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "BANK_API_KEY": "your_bank_api_key"
      }
    }
  }
}
Use absolute paths in the config. Relative paths may fail depending on how Claude Desktop launches the server process.

Restart Claude Desktop after saving the config. You should see a hammer icon in the chat interface indicating your MCP tools are connected.

Step 6 — Send a test payment

Open a new conversation in Claude Desktop and try sending a SPEI payment. Because you are in sandbox mode, the transfer will be simulated but the full 2FA flow will run end-to-end:

“Send 500 MXN via SPEI to CLABE 014027000005555558”

Claude will call spei_send_payment without a verification code. The SDK will dispatch an SMS via Twilio Verify and return a 2fa_required status. Claude will then ask the user for the code:

“I've initiated the transfer. Please enter the verification code sent to your phone to authorize this payment.”

Reply with the code you received. Claude will call the tool again with the verification code. The SDK verifies it and executes the transfer, returning the transaction result.

What's next