> ## Documentation Index
> Fetch the complete documentation index at: https://developers.dwolla.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol

> Learn how to use the Dwolla MCP Server to enable AI agents to retrieve and analyze data from Dwolla's payment platform using natural language.

The Dwolla Model Context Protocol (MCP) Server enables AI agents to retrieve and analyze data from the Dwolla payment platform using natural language. It provides read-only access to inspect accounts, analyze transfer history, monitor customer data, and generate insights from your payment operations.

Unlike a traditional REST API, the MCP Server is designed for AI inference, allowing you to ask questions and get insights from your Dwolla data conversationally.

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dwolla/dwolla-mcp">
    View the full README, report issues, and explore the source code on GitHub.
  </Card>

  <Card title="MCP Protocol" icon="book-open" href="https://modelcontextprotocol.io">
    Learn more about the Model Context Protocol that powers this server.
  </Card>
</CardGroup>

## Use Cases

Leverage the MCP Server to build AI-powered workflows for various business needs:

<AccordionGroup>
  <Accordion title="Customer Support & Operations">
    Quickly investigate customer issues and transfer failures.

    * *"Find all failed transfers for customer `jane.doe@example.com` and explain why they failed."*
    * *"Show me customer details for customer ID `62c3aa1b-3a1b-46d0-ae90-17304d60c3d5`."*
  </Accordion>

  <Accordion title="Financial Reconciliation & Reporting">
    Automate reconciliation and reporting tasks.

    * *"Calculate total transfer volume for last quarter."*
    * *"Show me all pending transfers over \$5,000 this week."*
  </Accordion>

  <Accordion title="Compliance & Risk Management">
    Monitor for suspicious activity and ensure regulatory compliance.

    * *"List all customers missing required beneficial ownership information."*
    * *"Identify customers with multiple failed transfers this month."*
  </Accordion>

  <Accordion title="Business Intelligence & Analytics">
    Gain insights into payment patterns and customer behavior.

    * *"What's the average transfer amount by customer segment?"*
    * *"Which funding source types have the highest failure rates?"*
  </Accordion>
</AccordionGroup>

## Getting Started

Follow these steps to set up and run the Dwolla MCP Server.

### Prerequisites

Before you begin, ensure you have the following:

* **Node.js v18+ and npm**: The server is a Node.js application.
* **Dwolla Account**: You'll need a Dwolla account to generate API credentials. A [Sandbox Account](https://accounts-sandbox.dwolla.com/sign-up) is recommended for development.
* **Access Token**: An access token from your Dwolla application is required for authentication.

### Setup and Configuration

