Integrations
Uses Express to handle asynchronous callbacks from Twilio, processing payment stage notifications and updating payment session state.
Built on Node.js, allowing the server to maintain in-memory state stores for payment sessions and handle the MCP protocol communication.
Enables handling agent-assisted payments via the Twilio API, allowing secure processing of payment card information (card number, security code, expiration date) during voice calls, with support for tokenization, payment status tracking, and field re-entry.
Twilio Agent Payments MCP Server
An MCP (Model Context Protocol) server that enables handling agent-assisted payments via the Twilio API, with enhanced features for asynchronous callbacks and guided workflow through contextual prompts.
Features
- 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
Installation
You can use this server directly via npx:
Or install it globally:
Environmental Parameters
When installing the server, you need to provide the following parameters:
- Command-line arguments (required):
accountSid
: Your Twilio Account SIDapiKey
: Your Twilio API KeyapiSecret
: 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 TwilioNGROK_AUTH_TOKEN
: Your Ngrok authentication token (required for callback handling)NGROK_CUSTOM_DOMAIN
: Optional custom domain for Ngrok
Example with environment variables:
See the Configuration section below for more details on these parameters.
Configuration
The server requires the following parameters:
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
Environment Variables
The following environment variables are used for configuration:
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 TwilioNGROK_AUTH_TOKEN
: Your Ngrok authentication token (required for callback handling)NGROK_CUSTOM_DOMAIN
: Optional custom domain for Ngrok
Note: Twilio credentials (accountSid, apiKey, apiSecret) are provided as command-line arguments, not environment variables.
Security Note
This server uses API Keys and Secrets instead of Auth Tokens for improved security. This approach provides better access control and the ability to revoke credentials if needed. For more information, see the Twilio API Keys documentation.
Usage with Claude Desktop
Local Development
For local development (when the package is not published to npm), add the following to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json
on macOS or %APPDATA%\Claude\claude_desktop_config.json
on Windows):
Replace the values with your actual Twilio credentials and configuration.
After Publishing to npm
Once the package is published to npm, you can use the following configuration:
Integration with Host Applications
One of the key advantages of the Model Context Protocol (MCP) is that it eliminates the need for extensive manual configuration of LLM context. The MCP server automatically provides all necessary tool definitions, resource templates, and capabilities to the LLM client.
Setting Up Your Host Application
To integrate this MCP server into your own host application:
- 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
No manual definition of tools or resources is required in your LLM's context - the MCP protocol handles this discovery automatically.
Example Integration Code
Here's a simplified example of how to integrate with an MCP client:
Minimal LLM Context Required
The LLM only needs to know that it can use the Twilio Agent Payments MCP server for handling payments. A simple instruction in your system prompt is sufficient:
The MCP server itself provides all the detailed tool definitions, input schemas, and contextual prompts to guide the LLM through the payment flow.
Developer Implementation Notes
This section explains how the MCP server implementation is organized across different components and files, focusing on the architecture patterns used.
Component Organization
The server implementation is split across several directories:
- 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
Singleton Pattern for TwilioAgentPaymentServer
A key architectural pattern in this codebase is the use of the Singleton pattern for the TwilioAgentPaymentServer:
Benefits of this approach:
- 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
Factory Function Pattern
Tools, prompts, and resources are implemented using the factory function pattern:
- In Tools: Copy
- In Resources:Copy
- In Prompts:Copy
Auto-Discovery and Registration
The server uses an auto-discovery mechanism to find and register all components:
This approach:
- 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
Parameters in Prompts
Some prompts accept parameters that can be used to customize the prompt content. The StartCapturePrompt is a good example:
- Parameter Definition:Copy
- 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:Copy
- 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
This pattern allows prompts to be dynamic and contextual, providing tailored guidance based on the current state of the payment flow.
Available Tools
startPaymentCapture
Initiates a payment capture process for an active call.
Parameters:
callSid
: The Twilio Call SID for the active call
IMPORTANT: The StartCapturePrompt.ts requires the user to enter a Call SID from the MCP Client side. This is a required parameter and the prompt will throw an error if it's not provided.
NOTE: When handling Twilio calls, you need to understand which call leg Call SID you are working with. Twilio Payments need to be attached to the PSTN side call leg. If applied to the Twilio Client side, the DTMF digits will not be captured. As such this MCP Server assumes the correct call leg is being used. Typically it is checked as below:
Returns:
paymentSid
: The Twilio Payment SID for the new payment session
captureCardNumber
Starts the capture of the payment card number.
Parameters:
callSid
: The Twilio Call SID for the active callpaymentSid
: The Twilio Payment SID for the payment sessioncaptureType
: Set to 'payment-card-number'
Returns:
- Status of the card number capture operation
captureSecurityCode
Starts the capture of the card security code.
Parameters:
callSid
: The Twilio Call SID for the active callpaymentSid
: The Twilio Payment SID for the payment sessioncaptureType
: Set to 'security-code'
Returns:
- Status of the security code capture operation
captureExpirationDate
Starts the capture of the card expiration date.
Parameters:
callSid
: The Twilio Call SID for the active callpaymentSid
: The Twilio Payment SID for the payment sessioncaptureType
: Set to 'expiration-date'
Returns:
- Status of the expiration date capture operation
completePaymentCapture
Completes a payment capture session.
Parameters:
callSid
: The Twilio Call SID for the active callpaymentSid
: The Twilio Payment SID for the payment session
Returns:
- Status of the payment completion operation
Available Resources
payment://{callSid}/{paymentSid}/status
Get the current status of a payment session as a JSON object. This resource provides detailed information about the current state of the payment capture process, including:
- Payment SID
- Payment card number (masked)
- Payment card type
- Security code status
- Expiration date
- Payment confirmation code
- Payment result
- Payment token
MCP Prompts
The server provides contextual prompts to guide the LLM through each step of the payment flow:
StartCapture Prompt
Provides guidance on how to initiate the payment capture process, including:
- 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
CardNumber Prompt
Guides the LLM on how to handle the card number capture process, including:
- Instructions for explaining to the customer what information is needed
- Tips for handling customer questions or concerns
- Steps to use the captureCardNumber tool
SecurityCode Prompt
Provides guidance on capturing the card security code, including:
- Instructions for explaining what the security code is
- Tips for handling customer questions or concerns
- Steps to use the captureSecurityCode tool
ExpirationDate Prompt
Guides the LLM on capturing the card expiration date, including:
- Instructions for explaining the format needed (MM/YY)
- Tips for handling customer questions or concerns
- Steps to use the captureExpirationDate tool
FinishCapture Prompt
Provides guidance on completing the payment capture process, including:
- Instructions for confirming all information has been collected
- Steps to use the completePaymentCapture tool
Completion Prompt
Guides the LLM on what to do after the payment has been successfully processed, including:
- Instructions for confirming the payment was successful
- Suggestions for next steps in the conversation
Error Prompt
Provides guidance on handling errors during the payment capture process, including:
- Instructions for explaining the error to the customer
- Suggestions for troubleshooting common issues
- Steps to retry the payment capture process
Architecture
This MCP server implements an enhanced architecture for handling payment flows:
Event-Based Architecture
The server uses an event-based architecture with EventEmitter for communication between components:
- 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
Callback Handling
The server uses the @deshartman/mcp-status-callback package to handle asynchronous callbacks from Twilio:
- 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
State Management
Payment state is managed through a Map-based store:
- 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
MCP Integration
The server integrates with the MCP protocol through:
- 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
Development
To build the project:
Prerequisites
- Node.js 18+
- Express (for callback handling)
- Twilio SDK
- Ngrok account with auth token
Running the Server Manually
To start the server manually for testing (outside of Claude Desktop):
The server will start and wait for MCP client connections.
When using with Claude Desktop, the server is started automatically when Claude loads the configuration file. You don't need to manually start it.
PCI Compliance
This server helps with PCI compliance by tokenizing payment card information. The actual card data is handled by Twilio and never stored in your system. For more information on Twilio's PCI compliance, see the Twilio documentation on secure payments.
License
MIT
MCP Inspector Compatibility
When using this server with the MCP Inspector, note that all logging is done via the MCP logging capability instead of console.log()
. This is intentional and necessary for compatibility with the MCP protocol, which uses stdout for JSON communication.
If you're extending this server or debugging issues:
- 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-Based Logging Architecture
The server uses an event-based logging architecture:
- 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:Copy
- MCP Integration: The
logToMcp
function transforms these events into MCP-compatible log messages:Copy
Supported Log Levels
The server supports the following log levels:
info
: General information messageserror
: Error messages and exceptionsdebug
: Detailed debugging informationwarn
: Warning messages (automatically converted to 'info' for MCP compatibility)
Payment Callback Data Structure
The server processes two main types of callback data from Twilio:
Initial Connector Data
When a payment session is first created, Twilio sends connector data:
Capture Data
As payment information is captured, Twilio sends updated data:
The server stores this data in the statusCallbackMap, indexed by the payment SID, and makes it available through the PaymentStatusResource.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
An MCP server that enables secure, PCI-compliant payment processing during voice calls via Twilio API, providing asynchronous callbacks and guided workflow for agent-assisted payments.
- Features
- Installation
- Configuration
- Usage with Claude Desktop
- Integration with Host Applications
- Developer Implementation Notes
- Available Tools
- Available Resources
- MCP Prompts
- Architecture
- Development
- PCI Compliance
- License
- MCP Inspector Compatibility
- Event-Based Logging Architecture
- Payment Callback Data Structure
Related MCP Servers
- AsecurityAlicenseAqualityThe Voyp MCP Server enables AI systems to integrate with VOYP's calling capabilities, allowing for secure telephony actions such as making calls, scheduling appointments, and tracking call statuses through the Model Context Protocol.Last updated -7114JavaScriptMIT License
- -securityFlicense-qualityAn MCP (Model Context Protocol) server that lets users send SMS messages through Twilio API directly from Claude Desktop via natural language commands.Last updated -1TypeScript
- -securityFlicense-qualityA server that connects Claude AI to Twilio through the Model Context Protocol, enabling prompt-assisted management of Twilio accounts, phone numbers, and regulatory compliance.Last updated -Python
- -securityFlicense-qualityAn MCP server that enables AI assistants to interact with Flutterwave payment services, providing tools for transaction management, payment link generation, and automated customer support.Last updated -TypeScript