Pular para o conteúdo principal

Visão Geral

O Protocolo de Contexto de Modelo (MCP) é um padrão aberto que permite que aplicações de IA se conectem de forma segura a fontes de dados externas e APIs. O Servidor MCP de Pagamentos Dodo fornece a assistentes de IA como Claude, Cursor e outros clientes compatíveis com MCP acesso estruturado à sua infraestrutura de pagamento. O Servidor MCP do Dodo Payments é construído com Stainless e utiliza a arquitetura Code Mode, que permite que agentes de IA escrevam e executem código TypeScript contra o SDK do Dodo Payments em um ambiente de sandbox isolado.

Principais capacidades

  • Operações de Pagamento: Criar, recuperar e gerenciar pagamentos e reembolsos
  • Gerenciamento de Assinaturas: Lidar com cobranças recorrentes, upgrades e cancelamentos
  • Administração de Clientes: Gerenciar dados de clientes e acesso ao portal
  • Catálogo de Produtos: Criar e atualizar produtos, preços e descontos
  • Gerenciamento de Licenças: Ativar, validar e gerenciar licenças de software
  • Cobrança Baseada em Uso: Rastrear e cobrar pelo uso medido

Como o Code Mode Funciona

O Servidor MCP do Dodo Payments utiliza o Code Mode, fornecendo ao seu agente de IA duas ferramentas poderosas:
  1. Docs Search Tool: Consultar a documentação sobre a API e SDK do Dodo Payments para entender as operações e parâmetros disponíveis
  2. Code Execution Tool: Escrever código TypeScript contra o SDK que é executado em um ambiente de sandbox seguro sem acesso à web ou ao sistema de arquivos
Essa arquitetura permite que agentes de IA realizem operações de pagamento complexas e em múltiplas etapas de forma determinística e repetível.
Usando o Code Mode, os agentes podem encadear múltiplas chamadas de API, lidar com lógica condicional e realizar cálculos—tudo em uma única invocação de ferramenta.

Instalação

Escolha o método de instalação que melhor se adapta ao seu fluxo de trabalho.

Servidor MCP Remoto (Recomendado)

Acesse o servidor MCP hospedado sem nenhuma configuração ou instalação local. Esta é a maneira mais rápida de começar.
1

Acesse o servidor remoto

Navegue até https://mcp.dodopayments.com em seu navegador.
2

Configure seu cliente MCP

Copie a configuração JSON fornecida para seu cliente específico. Para Cursor ou Claude Desktop, adicione isso às suas configurações MCP:
{
  "mcpServers": {
    "dodopayments_api": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
    }
  }
}
3

Autentique e configure

O fluxo OAuth solicitará que você:
  • Insira sua chave de API do Dodo Payments
  • Selecione seu ambiente (teste ou produção)
  • Escolha seu tipo de cliente MCP
Mantenha sua chave de API segura. Use chaves de modo de teste durante o desenvolvimento.
4

Complete a configuração

Clique em Login e Aprovar para autorizar a conexão.
Uma vez conectado, seu assistente de IA pode interagir com a API do Dodo Payments em seu nome.

Pacote NPM

Instale e execute o servidor MCP localmente usando NPM.
# 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
Use @latest para sempre puxar a versão mais recente, ou fixe a uma versão específica como @1.0.0 para estabilidade.

Docker

Execute o servidor MCP em um ambiente containerizado para implantação consistente.
# 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
Imagens Docker estão disponíveis no GitHub Container Registry.

Configuração do Cliente

