Configuration

This page documents all configuration options accepted by createMcp2pServer. Every option is validated at runtime with Zod, and TypeScript will surface missing required fields at compile time.

createMcp2pServer

The main entrypoint for the SDK. Pass a single configuration object:

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

const server = createMcp2pServer({
  licenseKey: process.env.MCP2P_LICENSE_KEY!,
  rails: ["spei", "pse"],
  bankConnector: { ... },
  twoFactor: { ... },
  licenseServer: { ... },   // optional
  logging: { ... },         // optional
});

server.start();

Top-level options

Rail configuration

The rails array determines which payment tools are registered with the MCP server. Each rail string corresponds to a set of MCP tools (send, check status, refund).

createMcp2pServer({
  // Enable multiple rails
  rails: ["spei", "pse", "pix"],

  // Or a single rail
  rails: ["spei"],
})

Rail-specific options

Each rail can also accept fine-grained options via a per-rail config object instead of a plain string:

createMcp2pServer({
  rails: [
    {
      id: "spei",
      // Override the max transfer amount (in minor units — centavos)
      maxAmount: 50_000_00,
      // Restrict to specific bank codes
      allowedBankCodes: ["014", "072"],
    },
    {
      id: "pix",
      // Restrict allowed PIX key types
      allowedKeyTypes: ["cpf", "cnpj"],
    },
  ],
})

Bank connector

The bankConnector object configures how the SDK delegates actual payment execution to your aggregator or bank:

createMcp2pServer({
  bankConnector: {
    // Name of your aggregator provider
    provider: "your-aggregator",

    credentials: {
      apiKey: process.env.BANK_API_KEY!,
      // Additional credentials depend on your provider
    },

    // Optional: sandbox mode forces all requests to test endpoints
    sandbox: process.env.NODE_ENV !== "production",

    // Optional: request timeout in milliseconds (default: 30000)
    timeoutMs: 30_000,
  },
})

2FA provider setup

The twoFactor object configures Twilio Verify for conversational 2FA:

createMcp2pServer({
  twoFactor: {
    provider: "twilio-verify",

    // Twilio credentials
    accountSid: process.env.TWILIO_ACCOUNT_SID!,
    authToken: process.env.TWILIO_AUTH_TOKEN!,
    verifyServiceSid: process.env.TWILIO_VERIFY_SERVICE_SID!,

    // Phone number that receives the OTP
    phoneNumber: "+525512345678",

    // Optional: code expiry in seconds (default: 600)
    codeExpirySeconds: 600,

    // Optional: max verification attempts before lockout (default: 3)
    maxAttempts: 3,
  },
})

See the Two-Factor Auth guide for the full flow explanation and advanced options.

License key configuration

The licenseKey field accepts a plain string. The SDK also accepts optional licenseServer config to override defaults:

createMcp2pServer({
  licenseKey: process.env.MCP2P_LICENSE_KEY!,

  licenseServer: {
    // Optional: override the license server URL
    // Useful for self-hosted or enterprise setups
    url: "https://your-license-server.example.com",

    // Optional: how long to cache a valid license response (seconds)
    // Default: 300 (5 minutes)
    cacheTtlSeconds: 300,
  },
})

Logging

createMcp2pServer({
  logging: {
    // "debug" | "info" | "warn" | "error" | "silent"
    level: "info",

    // "json" | "pretty" — use "json" in production for log aggregators
    format: process.env.NODE_ENV === "production" ? "json" : "pretty",
  },
})

Environment variables reference

All sensitive values should be read from environment variables rather than hardcoded. The recommended variable names match the .env.example file in the repository:

# License
MCP2P_LICENSE_KEY=mcp2p_test_your_key_here

# Twilio Verify
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_VERIFY_SERVICE_SID=VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Bank connector
BANK_API_KEY=your_aggregator_api_key

# Optional
MCP2P_LICENSE_SERVER_URL=https://license.mcp2p.dev
NODE_ENV=production

Full example

A complete configuration file for a production deployment with all three rails enabled:

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

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

  rails: ["spei", "pse", "pix"],

  bankConnector: {
    provider: "your-aggregator",
    credentials: {
      apiKey: process.env.BANK_API_KEY!,
    },
    sandbox: process.env.NODE_ENV !== "production",
    timeoutMs: 30_000,
  },

  twoFactor: {
    provider: "twilio-verify",
    accountSid: process.env.TWILIO_ACCOUNT_SID!,
    authToken: process.env.TWILIO_AUTH_TOKEN!,
    verifyServiceSid: process.env.TWILIO_VERIFY_SERVICE_SID!,
    phoneNumber: "+525512345678",
    codeExpirySeconds: 600,
    maxAttempts: 3,
  },

  licenseServer: {
    cacheTtlSeconds: 300,
  },

  logging: {
    level: "info",
    format: "json",
  },
});

server.start();

Next steps

• SPEI (Mexico) — MCP tool schemas and CLABE validation for SPEI transfers
• PSE (Colombia) — NIT/CC validation and PSE-specific configuration
• PIX (Brazil) — PIX key types and CPF/CNPJ validation