> ## Documentation Index
> Fetch the complete documentation index at: https://dodopayments-mintlify-external-integration-datafast-autosen.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Enable AI assistants to interact with the Dodo Payments API through the Model Context Protocol (MCP) for seamless payment operations, subscription management, and customer interactions.

## Overview

The Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect to external data sources and APIs. The Dodo Payments MCP Server provides AI assistants like Claude, Cursor, and other MCP-compatible clients with structured access to your payment infrastructure.

### Key capabilities

* **Payment Operations**: Create, retrieve, and manage payments and refunds
* **Subscription Management**: Handle recurring billing, upgrades, and cancellations
* **Customer Administration**: Manage customer data and portal access
* **Product Catalog**: Create and update products, pricing, and discounts
* **License Management**: Activate, validate, and manage software licenses
* **Usage-Based Billing**: Track and bill for metered usage

## Installation

Choose the installation method that best fits your workflow.

### Remote MCP Server (Recommended)

Access the hosted MCP server without any local setup or installation. This is the fastest way to get started.

<Frame>
  <iframe className="w-full aspect-video rounded-md" src="https://www.youtube.com/embed/TxGgYxNmkT4" title="Using Dodo Payment's Remote MCP Server" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</Frame>

<Steps>
  <Step title="Access the remote server">
    Navigate to [https://mcp.dodopayments.com](https://mcp.dodopayments.com) in your browser.
  </Step>

  <Step title="Configure your MCP client">
    Copy the provided JSON configuration for your specific client. For Cursor or Claude Desktop, add this to your MCP settings:

    ```json theme={null}
    {
      "mcpServers": {
        "dodopayments_api": {
          "command": "npx",
          "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
        }
      }
    }
    ```
  </Step>

  <Step title="Authenticate and configure">
    The OAuth flow will prompt you to:

    * Enter your Dodo Payments API key
    * Select your environment (test or live)
    * Choose your MCP client type

    <Warning>
      Keep your API key secure. Use test mode keys during development.
    </Warning>
  </Step>

  <Step title="Complete setup">
    Click **Login and Approve** to authorize the connection.

    <Check>
      Once connected, your AI assistant can interact with the Dodo Payments API on your behalf.
    </Check>
  </Step>
</Steps>

### NPM Package

Install and run the MCP server locally using NPM.

<Tabs>
  <Tab title="NPX (No Installation)">
    ```bash theme={null}
    # Set your API key
    export DODO_PAYMENTS_API_KEY="dodo_test_..."

    # Run the latest version
    npx -y dodopayments-mcp@latest
    ```
  </Tab>

  <Tab title="MCP Client Configuration">
    ```json theme={null}
    {
      "mcpServers": {
        "dodopayments_api": {
          "command": "npx",
          "args": ["-y", "dodopayments-mcp@latest"],
          "env": {
            "DODO_PAYMENTS_API_KEY": "dodo_test_..."
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  Use `@latest` to always pull the most recent version, or pin to a specific version like `@1.0.0` for stability.
</Tip>

### Docker

Run the MCP server in a containerized environment for consistent deployment.

<CodeGroup>
  ```bash Docker theme={null}
  # Pull the latest image
  docker pull ghcr.io/dodopayments/mcp:latest

  # Run the container
  docker run -e DODO_PAYMENTS_API_KEY="dodo_test_..." \
    -p 3000:3000 \
    ghcr.io/dodopayments/mcp:latest
  ```

  ```yaml Docker Compose theme={null}
  services:
    dodopayments-mcp:
      image: ghcr.io/dodopayments/mcp:latest
      environment:
        - DODO_PAYMENTS_API_KEY=dodo_test_...
      ports:
        - "3000:3000"
      restart: unless-stopped
  ```
</CodeGroup>

<Note>
  Docker images are available on [GitHub Container Registry](https://github.com/orgs/dodopayments/packages/container/package/mcp).
</Note>

## Client Configuration

Configure the Dodo Payments MCP server in your preferred AI client.

<Tabs>
  <Tab title="Cursor">
    Set up the Dodo Payments MCP server in Cursor to enable conversational access to your payments data.

    <Steps>
      <Step title="Open Cursor settings">
        Navigate to **Cursor Settings** > **Features** > **Model Context Protocol** or press `Cmd/Ctrl + Shift + P` and search for "MCP Settings".
      </Step>

      <Step title="Edit configuration">
        Click **Edit Config** to open the `mcp_config.json` file.
      </Step>

      <Step title="Add Dodo Payments configuration">
        Choose one of the following configurations:

        **Remote Server (Recommended)**

        ```json theme={null}
        {
          "mcpServers": {
            "dodopayments": {
              "command": "npx",
              "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
            }
          }
        }
        ```

        **Local NPX**

        ```json theme={null}
        {
          "mcpServers": {
            "dodopayments": {
              "command": "npx",
              "args": ["-y", "dodopayments-mcp@latest"],
              "env": {
                "DODO_PAYMENTS_API_KEY": "dodo_test_..."
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Save and restart">
        Save the configuration file and restart Cursor.

        <Check>
          Verify the connection by asking the AI assistant about your Dodo Payments data.
        </Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Desktop">
    Set up the Dodo Payments MCP server in Claude Desktop to enable conversational access to your payments data.

    <Steps>
      <Step title="Locate configuration file">
        Find the Claude Desktop configuration file:

        * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
        * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
        * **Linux**: `~/.config/Claude/claude_desktop_config.json`
      </Step>

      <Step title="Edit configuration">
        Open the file in a text editor and add the Dodo Payments configuration:

        **Remote Server (Recommended)**

        ```json theme={null}
        {
          "mcpServers": {
            "dodopayments": {
              "command": "npx",
              "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
            }
          }
        }
        ```

        **Local NPX**

        ```json theme={null}
        {
          "mcpServers": {
            "dodopayments": {
              "command": "npx",
              "args": ["-y", "dodopayments-mcp@latest"],
              "env": {
                "DODO_PAYMENTS_API_KEY": "dodo_test_..."
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Restart Claude Desktop">
        Close and reopen Claude Desktop for the changes to take effect.

        <Tip>
          Look for the 🔌 icon in Claude Desktop to confirm the MCP server is connected.
        </Tip>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cline (VS Code)">
    Set up the Dodo Payments MCP server in Cline (VS Code) to enable conversational access to your payments data.

    <Steps>
      <Step title="Open Cline settings">
        Locate the Cline configuration file:

        * **macOS**: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
        * **Windows**: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
        * **Linux**: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
      </Step>

      <Step title="Configure MCP server">
        Add the Dodo Payments MCP server configuration:

        ```json theme={null}
        {
          "mcpServers": {
            "dodopayments": {
              "command": "npx",
              "args": ["-y", "dodopayments-mcp@latest"],
              "env": {
                "DODO_PAYMENTS_API_KEY": "dodo_test_..."
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Reload VS Code">
        Reload the VS Code window (`Cmd/Ctrl + Shift + P` > "Reload Window") to activate the MCP server connection.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Zed">
    Set up the Dodo Payments MCP server in Zed to enable conversational access to your payments data.

    <Steps>
      <Step title="Open Zed settings">
        Navigate to **Settings** > **Assistant** > **Model Context Protocol**.
      </Step>

      <Step title="Add server configuration">
        Add the following configuration:

        ```json theme={null}
        {
          "mcpServers": {
            "dodopayments": {
              "command": "npx",
              "args": ["-y", "dodopayments-mcp@latest"],
              "env": {
                "DODO_PAYMENTS_API_KEY": "dodo_test_..."
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Save and verify">
        Save the configuration. The MCP server should now be available in Zed's AI assistant.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Other Clients">
    Set up the Dodo Payments MCP server in other MCP-compatible clients to enable conversational access to your payments data.

    **Remote Server (Recommended)**

    ```json theme={null}
    {
      "mcpServers": {
        "dodopayments": {
          "command": "npx",
          "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
        }
      }
    }
    ```

    **Local NPX**

    ```json theme={null}
    {
      "mcpServers": {
        "dodopayments": {
          "command": "npx",
          "args": ["-y", "dodopayments-mcp@latest"],
          "env": {
            "DODO_PAYMENTS_API_KEY": "dodo_test_..."
          }
        }
      }
    }
    ```

    <Info>
      Visit [modelcontextprotocol.io/clients](https://modelcontextprotocol.io/clients) for a complete list of MCP-compatible clients and their configuration methods.
    </Info>
  </Tab>
</Tabs>

## Tool Filtering

Control which API operations are exposed to your AI assistant to optimize performance and maintain security.

### Filter by operation type

Restrict access to read-only or write operations.

```bash theme={null}
# Only expose read operations (GET requests)
npx dodopayments-mcp --operation=read

# Only expose write operations (POST, PUT, DELETE)
npx dodopayments-mcp --operation=write
```

<Tip>
  Use `--operation=read` during development to prevent accidental modifications to your data.
</Tip>

### Filter by resource

Limit tools to specific API resources.

```bash theme={null}
# Only expose payment-related tools
npx dodopayments-mcp --resource=payments

# Expose multiple resources
npx dodopayments-mcp --resource=payments --resource=customers
```

### Include or exclude specific tools

Fine-tune which individual tools are available.

```bash theme={null}
# Include only specific tools
npx dodopayments-mcp --tool=create_payments --tool=list_payments

# Exclude specific tools
npx dodopayments-mcp --no-tool=delete_products

# List all available tools
npx dodopayments-mcp --list
```

### Combine filters

Apply multiple filters simultaneously for precise control.

```bash theme={null}
# Only payment and subscription read operations
npx dodopayments-mcp --operation=read --resource=payments --resource=subscriptions
```

## Advanced Usage

### Programmatic integration

Build custom MCP servers or extend the existing one programmatically.

```javascript theme={null}
import { server, endpoints, init } from "dodopayments-mcp/server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Initialize with all default endpoints
init({ server, endpoints });

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);
```

### Custom tool development

Extend the MCP server with your own tools and business logic.

```javascript theme={null}
import { server, init } from "dodopayments-mcp/server";
import createPayments from "dodopayments-mcp/tools/payments/create-payments";
import { zodToJsonSchema } from "zod-to-json-schema";
import { z } from "zod";

// Define a custom tool
const customTool = {
  tool: {
    name: 'calculate_payment_total',
    description: 'Calculate payment total with tax and fees',
    inputSchema: zodToJsonSchema(
      z.object({
        amount: z.number().describe('Base amount in cents'),
        tax_rate: z.number().describe('Tax rate as decimal'),
      })
    ),
  },
  handler: async (client, args) => {
    const total = args.amount * (1 + args.tax_rate);
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ total, currency: 'usd' }),
      }],
    };
  },
};

// Initialize with custom tools
init({ 
  server, 
  endpoints: [createPayments, customTool] 
});
```

## Security Best Practices

Protect your API credentials and maintain secure integrations.

<AccordionGroup>
  <Accordion title="API Key Management">
    **Never commit credentials to version control**

    Store API keys in environment variables or secure secret management systems.

    ```bash theme={null}
    # Use environment variables
    export DODO_PAYMENTS_API_KEY="dodo_test_..."

    # Use a .env file (add to .gitignore)
    echo "DODO_PAYMENTS_API_KEY=dodo_test_..." > .env
    ```

    **Rotate keys regularly**

    Generate new API keys periodically and revoke old ones through your Dodo Payments dashboard.

    **Use test keys for development**

    Always use test mode API keys during development to avoid affecting production data.
  </Accordion>

  <Accordion title="Access Control">
    **Apply tool filtering in production**

    Limit exposed operations to only what your AI assistant needs.

    ```bash theme={null}
    # Production: read-only access
    npx dodopayments-mcp --operation=read

    # Development: full access
    npx dodopayments-mcp
    ```

    **Implement authentication for custom endpoints**

    Validate requests and enforce authorization in your custom tool handlers.

    **Monitor API usage**

    Track MCP server activity through your Dodo Payments dashboard and set up alerts for unusual patterns.
  </Accordion>

  <Accordion title="Network Security">
    **Use HTTPS for remote servers**

    Always deploy remote MCP servers behind HTTPS endpoints.

    **Implement rate limiting**

    Protect against abuse by implementing rate limits at both the MCP server and API levels.

    **Restrict network access**

    Configure firewall rules to limit which clients can connect to your MCP server.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection issues">
    **Verify your API key**

    Ensure your API key is correctly set and has the necessary permissions.

    ```bash theme={null}
    # Test your API key
    curl -H "Authorization: Bearer dodo_test_..." \
      https://api.dodopayments.com/payments
    ```

    **Check your network connection**

    Verify you can reach the Dodo Payments API endpoints.

    **Review client logs**

    Enable verbose logging in your MCP client to diagnose connection problems.
  </Accordion>

  <Accordion title="Authentication errors">
    **Confirm API key environment**

    Ensure you're using test keys with test endpoints and live keys with production endpoints.

    **Check key permissions**

    Verify your API key has permissions for the operations you're attempting.

    **Regenerate credentials**

    If issues persist, generate a new API key through your dashboard.
  </Accordion>

  <Accordion title="Tool execution failures">
    **Validate input parameters**

    Ensure the AI assistant is providing correctly formatted parameters for each tool.

    **Review error messages**

    Check the error response from the API for specific guidance on what went wrong.

    **Test with API directly**

    Verify the operation works when calling the Dodo Payments API directly via curl or Postman.
  </Accordion>
</AccordionGroup>

## Resources

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore the complete Dodo Payments API documentation
  </Card>

  <Card title="MCP Protocol" icon="link" href="https://modelcontextprotocol.io">
    Learn more about the Model Context Protocol standard
  </Card>
</CardGroup>