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.

1. Access the remote server

   Navigate to https://mcp.dodopayments.com in your browser.

2. Configure your MCP client

   Copy the provided JSON configuration for your specific client. For Cursor or Claude Desktop, add this to your MCP settings:

   {
     "mcpServers": {
       "dodopayments_api": {
         "command": "npx",
         "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
       }
     }
   }
   
3. 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

   Keep your API key secure. Use test mode keys during development.

4. Complete setup

   Click Login and Approve to authorize the connection.

   Once connected, your AI assistant can interact with the Dodo Payments API on your behalf.

NPM Package

Install and run the MCP server locally using NPM.

NPX (No Installation)

# Set your API key
export DODO_PAYMENTS_API_KEY="dodo_test_..."

# Run the latest version
npx -y dodopayments-mcp@latest

MCP Client Configuration

{
  "mcpServers": {
    "dodopayments_api": {
      "command": "npx",
      "args": ["-y", "dodopayments-mcp@latest"],
      "env": {
        "DODO_PAYMENTS_API_KEY": "dodo_test_..."
      }
    }
  }
}

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

Docker

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

Docker

# 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

Docker images are available on GitHub Container Registry.

Client Configuration

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

Cursor

Set up the Dodo Payments MCP server in Cursor to enable conversational access to your payments data.

1. Open Cursor settings

   Navigate to Cursor Settings > Features > Model Context Protocol or press Cmd/Ctrl + Shift + P and search for “MCP Settings”.

2. Edit configuration

   Click Edit Config to open the mcp_config.json file.

3. Add Dodo Payments configuration

   Choose one of the following configurations:

   Remote Server (Recommended)

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

   Local NPX

   {
     "mcpServers": {
       "dodopayments": {
         "command": "npx",
         "args": ["-y", "dodopayments-mcp@latest"],
         "env": {
           "DODO_PAYMENTS_API_KEY": "dodo_test_..."
         }
       }
     }
   }
   
4. Save and restart

   Save the configuration file and restart Cursor.

   Verify the connection by asking the AI assistant about your Dodo Payments data.

Claude Desktop

Set up the Dodo Payments MCP server in Claude Desktop to enable conversational access to your payments data.

1. 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
2. Edit configuration

   Open the file in a text editor and add the Dodo Payments configuration:

   Remote Server (Recommended)

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

   Local NPX

   {
     "mcpServers": {
       "dodopayments": {
         "command": "npx",
         "args": ["-y", "dodopayments-mcp@latest"],
         "env": {
           "DODO_PAYMENTS_API_KEY": "dodo_test_..."
         }
       }
     }
   }
   
3. Restart Claude Desktop

   Close and reopen Claude Desktop for the changes to take effect.

   Look for the 🔌 icon in Claude Desktop to confirm the MCP server is connected.

Cline (VS Code)

Set up the Dodo Payments MCP server in Cline (VS Code) to enable conversational access to your payments data.

1. 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
2. Configure MCP server

   Add the Dodo Payments MCP server configuration:

   {
     "mcpServers": {
       "dodopayments": {
         "command": "npx",
         "args": ["-y", "dodopayments-mcp@latest"],
         "env": {
           "DODO_PAYMENTS_API_KEY": "dodo_test_..."
         }
       }
     }
   }
   
3. Reload VS Code

   Reload the VS Code window (Cmd/Ctrl + Shift + P > “Reload Window”) to activate the MCP server connection.

Zed

Set up the Dodo Payments MCP server in Zed to enable conversational access to your payments data.

1. Open Zed settings

   Navigate to Settings > Assistant > Model Context Protocol.

2. Add server configuration

   Add the following configuration:

   {
     "mcpServers": {
       "dodopayments": {
         "command": "npx",
         "args": ["-y", "dodopayments-mcp@latest"],
         "env": {
           "DODO_PAYMENTS_API_KEY": "dodo_test_..."
         }
       }
     }
   }
   
3. Save and verify

   Save the configuration. The MCP server should now be available in Zed’s AI assistant.

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)

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

Local NPX

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

Visit modelcontextprotocol.io/clients for a complete list of MCP-compatible clients and their configuration methods.

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.

# Only expose read operations (GET requests)
npx dodopayments-mcp --operation=read

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

Use --operation=read during development to prevent accidental modifications to your data.

Filter by resource

Limit tools to specific API resources.

# 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.

# 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.

# 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.

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.

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.

API Key Management

Never commit credentials to version control

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

# 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.

Access Control

Apply tool filtering in production

Limit exposed operations to only what your AI assistant needs.

# 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.

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.

Troubleshooting

Connection issues

Verify your API key

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

# 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.

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.

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.

Resources

API Reference

Explore the complete Dodo Payments API documentation

MCP Protocol

Learn more about the Model Context Protocol standard