Twilio Agent Payments MCP Server

🚀 Twilio Voice MCP Server Plugin Development Documentation

This MCP server plugin is designed to integrate with Twilio's voice API and payment processing capabilities. It offers the following core features:

• Initiate payment capture
• Capture credit card numbers
• Capture security codes
• Capture card types
• Retrieve payment status

All actual payment data processing and storage are handled by Twilio's secure processes, ensuring PCI compliance.

✨ Features

Core Utility Classes

Initiate Payment Capture

interface StartPaymentCaptureParams {
    accountSid: string;
    apiKey: string;
    apiSecretKey: string;
}

class StartPaymentCaptureTool extends EventEmitter {
    constructor(params: StartPaymentCaptureParams) {
        super();
        // Initialize the Twilio client
    }

    async startPaymentCapture(callSid: string, amount: string): Promise<PaymentSession> {
        // Invoke the Twilio voice API to start a payment capture session
        // Return a new PaymentSession object
    }
}

Capture Credit Card Numbers

interface CaptureCardNumberParams {
    accountSid: string;
    apiKey: string;
    apiSecretKey: string;
}

class CaptureCardNumberTool extends EventEmitter {
    constructor(params: CaptureCardNumberParams) {
        super();
    }

    async captureCardNumber(callSid: string): Promise<PaymentData> {
        // Invoke the Twilio voice API to capture credit card numbers
        // Process the returned payment data
    }
}

Other Utility Classes

• CaptureSecurityCodeTool - Capture security verification codes
• CaptureCardTypeTool - Capture card types
• GetPaymentStatusTool - Retrieve payment status

Payment Callback Data Structure

Initial Connector Data

{
  "PaymentConnector": "PGP_MOCK",
  "DateCreated": "2021-08-10T03:55:53.408Z",
  "PaymentMethod": "credit-card",
  "CallSid": "CAzzzzz",
  "ChargeAmount": "9.99",
  "AccountSid": "ACxxxxx",
  "Sid": "PKxxxx"
}

Captured Data

{ 
  "SecurityCode": "xxx",          // Security verification code
  "PaymentCardType": "visa",      // Card type (e.g., visa, mastercard, etc.)
  "Sid": "PKxxxx",                // Payment session ID
  "PaymentConfirmationCode": "ch_a9dc6297cd1a4fb095e61b1a9cf2dd1d",
  "CallSid": "CAxxxxx",           // Call ID
  "Result": "success",            // Payment result
  "AccountSid": "AC75xxxxxx",     // Account ID  
  "DateCreated": "2021-08-10T03:55:53.408Z",
  "ChargeAmount": "9.99"
}

Logging Architecture

All utility classes inherit from EventEmitter and define a unified logging event interface:

interface LogEvent {
    timestamp: string;
    level: 'info' | 'error' | 'debug';
    message: string;
    context?: object;
}

Logging emitter implementation:

class Logger extends EventEmitter {
    log(level: 'info' | 'error' | 'debug', message: string, context?: object): void {
        const event: LogEvent = {
            timestamp: new Date().toISOString(),
            level,
            message,
            context
        };
        this.emit('log', event);
    }
}

MCP Protocol Compatibility

The plugin implements the following MCP standard interfaces:

• startPaymentCapture
• captureCardNumber
• captureSecurityCode
• getPaymentStatus
• handlePaymentComplete

All operations notify the MCP manager via the event emitter.

📦 Installation

npm install twilio-mcp-server-plugin

💻 Usage Examples

Initialize the Plugin

import { StartPaymentCaptureTool } from 'twilio-mcp-server-plugin';

const params = {
    accountSid: process.env.TWILIO_ACCOUNT_SID,
    apiKey: process.env.TWILIO_API_KEY,
    apiSecretKey: process.env.TWILIO_API_SECRET_KEY
};

const paymentCapture = new StartPaymentCaptureTool(params);

Handle the Payment Process

async function handleVoiceCallStarted(callSid: string, amount: string) {
    try {
        const session = await paymentCapture.startPaymentCapture(callSid, amount);
        // Listen for subsequent voice interactions
    } catch (err) {
        console.error('Error starting payment capture:', err);
    }
}

⚠️ Important Note

1. All API calls require valid Twilio account credentials.
2. The payment process must be conducted in a trusted network environment.
3. Callback data needs to be properly handled and verified.
4. Ensure complete logging for easy troubleshooting.