Configure o servidor MCP do Dodo Payments em seu cliente de IA preferido.
Configure o servidor MCP do Dodo Payments no Cursor para habilitar o acesso conversacional aos seus dados de pagamento.Instalação com Um CliqueUse o botão abaixo para instalar o servidor MCP diretamente no Cursor:[Adicionar ao Cursor](https://cursor.com/en-US/install-mcp?name=dodopayments-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImRvZG9wYXltZW50cy1tY3AiXSwiZW52Ijp7IkRPRE9fUEFZTUVOVFNfQVBJX0tFWSI6IlNldCB5b3VyIERPRE9fUEFZTUVOVFNfQVBJX0tFWSBoZXJlLiIsIkRPRE9fUEFZTUVOVFNfV0VCSE9PS19LRVkiOiJTZXQgeW91ciBET0RPX1BBWU1FTlRTX1dFQkhPT0tfS0VZIGhlcmUuIn19)Após clicar, defina suas variáveis de ambiente nas mcp.json do Cursor via Configurações do Cursor > Ferramentas & MCP > Novo Servidor MCP.Configuração Manual
1

Abra as configurações do Cursor

Navegue até Configurações do Cursor > Recursos > Modelo Contextual de Protocolo ou pressione Cmd/Ctrl + Shift + P e procure por “Configurações MCP”.
2

Edite a configuração

Clique em Editar Config para abrir o arquivo mcp_config.json.
3

Adicione a configuração do Dodo Payments

Escolha uma das seguintes configurações:Servidor Remoto (Recomendado)
{
  "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"
      }
    }
  }
}
4

Salve e reinicie

Salve o arquivo de configuração e reinicie o Cursor.
Verifique a conexão perguntando ao assistente de IA sobre seus dados do Dodo Payments.

Variáveis de Ambiente

Configure o comportamento do servidor MCP usando variáveis de ambiente.
VariávelDescriçãoNecessária
DODO_PAYMENTS_API_KEYSua chave de API do Dodo PaymentsSim
DODO_PAYMENTS_WEBHOOK_KEYSua chave de assinatura de webhookNão
DODO_PAYMENTS_ENVIRONMENTDefina como live_mode para produçãoNão

Execução Remota

Implante o servidor MCP como um servidor HTTP remoto para clientes baseados na web ou fluxos de trabalho agentes.
# Start as remote server
npx -y dodopayments-mcp --transport=http

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

Configuração do Servidor Remoto

Uma vez implantado, os clientes podem se conectar usando a URL do servidor:
{
  "mcpServers": {
    "dodopayments_api": {
      "url": "http://localhost:3000",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    }
  }
}

Cabeçalhos de Autorização

O servidor remoto aceita autenticação através dos seguintes cabeçalhos:
CabeçalhoDescrição
AuthorizationAutenticação por token Bearer
x-dodo-payments-api-keyCabeçalho de chave de API direta

Capacidades do Cliente

Diferentes clientes MCP têm níveis variados de suporte para a especificação MCP. O servidor pode ajustar automaticamente os esquemas de ferramentas para contornar essas limitações.
# 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

Presets de Cliente Disponíveis

ClienteDescrição
inferCliente de detecção automática (padrão)
cursorEditor Cursor
claudeClaude AI web ou desktop
claude-codeClaude Code CLI
openai-agentsPlataforma de agentes OpenAI

Configuração Manual de Capacidades

Para clientes não listados acima, configure manualmente as capacidades:
# Disable $ref pointer support and set max tool name length
npx dodopayments-mcp --no-capability=refs --capability=tool-name-length=40
Capacidades disponíveis:
  • top-level-unions - Suporte para tipos de união de nível superior
  • valid-json - Análise correta de argumentos de string JSON
  • refs - Suporte para ponteiros $ref em esquemas
  • unions - Suporte para tipos de união (anyOf)
  • formats - Suporte para validações de formato
  • tool-name-length=N - Comprimento máximo do nome da ferramenta
Execute npx dodopayments-mcp --describe-capabilities para informações detalhadas sobre capacidades.

Filtragem de Ferramentas

Controle quais operações da API são expostas ao seu assistente de IA para otimizar o desempenho e manter a segurança.

Filtrar por tipo de operação

Restringir o acesso a operações somente de leitura ou de gravação.
# 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 durante o desenvolvimento para evitar modificações acidentais em seus dados.

Filtrar por recurso

Limitar ferramentas a recursos específicos da API.
# 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*

Incluir ou excluir ferramentas específicas

Ajuste quais ferramentas individuais estão disponíveis.
# 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

Combinar filtros

Aplique múltiplos filtros simultaneamente para controle preciso.
# Only payment and subscription read operations
npx dodopayments-mcp --operation=read --resource=payments --resource=subscriptions

Filtragem de Parâmetros de Consulta de URL (Servidor Remoto)

