MCP Server

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. The Dodo Payments MCP Server is built with Stainless and uses the Code Mode architecture, which enables AI agents to write and execute TypeScript code against the Dodo Payments SDK in an isolated sandbox environment.

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

How Code Mode Works

The Dodo Payments MCP Server uses Code Mode, providing your AI agent with two powerful tools:

Docs Search Tool: Query documentation about the Dodo Payments API and SDK to understand available operations and parameters
Code Execution Tool: Write TypeScript code against the SDK that executes in a secure sandbox environment without web or filesystem access

This architecture enables AI agents to perform complex, multi-step payment operations deterministically and repeatably.

Using Code Mode, agents can chain multiple API calls, handle conditional logic, and perform calculations—all in a single tool invocation.

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.

Access the remote server

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

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"]
    }
  }
}

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.

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)
MCP Client Configuration

# Set your environment variables
export DODO_PAYMENTS_API_KEY="dodo_test_..."
export DODO_PAYMENTS_WEBHOOK_KEY="your_webhook_key"
export DODO_PAYMENTS_ENVIRONMENT="live_mode"

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

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

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.

# Pull the latest image
docker pull ghcr.io/dodopayments/mcp:latest

# Run the container
docker run -e DODO_PAYMENTS_API_KEY="dodo_test_..." \
  -e DODO_PAYMENTS_WEBHOOK_KEY="your_webhook_key" \
  -e DODO_PAYMENTS_ENVIRONMENT="live_mode" \
  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.

Set up the Dodo Payments MCP server in Cursor to enable conversational access to your payments data.One-Click InstallUse the button below to install the MCP server directly in Cursor:

After clicking, set your environment variables in Cursor’s mcp.json via Cursor Settings > Tools & MCP > New MCP Server.Manual Configuration

Open Cursor settings

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

Edit configuration

Click Edit Config to open the mcp_config.json file.

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_...",
        "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key"
      }
    }
  }
}

Save and restart

Save the configuration file and restart Cursor.

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

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

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

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_...",
        "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key"
      }
    }
  }
}

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.

Set up the Dodo Payments MCP server in Claude Code CLI.Run the following command in your terminal:

claude mcp add --transport stdio dodopayments_api \
  --env DODO_PAYMENTS_API_KEY="dodo_test_..." \
  DODO_PAYMENTS_WEBHOOK_KEY="your_webhook_key" \
  -- npx -y dodopayments-mcp

The configuration will be stored in your home directory’s .claude.json file.

Claude Code automatically picks up environment variables from your shell, so you can also export them before running the command.

Set up the Dodo Payments MCP server in VS Code.One-Click InstallOpen VS CodeAfter clicking, set your environment variables in VS Code’s mcp.json via Command Palette > MCP: Open User Configuration.Manual Configuration

Open MCP configuration

Open the Command Palette (Cmd/Ctrl + Shift + P) and search for “MCP: Open User Configuration”.

Add server configuration

Add the Dodo Payments MCP server:

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

Reload window

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

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

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

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_...",
        "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key"
      }
    }
  }
}

Reload VS Code

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

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

Open Zed settings

Navigate to Settings > Assistant > Model Context Protocol.

Add server configuration

Add the following configuration:

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

Save and verify

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

Set up the Dodo Payments MCP server in other MCP-compatible clients.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_...",
        "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key"
      }
    }
  }
}

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

Environment Variables

Configure the MCP server behavior using environment variables.

Variable	Description	Required
`DODO_PAYMENTS_API_KEY`	Your Dodo Payments API key	Yes
`DODO_PAYMENTS_WEBHOOK_KEY`	Your webhook signing key	No
`DODO_PAYMENTS_ENVIRONMENT`	Set to `live_mode` for production	No

Running Remotely

Deploy the MCP server as a remote HTTP server for web-based clients or agentic workflows.

# Start as remote server
npx -y dodopayments-mcp --transport=http

# Specify a custom port
npx -y dodopayments-mcp --transport=http --port=3000

Remote Server Configuration

Once deployed, clients can connect using the server URL:

{
  "mcpServers": {
    "dodopayments_api": {
      "url": "http://localhost:3000",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    }
  }
}

Authorization Headers

The remote server accepts authentication via the following headers:

Header	Description
`Authorization`	Bearer token authentication
`x-dodo-payments-api-key`	Direct API key header

Client Capabilities

Different MCP clients have varying levels of support for the MCP specification. The server can automatically adjust tool schemas to work around these limitations.

# Auto-detect client (default)
npx dodopayments-mcp --client=infer

# Configure for specific clients
npx dodopayments-mcp --client=cursor
npx dodopayments-mcp --client=claude
npx dodopayments-mcp --client=claude-code
npx dodopayments-mcp --client=openai-agents

Available Client Presets

Client	Description
`infer`	Auto-detect client (default)
`cursor`	Cursor editor
`claude`	Claude AI web or desktop
`claude-code`	Claude Code CLI
`openai-agents`	OpenAI agents platform

Manual Capability Configuration

For clients not listed above, manually configure capabilities:

# Disable $ref pointer support and set max tool name length
npx dodopayments-mcp --no-capability=refs --capability=tool-name-length=40

Available capabilities:

