deshartman twilio agent payments mcp server

WHAT IT CONNECTS

What deshartman twilio agent payments mcp server gives an AI Agent

• Process secure payments during voice calls via Twilio
• Capture payment information (card number, security code, expiration date)
• Tokenize payment information for PCI compliance
• Asynchronous callbacks via MCP Resources
• Guided workflow with MCP Prompts for each step of the payment process
• Support for re-entry of payment information
• Integrates with MCP clients like Claude Desktop
• Secure credential handling
• Uses Twilio API Keys for improved security
• Event-based logging architecture
• **Command-line arguments** (required):
• `accountSid`: Your Twilio Account SID
• `apiKey`: Your Twilio API Key
• `apiSecret`: Your Twilio API Secret
• **Environment variables** (set before running the server):
• `TOKEN_TYPE`: Type of token to use for payments (e.g., 'reusable', 'one-time')
• `CURRENCY`: Currency for payments (e.g., 'USD', 'EUR')
• `PAYMENT_CONNECTOR`: Payment connector to use with Twilio
• `NGROK_AUTH_TOKEN`: Your Ngrok authentication token (required for callback handling)
• `NGROK_CUSTOM_DOMAIN`: Optional custom domain for Ngrok
• `accountSid`: Your Twilio Account SID (must start with 'AC', will be validated)
• `apiKey`: Your Twilio API Key (starts with 'SK')
• `apiSecret`: Your Twilio API Secret
• `TOKEN_TYPE`: Type of token to use for payments (e.g., 'reusable', 'one-time')
• `CURRENCY`: Currency for payments (e.g., 'USD', 'EUR')
• `PAYMENT_CONNECTOR`: Payment connector to use with Twilio
• `NGROK_AUTH_TOKEN`: Your Ngrok authentication token (required for callback handling)
• `NGROK_CUSTOM_DOMAIN`: Optional custom domain for Ngrok
• **Implement an MCP Client**: Use an existing MCP client library or implement the MCP client protocol in your application.
• **Connect to the MCP Server**: Configure your application to connect to the Twilio Agent Payments MCP server.
• **Let the Protocol Handle the Rest**: The MCP server will automatically:
• Register its tools and resources with your client
• Provide input schemas for all tools
• Supply contextual prompts to guide the LLM through the payment flow
• **src/index.ts**: The main entry point that:
• Initializes the MCP server
• Initializes the TwilioAgentPaymentServer singleton
• Discovers and registers all components with the MCP server via auto-discovery
• Sets up event listeners for logging
• Connects the server to the transport layer
• **src/tools/**: Contains individual tool implementations
• Each tool is implemented as a factory function that returns an object with name, description, shape, and execute properties
• Tools handle specific payment operations (e.g., StartPaymentCaptureTool, CaptureCardNumberTool)
• Each tool defines its input schema using Zod and implements an execute method
• Tools access the TwilioAgentPaymentServer singleton via getInstance()
• **src/prompts/**: Contains prompt implementations
• Each prompt is implemented as a factory function that returns an object with name, description, and execute properties
• Prompts provide contextual guidance to the LLM for each step of the payment flow
• Some prompts accept parameters that can be used to customize the prompt content
• **src/resources/**: Contains resource implementations
• Resources provide access to data (e.g., PaymentStatusResource)
• Each resource is implemented as a factory function that returns an object with name, template, description, and read properties
• Resources access the TwilioAgentPaymentServer singleton via getInstance()
• **src/api-servers/**: Contains the implementation of the Twilio API client
• Implements the TwilioAgentPaymentServer as a singleton
• Handles communication with the Twilio API
• Manages payment session state
• Provides static methods for accessing the singleton instance
• **src/utils/**: Contains utility functions
• The autoDiscovery.ts file handles automatic discovery and registration of tools, prompts, and resources
• Static method to get the instance
• Static method to initialize the instance
• Ensures there's only one instance of TwilioAgentPaymentServer throughout the application
• Eliminates the need to pass the instance through multiple functions
• Provides a cleaner API with simpler function signatures
• Makes it easier to access the TwilioAgentPaymentServer from anywhere in the codebase
• **In Tools**:
• **In Resources**:
• **In Prompts**:
• Automatically finds all tools, prompts, and resources in their respective directories
• Dynamically imports and registers them with the MCP server
• Makes it easy to add new components without modifying the main file
• Reduces boilerplate code and improves maintainability
• **Parameter Definition**:
• The schema property defines the parameter schema using Zod
• In this case, it requires a `callSid` parameter of type string
• **Parameter Usage in the Prompt**:
• The execute method accepts the parameters as its first argument
• It can validate the parameters and use them to customize the prompt content
• In this case, the callSid is used in the prompt text to provide context
• `callSid`: The Twilio Call SID for the active call
• `paymentSid`: The Twilio Payment SID for the new payment session
• `callSid`: The Twilio Call SID for the active call
• `paymentSid`: The Twilio Payment SID for the payment session
• `captureType`: Set to 'payment-card-number'
• Status of the card number capture operation
• `callSid`: The Twilio Call SID for the active call
• `paymentSid`: The Twilio Payment SID for the payment session
• `captureType`: Set to 'security-code'
• Status of the security code capture operation
• `callSid`: The Twilio Call SID for the active call
• `paymentSid`: The Twilio Payment SID for the payment session
• `captureType`: Set to 'expiration-date'
• Status of the expiration date capture operation
• `callSid`: The Twilio Call SID for the active call
• `paymentSid`: The Twilio Payment SID for the payment session
• Status of the payment completion operation
• Payment SID
• Payment card number (masked)
• Payment card type
• Security code status
• Expiration date
• Payment confirmation code
• Payment result
• Payment token
• Instructions for asking the customer if they're ready to provide payment information
• Explanation of the secure processing and tokenization
• Steps to use the startPaymentCapture tool
• **IMPORTANT**: Requires the user to enter a Call SID from the MCP Client side, which is a mandatory parameter
• Instructions for explaining to the customer what information is needed
• Tips for handling customer questions or concerns
• Steps to use the captureCardNumber tool
• Instructions for explaining what the security code is
• Tips for handling customer questions or concerns
• Steps to use the captureSecurityCode tool
• Instructions for explaining the format needed (MM/YY)
• Tips for handling customer questions or concerns
• Steps to use the captureExpirationDate tool
• Instructions for confirming all information has been collected
• Steps to use the completePaymentCapture tool
• Instructions for confirming the payment was successful
• Suggestions for next steps in the conversation
• Instructions for explaining the error to the customer
• Suggestions for troubleshooting common issues
• Steps to retry the payment capture process
• Each tool, resource, and server component extends EventEmitter
• Components emit events for logging and callbacks
• Event listeners forward logs to the MCP server's logging system
• Creates a secure tunnel using Ngrok for receiving callbacks
• Processes callbacks for different payment stages
• Updates the state store based on callback data
• Handles error conditions and re-entry scenarios
• The statusCallbackMap stores payment session data indexed by payment SID
• Each callback updates the state with the latest information
• The PaymentStatusResource provides access to this state data
• Tools: Defined with Zod schemas for input validation
• Resources: Providing access to payment state data
• Prompts: Contextual guidance for each step of the payment flow
• Logging: Event-based logging forwarded to the MCP server
• Node.js 18+
• Express (for callback handling)
• Twilio SDK
• Ngrok account with auth token
• Use the event-based logging system by emitting LOG_EVENT events
• Avoid using `console.log()` as it will interfere with the MCP protocol's JSON messages on stdout
• For debugging outside the MCP context, you can use `console.error()` which outputs to stderr
• **Event Emitters**: All tool and resource classes extend Node.js's `EventEmitter` and emit 'log' events with level and message data.
• **Log Forwarding**: These events are captured by event listeners and forwarded to the MCP server's logging system:
• **MCP Integration**: The `logToMcp` function transforms these events into MCP-compatible log messages:
• `info`: General information messages
• `error`: Error messages and exceptions
• `debug`: Detailed debugging information
• `warn`: Warning messages (automatically converted to 'info' for MCP compatibility)