Ao usar o servidor remoto, aplique filtros através de parâmetros de consulta de URL:
https://mcp.dodopayments.com/?operation=read
https://mcp.dodopayments.com/?resource=payments

Modo de Ferramentas Dinâmicas

Para APIs grandes, carregar todas as ferramentas de uma vez pode sobrecarregar a janela de contexto da IA. O modo de ferramentas dinâmicas fornece uma alternativa mais eficiente.
npx dodopayments-mcp --tools=dynamic
No modo dinâmico, três meta-ferramentas substituem ferramentas individuais da API:
  1. list_api_endpoints - Descobre métodos disponíveis com filtragem opcional
  2. get_api_endpoint_schema - Obtém esquema detalhado para um método específico
  3. invoke_api_endpoint - Executa qualquer método com parâmetros apropriados
Ferramentas dinâmicas são automaticamente habilitadas para APIs com mais de 50 métodos. Substitua com --tools=all para incluir todas as ferramentas.
# Use both dynamic tools and specific resources
npx dodopayments-mcp --tools=dynamic --resource=payments

Uso Avançado

Integração programática

Construa servidores MCP personalizados ou estenda o existente programaticamente.
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);

Desenvolvimento de ferramentas personalizadas

Estenda o servidor MCP com suas próprias ferramentas e lógica de negócios.
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] 
});

Melhores Práticas de Segurança

Proteja suas credenciais de API e mantenha integrações seguras.
Nunca comite credenciais no controle de versãoArmazene chaves de API em variáveis de ambiente ou sistemas de gerenciamento de segredos seguros.
# 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
Gire as chaves regularmenteGere novas chaves de API periodicamente e revogue as antigas através do seu painel do Dodo Payments.Use chaves de teste para desenvolvimentoSempre use chaves de API em modo de teste durante o desenvolvimento para evitar afetar dados de produção.
Aplique filtragem de ferramentas em produçãoLimite operações expostas apenas ao que seu assistente de IA precisa.
# Production: read-only access
npx dodopayments-mcp --operation=read

# Development: full access
npx dodopayments-mcp
Implemente autenticação para servidores remotosAo implantar remotamente, sempre exija autenticação através do cabeçalho Authorization ou do cabeçalho x-dodo-payments-api-key.Monitore o uso da APIAcompanhe a atividade do servidor MCP através do seu painel do Dodo Payments e configure alertas para padrões incomuns.
Use HTTPS para servidores remotosSempre implante servidores MCP remotos atrás de endpoints HTTPS.Implemente limitação de taxaProteja contra abusos implementando limites de taxa tanto no servidor MCP quanto nos níveis da API.Restringir acesso à redeConfigure regras de firewall para limitar quais clientes podem se conectar ao seu servidor MCP.

Resolução de Problemas

Verifique sua chave de APICertifique-se de que sua chave de API está configurada corretamente e possui as permissões necessárias.
# Test your API key
curl -H "Authorization: Bearer dodo_test_..." \
  https://api.dodopayments.com/payments
Verifique sua conexão de redeVerifique se você consegue acessar os endpoints da API do Dodo Payments.Revise os logs do clienteAtive o registro detalhado em seu cliente MCP para diagnosticar problemas de conexão.
Confirme o ambiente da chave de APICertifique-se de que está usando chaves de teste com endpoints de teste e chaves ao vivo com endpoints de produção.Verifique a variável de ambienteVerifique se DODO_PAYMENTS_ENVIRONMENT está configurada corretamente (live_mode para produção).Regenerar credenciaisSe os problemas persistirem, gere uma nova chave de API através do seu painel.
Valide os parâmetros de entradaCertifique-se de que o assistente de IA está fornecendo parâmetros formatados corretamente para cada ferramenta.Revise as mensagens de erroVerifique a resposta de erro da API para orientações específicas sobre o que deu errado.Teste diretamente com a APIVerifique se a operação funciona ao chamar a API do Dodo Payments diretamente via curl ou Postman.
Tente um preset de cliente diferenteSe as ferramentas não estiverem funcionando corretamente, tente especificar seu cliente explicitamente:
npx dodopayments-mcp --client=cursor
Verifique o suporte a capacidadesAlguns clientes não suportam todos os recursos do esquema JSON. Use --describe-capabilities para entender o que é suportado.

Recursos