dwolla-mcp

Model Context Protocol (MCP) Server for the Dwolla API.

Summary

Dwolla API: Dwolla API Documentation

🏦 About Dwolla & This MCP Server

This MCP server enables AI agents to retrieve and analyze data from Dwolla's payment platform using natural language. It provides read-only access to Dwolla's comprehensive payment infrastructure, allowing you to inspect accounts, analyze transfer history, monitor customer data, and generate insights from your payment operations.

💡 What You Can Do

• Account Monitoring - View account details, balances, and funding sources
• Customer Analytics - Analyze customer data, beneficial ownership, and compliance status
• Transfer Analysis - Examine transfer history, status, and failure reasons
• Mass Payment Insights - Review bulk payment operations and their items
• Compliance Reporting - Access documents, KBA sessions, and verification data
• Business Intelligence - Query exchange data, webhooks, and system events

⚠️ Current Scope

Read-Only Operations: This MCP server currently supports data retrieval and analysis only. It does not support creating customers, initiating transfers, or modifying account data at the moment. This makes it ideal for reporting, analytics, and monitoring workflows while maintaining security for sensitive payment operations.

🌍 Environment Support

• Sandbox Environment (https://api-sandbox.dwolla.com) - Perfect for development and testing
• Production Environment (https://api.dwolla.com) - Live payment data access

Table of Contents

• dwolla-mcp
  • 🏦 About Dwolla & This MCP Server
  • 🔑 Environment Setup & Authentication
  • Installation
  • 💬 Usage Examples & Business Applications
  • 🛠️ Available Operations
  • ❓ Troubleshooting
  • 🔒 Security Considerations
• Development
  • Contributions

🔑 Environment Setup & Authentication

Prerequisites

Before using the Dwolla MCP server, you'll need:

• Node.js 18+ and npm
• Dwolla Account (Sandbox Account Sign-up)
• Bearer Token generated using your API client credential sfrom your Dwolla application

Getting Your Bearer Token

1. Log in to your Dwolla Dashboard

   • Sandbox: https://dashboard-sandbox.dwolla.com
   • Production: https://dashboard.dwolla.com

2. Create or select your application

3. Generate a bearer token

4. Copy your bearer token

Environment Configuration

You will need to specify which environment you want to run the tools against:

Sandbox Environment (Recommended for testing):

--server sandbox

Production Environment (Live data):

--server prod

For local development and testing:

# Clone the repository
git clone https://github.com/dwolla/dwolla-mcp.git
cd dwolla-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run with your bearer token
node bin/mcp-server.js start --bearer-auth "your_token_here" --server "sandbox"

Installation

Install the MCP server as a Desktop Extension using the pre-built mcp-server.mcpb file:

Simply drag and drop the mcp-server.mcpb file onto Claude Desktop to install the extension.

The MCP bundle package includes the MCP server and all necessary configuration. Once installed, the server will be available without additional setup.

[!NOTE] MCP bundles provide a streamlined way to package and distribute MCP servers. Learn more about Desktop Extensions.

Or manually:

1. Open Cursor Settings
2. Select Tools and Integrations
3. Select New MCP Server
4. If the configuration file is empty paste the following JSON into the MCP Server Configuration:

{
  "command": "npx",
  "args": [
    "@dwolla/mcp-server",
    "start",
    "--server",
    "prod",
    "--bearer-auth",
    ""
  ]
}

claude mcp add DwollaMcp -- npx -y @dwolla/mcp-server start --server prod --bearer-auth 

gemini mcp add DwollaMcp -- npx -y @dwolla/mcp-server start --server prod --bearer-auth 

Refer to Official Windsurf documentation for latest information

1. Open Windsurf Settings
2. Select Cascade on left side menu
3. Click on Manage MCPs. (To Manage MCPs you should be signed in with a Windsurf Account)
4. Click on View raw config to open up the mcp configuration file.
5. If the configuration file is empty paste the full json

{
  "command": "npx",
  "args": [
    "@dwolla/mcp-server",
    "start",
    "--server",
    "prod",
    "--bearer-auth",
    ""
  ]
}

Or manually:

Refer to Official VS Code documentation for latest information

1. Open Command Palette
2. Search and open MCP: Open User Configuration. This should open mcp.json file
3. If the configuration file is empty paste the full json

{
  "command": "npx",
  "args": [
    "@dwolla/mcp-server",
    "start",
    "--server",
    "prod",
    "--bearer-auth",
    ""
  ]
}

npx @dwolla/mcp-server start --server prod --bearer-auth 

For a full list of server arguments, run:

npx @dwolla/mcp-server --help

💬 Usage Examples & Business Applications

🎧 Customer Support & Operations

Business Problem: Support teams need to quickly investigate customer issues and transfer failures.

Solutions with AI:

• "Find all failed transfers for customer [email protected] and explain why they failed"
• "Show me customer details for customer ID {id}"
• "List transfers for customer {id} in the last month"

📊 Financial Reconciliation & Reporting

Business Problem: Finance teams need automated reconciliation and reporting.

Solutions with AI:

• "Calculate total transfer volume for Q1 2024 and compare to Q4 2023"
• "Show me all pending transfers over $10,000"
• "What's the current balance of my Dwolla Balance funding source?"

⚖️ Compliance & Risk Management

Problem: Compliance teams need to monitor suspicious activity, verify customer information, and ensure regulatory compliance.

Solutions with AI:

• "List all customers missing required beneficial ownership information"
• "Find transfers over $50,000 in the last 30 days for regulatory reporting"
• "Which customers need additional identity documents to maintain compliance?"
• "Identify customers with multiple failed transfer attempts this month"

📈 Business Intelligence & Analytics

Problem: Business teams need insights into payment patterns, customer behavior, and platform performance.

Solutions with AI:

• "What's the average transfer amount by customer segment and how has it changed?"
• "How many new verified customers were added this quarter vs last quarter?"
• "Which funding source types have the highest failure rates and why?"
• "Show me customers with increasing transfer volumes who might need premium features"

👩‍💻 Developer Tools & Integration Support

Problem: Development teams need to debug integrations, test scenarios, and understand API behavior.

Solutions with AI:

• "Show me the exact webhook events and timeline for transfer {id}"
• "What are the most common transfer failure reasons this week and their causes?"
• "Find examples of customers using each funding source type for testing"
• "Analyze the verification process for business customers who got stuck"

🚨 Automated Monitoring & Alerting

Problem: Operations teams need proactive monitoring of system health and business metrics.

Solutions with AI:

• "Has our daily failed transfer rate exceeded 5% and what's causing the failures?"
• "Show me any unusual spikes in transfer volumes or patterns today"
• "Which customers have been stuck in verification states for over 30 days?"
• "Are there any funding sources experiencing higher than normal failure rates?"

💡 Real-World Workflow Example

Scenario: Support receives an escalation about failed payments

Traditional Process (45+ minutes):

1. Log into multiple dashboards
2. Look up customers across different systems
3. Check transfer history manually
4. Research failure codes in documentation
5. Escalate to engineering for analysis

With Dwolla MCP (5 minutes):

User: "We're seeing more transfer failures lately. Can you investigate?"

AI: "I'll analyze recent transfer failures for you."
→ Pulls transfer data with failed status
→ Groups by failure reasons
→ Identifies top failure patterns
→ Suggests specific customers to investigate
→ Recommends remediation steps

Result: "I found a 15% increase in 'insufficient funds' failures, 
primarily from 3 specific customers. Here are the details and 
recommended actions..."

Result: Issue identified and resolved in 5 minutes instead of 45+ minutes, with complete context for the support agent.

🛠️ Available Operations

The Dwolla MCP server provides the following tools for data retrieval and analysis:

Account Operations

• accounts-get - Retrieve account details and status
• accounts-funding-sources-list - List all funding sources for account
• accounts-transfers-list - List and search transfers for account
• accounts-mass-payments-list - List mass payments for account
• accounts-exchanges-list - List exchanges for account

Customer Management

• customers-list - List and search customers with filtering
• customers-get - Retrieve detailed customer information
• customers-funding-sources-list - List customer funding sources
• customers-transfers-list - List customer transfer history
• customers-mass-payments-list - List customer mass payments
• customers-documents-list - List customer documents
• customers-exchanges-list - List customer exchanges
• customers-beneficial-owners-list - List customer beneficial owners
• customers-list-available-connections - List available exchange connections

Transfer Operations

• transfers-get - Retrieve specific transfer details
• transfers-get-failure-reason - Get transfer failure analysis
• transfers-list-fees - List transfer fees and charges

Mass Payment Operations

• mass-payments-get - Retrieve mass payment details
• mass-payments-list-items - List items within a mass payment
• mass-payments-get-item - Retrieve specific mass payment item

Funding Source Operations

• funding-sources-get - Retrieve funding source details
• funding-sources-get-balance - Get funding source balance
• funding-sources-get-micro-deposits - Get micro-deposit verification details
• funding-sources-get-van-routing - Get Virtual Account Number routing info

Compliance & Documents

• documents-get - Retrieve document details
• beneficial-owners-get - Retrieve beneficial owner information
• beneficial-owners-get-ownership-status - Get beneficial ownership status
• beneficial-owners-documents-list - List beneficial owner documents
• kba-get-questions - Retrieve KBA (Knowledge-Based Authentication) questions

Exchange Operations

• exchanges-get - Retrieve exchange details
• exchange-partners-list - List available exchange partners
• exchange-sessions-get - Get exchange session information

Labels & Ledger

• labels-list-for-customer - List labels for customer
• labels-get - Retrieve label details
• labels-list-ledger-entries - List ledger entries
• labels-get-ledger-entry - Retrieve specific ledger entry
• labels-get-reallocation - Get label reallocation details

Webhooks & Events

• webhooks-get - Retrieve webhook details
• webhooks-list-retries - List webhook retry attempts
• webhook-subscriptions-list - List webhook subscriptions
• webhook-subscriptions-get - Get webhook subscription details
• webhook-subscriptions-list-webhooks - List webhooks for subscription
• events-list - List events
• events-get - Retrieve specific event details

Reference Data

• business-classifications-list - List business classifications
• business-classifications-get - Get business classification details
• root-get - API entry point for discovery

❓ Troubleshooting

🔧 Common Setup Issues

MCP Server Not Connecting

• Verify your bearer token is valid
• Check that Node.js 18+ is installed: node --version
• Ensure npm/npx is available: npm --version
• Try clearing npm cache: npm cache clean --force

Environment Configuration Issues

• Confirm you're using the correct environment URL:
  • Sandbox: https://api-sandbox.dwolla.com
  • Production: https://api.dwolla.com
• Verify your bearer token matches your intended environment

Authentication Errors

• Verify token hasn't expired
• Check that your application is active

🖥️ Client-Specific Issues

Claude Desktop

• Restart Claude Desktop after configuration changes
• Check claude_desktop_config.json syntax with a JSON validator
• Verify file paths are absolute and properly escaped
• Look for error messages in Claude's developer console

Cursor

• Restart Cursor after adding MCP configuration
• Check Settings → Cursor Settings → MCP for configuration status
• Verify the server appears in the MCP tools list
• Try removing and re-adding the server configuration

VS Code

• Ensure GitHub Copilot extension is installed and active
• Check that MCP support is enabled in settings
• Restart VS Code after configuration changes
• Verify the MCP server appears in the agent tools list

🔍 Advanced Troubleshooting

Token Validation

# Test your bearer token directly
curl -H "Authorization: Bearer your_token_here" \
     https://api-sandbox.dwolla.com/

# Should return API root information

📊 Debugging Tips

Verbose Logging

• Check your MCP client's logs for detailed error messages
• Enable debug mode in your client if available
• Monitor network requests to identify API call failures

Test with MCP Inspector

• Use the MCP Inspector to test your server:

  npx @modelcontextprotocol/inspector npx -y --package @dwolla/mcp-server -- mcp start --bearer-auth "your_token" --server "sandbox"

💡 Performance Optimization

Large Dataset Queries

• Use specific date ranges when querying transfers or events
• Consider filtering by customer or status to reduce response size

🆘 Getting Help

• Documentation: Dwolla API Docs
• Community Support: Developer Forum
• Dwolla Support: Dwolla Developer Support
• MCP Protocol: Model Context Protocol Docs
• GitHub Issues: Report bugs or request features in this repository

🔒 Security Considerations

Important: This MCP server can provide access to sensitive financial data and systems. Following these security best practices is essential to protect your information, maintain data integrity and ensure compliance.

🛡️ Authentication Security

Bearer Token Management

• Never commit bearer tokens to version control
• Use environment variables for token storage

Environment Separation

• Always start with Sandbox for development and testing
• Use separate tokens for sandbox and production environments
• Never use production tokens in development/testing

Development

Contributions

While we value contributions to this MCP Server, the code is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.