top-level-unions - Support for top-level union types
valid-json - Correct JSON string argument parsing
refs - Support for $ref pointers in schemas
unions - Support for union types (anyOf)
formats - Support for format validations
tool-name-length=N - Maximum tool name length

Run npx dodopayments-mcp --describe-capabilities for detailed capability information.

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

# Use wildcards for resource groups
npx dodopayments-mcp --resource=subscription*

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

# Disable the docs search tool
npx dodopayments-mcp --no-tools=docs

# 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

URL Query Parameter Filtering (Remote Server)

When using the remote server, apply filters via URL query parameters:

https://mcp.dodopayments.com/?operation=read
https://mcp.dodopayments.com/?resource=payments

Dynamic Tools Mode

For large APIs, loading all tools at once can overwhelm the AI’s context window. Dynamic tools mode provides a more efficient alternative.

npx dodopayments-mcp --tools=dynamic

In dynamic mode, three meta-tools replace individual API tools:

list_api_endpoints - Discovers available methods with optional filtering
get_api_endpoint_schema - Gets detailed schema for a specific method
invoke_api_endpoint - Executes any method with appropriate parameters

Dynamic tools are automatically enabled for APIs with more than 50 methods. Override with --tools=all to include all tools.

# Use both dynamic tools and specific resources
npx dodopayments-mcp --tools=dynamic --resource=payments

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 controlStore 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 regularlyGenerate new API keys periodically and revoke old ones through your Dodo Payments dashboard.Use test keys for developmentAlways use test mode API keys during development to avoid affecting production data.

Access Control

Apply tool filtering in productionLimit 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 remote serversWhen deploying remotely, always require authentication via the Authorization header or x-dodo-payments-api-key header.Monitor API usageTrack MCP server activity through your Dodo Payments dashboard and set up alerts for unusual patterns.

Network Security

Use HTTPS for remote serversAlways deploy remote MCP servers behind HTTPS endpoints.Implement rate limitingProtect against abuse by implementing rate limits at both the MCP server and API levels.Restrict network accessConfigure firewall rules to limit which clients can connect to your MCP server.

Troubleshooting

Connection issues

Verify your API keyEnsure 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 connectionVerify you can reach the Dodo Payments API endpoints.Review client logsEnable verbose logging in your MCP client to diagnose connection problems.

Authentication errors

Confirm API key environmentEnsure you’re using test keys with test endpoints and live keys with production endpoints.Check environment variableVerify DODO_PAYMENTS_ENVIRONMENT is set correctly (live_mode for production).Regenerate credentialsIf issues persist, generate a new API key through your dashboard.

Tool execution failures

Validate input parametersEnsure the AI assistant is providing correctly formatted parameters for each tool.Review error messagesCheck the error response from the API for specific guidance on what went wrong.Test with API directlyVerify the operation works when calling the Dodo Payments API directly via curl or Postman.

Client compatibility issues

Try a different client presetIf tools aren’t working correctly, try specifying your client explicitly:

npx dodopayments-mcp --client=cursor

Check capability supportSome clients don’t support all JSON schema features. Use --describe-capabilities to understand what’s supported.

Resources

API Reference

Explore the complete Dodo Payments API documentation

MCP Protocol

Learn more about the Model Context Protocol standard

GitHub Repository

View the MCP server source code and contribute

NPM Package

Install the MCP server from NPM

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Overview

Key capabilities

How Code Mode Works

Installation

Remote MCP Server (Recommended)

NPM Package

Docker

Client Configuration

Environment Variables

Running Remotely

Remote Server Configuration

Authorization Headers

Client Capabilities

Available Client Presets

Manual Capability Configuration

Tool Filtering

Filter by operation type

Filter by resource

Include or exclude specific tools

Combine filters

URL Query Parameter Filtering (Remote Server)

Dynamic Tools Mode

Advanced Usage

Programmatic integration

Custom tool development

Security Best Practices

Troubleshooting

Resources

API Reference

MCP Protocol

GitHub Repository

NPM Package

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Overview

​Key capabilities

​How Code Mode Works

​Installation

​Remote MCP Server (Recommended)

​NPM Package

​Docker

​Client Configuration

​Environment Variables

​Running Remotely

​Remote Server Configuration

​Authorization Headers

​Client Capabilities

​Available Client Presets

​Manual Capability Configuration

​Tool Filtering

​Filter by operation type

​Filter by resource

​Include or exclude specific tools

​Combine filters

​URL Query Parameter Filtering (Remote Server)

​Dynamic Tools Mode

​Advanced Usage

​Programmatic integration

​Custom tool development

​Security Best Practices

​Troubleshooting

​Resources

API Reference

MCP Protocol

GitHub Repository

NPM Package

Overview

Key capabilities

How Code Mode Works

Installation

Remote MCP Server (Recommended)

NPM Package

Docker

Client Configuration

Environment Variables

Running Remotely

Remote Server Configuration

Authorization Headers

Client Capabilities

Available Client Presets

Manual Capability Configuration

Tool Filtering

Filter by operation type

Filter by resource

Include or exclude specific tools

Combine filters

URL Query Parameter Filtering (Remote Server)

Dynamic Tools Mode

Advanced Usage

Programmatic integration

Custom tool development

Security Best Practices

Troubleshooting

Resources