<Steps>
  <Step title="Generate an Access Token">
    All access tokens are short-lived and expire after one hour. The primary way to generate a token is to programmatically exchange your application's key and secret. This method works for both Sandbox and Production. For full details, see our API reference on [creating an application access token](/docs/api-reference/tokens/create-an-application-access-token).

    For convenience during development, the **Sandbox** environment also allows you to generate a token directly from the Applications tab in the [Sandbox Dashboard](https://dashboard-sandbox.dwolla.com/applications-legacy).

    <Warning>
      Treat your application key, secret, and tokens like passwords. Do not commit them to version control. Use environment variables or a secret manager.
    </Warning>
  </Step>

  <Step title="Choose Your Environment">
    You must specify which Dwolla environment the MCP server should interact with. Use the `--server-url` argument when starting the server.

    * **Sandbox (Recommended for testing):** `--server-url https://api-sandbox.dwolla.com`
    * **Production (Live data):** `--server-url https://api.dwolla.com`
  </Step>

  <Step title="Install and Run the Server">
    You can run the server directly using `npx`, or install it in your preferred AI-powered development tool.

    <Tabs>
      <Tab title="Claude Desktop (DXT)">
        **Recommended**: Install the MCP server as a Desktop Extension using the pre-built `mcp-server.dxt` file.

        1. Download the `mcp-server.dxt` file from the [GitHub repo](https://github.com/Dwolla/dwolla-mcp/blob/main/mcp-server.dxt).
        2. Simply drag and drop the `mcp-server.dxt` file onto Claude Desktop to install the extension.
        3. The DXT package includes the MCP server and all necessary configuration. Once installed, the server will be available without additional setup.

        <Note>
          DXT (Desktop Extensions) provide a streamlined way to package and distribute MCP servers. Learn more about [Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions).
        </Note>
      </Tab>

      <Tab title="Claude Desktop (Local Build)">
        If you prefer to run from source or the DXT method doesn't work, you can run the MCP server locally by cloning this repository.

        1. Clone the repository and set it up locally:
           ```bash theme={"dark"}
           git clone https://github.com/dwolla/dwolla-mcp.git
           cd dwolla-mcp
           npm install
           npm run build
           ```

        2. Open Claude Desktop and go to `Settings > Developer > Edit Config`.

        3. Add the following server configuration to `claude_desktop_config.json`, replacing the path with your local clone location:

        ```json theme={"dark"}
        {
          "mcpServers": {
            "DwollaMcp": {
              "type": "stdio",
              "command": "node",
              "args": [
                "/path/to/your/dwolla-mcp/bin/mcp-server.js",
                "start",
                "--bearer-auth",
                "your_token_here",
                "--server-url",
                "https://api-sandbox.dwolla.com"
              ]
            }
          }
        }
        ```

        4. Save and restart Claude Desktop.
      </Tab>

      <Tab title="Cursor">
        1. Open `Settings > Tools & Integrations`.
        2. Select `New MCP Server`.
        3. Paste the following JSON configuration, replacing `your_token_here`.

        ```json theme={"dark"}
        {
          "mcpServers": {
            "DwollaMcp": {
              "command": "npx",
              "args": [
                "@dwolla/mcp-server",
                "start",
                "--bearer-auth",
                "your_token_here",
                "--server-url",
                "https://api-sandbox.dwolla.com"
              ]
            }
          }
        }
        ```
      </Tab>

      <Tab title="VS Code">
        1. Open `Settings` (`Cmd + ,`) and search for "mcp".
        2. In your `settings.json`, add the following server configuration.
        3. Restart VS Code after saving.

        ```json theme={"dark"}
        {
          "mcp": {
            "servers": {
              "dwolla": {
                "type": "stdio",
                "command": "npx",
                "args": [
                  "@dwolla/mcp-server",
                  "start",
                  "--bearer-auth",
                  "your_token_here",
                  "--server-url",
                  "https://api-sandbox.dwolla.com"
                ]
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Local Development">
        For contributing or running from source:

        ```bash theme={"dark"}
        # 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 access token
        node bin/mcp-server.js start --bearer-auth "your_token_here" --server-url https://api-sandbox.dwolla.com
        ```
      </Tab>

      <Tab title="Terminal / CLI">
        Run the following command, replacing `your_token_here` with your bearer token.

        ```bash theme={"dark"}
        npx @dwolla/mcp-server start \
          --bearer-auth your_token_here \
          --server-url https://api-sandbox.dwolla.com
        ```

        For a full list of server arguments, run `npx @dwolla/mcp-server start --help`.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Available Operations (Tools)

The MCP Server exposes functionalities as "tools" that an AI agent can discover and invoke.

<Info>
  **Read-Only Operations**: All tools provided by this server are for data retrieval and analysis only. Creating, updating, or deleting data (e.g., initiating transfers or creating customers) is not currently supported.
</Info>

For a complete and up-to-date list of available tools, consult the [project README](https://github.com/Dwolla/dwolla-mcp/blob/main/README.md#%EF%B8%8F-available-operations).

Here is a summary of available tool categories:

* **Account Operations**: Retrieve account details, funding sources, transfers, etc.
* **Customer Management**: List, search, and get details for customers and their associated resources.
* **Transfer Operations**: Get details for specific transfers and their fees or failure reasons.
* **Mass Payment Operations**: Retrieve details about mass payments and their individual items.
* **Funding Source Operations**: Get details for specific funding sources, including balance or micro-deposit status.
* **Compliance & Documents**: Access documents and information related to beneficial ownership and KBA.
* **Exchange Operations**: Retrieve details about exchanges, partners, and sessions.
* **Labels & Ledger**: Manage and query labels and ledger entries.
* **Webhooks & Events**: Get details about webhooks, subscriptions, and events.
* **Reference Data**: List business classifications.

<Tip>
  When using an AI agent framework, it will automatically discover the available tools from the server. You can then ask the agent to list the tools it has available.
</Tip>

## Using with AI Agents

You can interact with the Dwolla MCP server through integrated AI-powered clients like Cursor, Claude, Windsurf, VS Code etc., which provide a conversational interface to your data. In our testing, Claude Pro has been particularly effective at using natural language prompts to access information from the Dwolla API via the MCP tools.

For developers who want to build their own custom AI applications or agents that communicate with the MCP server, using a framework like LangChain or Semantic Kernel is recommended. These frameworks simplify development by handling tool discovery, context management, and the underlying communication protocol.

### Example Workflow: Investigating Failed Payments

Here's how an AI-powered workflow with the MCP server can drastically reduce investigation time.

**Scenario**: A support agent needs to understand a recent spike in failed payments.

**Traditional Process (Manual)**

1. Log into multiple dashboards.
2. Manually look up customer and transfer data.
3. Cross-reference failure codes with documentation.
4. Potentially escalate to engineering for database queries.

**Time: \~45 minutes** 🐢

**AI-Powered Process (with MCP)**

1. Ask the AI agent: *"We're seeing more transfer failures lately. Can you investigate?"*
2. The agent uses the MCP server to analyze recent transfers, group them by failure reason, and identify patterns.
3. The agent provides a concise summary with actionable insights.

**Time: \~5 minutes** 🚀

## Troubleshooting

If you encounter issues, refer to the detailed [troubleshooting section in the README](https://github.com/Dwolla/dwolla-mcp/blob/main/README.md#-troubleshooting) on GitHub. Here are some common solutions:

<AccordionGroup>
  <Accordion title="MCP Server Not Connecting">
    * **Invalid Access Token**: Ensure your token is correct, has not expired, and matches the selected environment (Sandbox vs. Production).
    * **Node.js Version**: Verify you are using Node.js v18 or higher (`node --version`).
    * **NPM Cache**: Try clearing the npm cache with `npm cache clean --force`.
  </Accordion>

  <Accordion title="Client-Specific Issues">
    * **Restart the Client**: After making configuration changes in Cursor, or another client, a restart is often required.
    * **Check Configuration**: Double-check your JSON configuration for syntax errors.
  </Accordion>

  <Accordion title="Advanced Troubleshooting">
    * **Validate Token with cURL**: Test your token directly against the API.
      ```bash theme={"dark"}
      curl -H "Authorization: Bearer your_token_here" \
           https://api-sandbox.dwolla.com/
      ```
    * **Use MCP Inspector**: Test your server setup with the official MCP Inspector tool. See the [`README`](https://github.com/Dwolla/dwolla-mcp/blob/main/README.md) for instructions.
  </Accordion>
</AccordionGroup>