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 Dodo Payments MCP Server utiliza a arquitetura Code Mode. Em vez de expor centenas de ferramentas individuais para cada endpoint da API, o Code Mode permite que agentes de IA escrevam e executem código TypeScript contra o SDK Dodo Payments em um ambiente 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 Dodo Payments MCP Server fornece ao seu agente de IA exatamente duas ferramentas:
  1. Docs Search Tool: Consulta documentações sobre a API e o SDK Dodo Payments para entender as operações e parâmetros disponíveis.
  2. Code Execution Tool: Escreve código TypeScript contra o SDK que é executado em um ambiente sandbox seguro.
Essa arquitetura permite que agentes realizem operações complexas em múltiplas etapas em uma única invocação. Por exemplo, um agente pode listar todas as assinaturas ativas, filtrá-las com base em critérios específicos e aplicar um desconto a cada uma — tudo dentro de um único script.
Usando o Code Mode, os agentes podem encadear múltiplas chamadas à API, tratar lógica condicional e realizar cálculos sem exigir várias viagens ao LLM.

Configuração rápida

Conecte-se ao Dodo Payments MCP Server no seu cliente de IA:
Adicione a ~/.cursor/mcp.json:
{
  "mcpServers": {
    "dodopayments": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
    }
  }
}
É necessário Node.js 18 ou superior. O servidor remoto usa OAuth para autenticação — você será solicitado a inserir sua chave de API e selecionar seu ambiente na primeira conexão.

Dodo Knowledge MCP

Além do Dodo Payments MCP Server (para executar operações da API), fornecemos o Dodo Knowledge MCP — um servidor de busca semântica que dá aos assistentes de IA acesso instantâneo à documentação e base de conhecimento da Dodo Payments.
Construído com o ContextMCP.ai: o Dodo Knowledge MCP é alimentado pelo ContextMCP, possibilitando buscas semânticas rápidas em nossa documentação usando embeddings vetoriais.

O que é o Dodo Knowledge MCP?

O Dodo Knowledge MCP é um servidor MCP remoto que oferece:
  • Busca semântica de documentação: Encontre documentação relevante usando consultas em linguagem natural.
  • Respostas contextuais: Assistentes de IA obtêm informações precisas e atualizadas sobre a Dodo Payments.
  • Zero configuração: Não são necessárias chaves de API ou instalações locais — basta conectar e começar a consultar.

Configuração rápida

Conecte-se ao Dodo Knowledge MCP no seu cliente de IA:
Adicione a ~/.cursor/mcp.json:
{
  "mcpServers": {
    "dodo-knowledge": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://knowledge.dodopayments.com/mcp"]
    }
  }
}
É necessário Node.js 18 ou superior. O pacote mcp-remote gerencia a conexão com o servidor MCP remoto.

Usando ambos os MCP Servers juntos

Para a melhor experiência de desenvolvimento assistida por IA, recomendamos o uso dos dois servidores MCP:
ServidorFinalidadeCaso de uso
Dodo Knowledge MCPBusca de documentação“Como lido com webhooks?”, “Quais métodos de pagamento são suportados?”
Dodo Payments MCPOperações de APICriar pagamentos, gerenciar assinaturas, lidar com reembolsos
{
  "mcpServers": {
    "dodo-knowledge": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://knowledge.dodopayments.com/mcp"]
    },
    "dodopayments": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
    }
  }
}
Com ambos os servidores configurados, seu assistente de IA pode primeiro buscar documentação para entender como implementar um recurso e depois executar as chamadas reais da API — tudo em uma única conversa.

Solução de problemas do Knowledge MCP

Se você encontrar problemas de conexão:
  1. Limpe o cache de autenticação do MCP: rm -rf ~/.mcp-auth
  2. Reinicie seu aplicativo cliente
  3. Verifique os logs do cliente em busca de mensagens de erro
  4. Verifique a versão do Node.js: Requer Node.js 18+

Knowledge MCP Server

Acesse a página de configuração do Dodo Knowledge MCP

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 qualquer configuração local ou instalação. Esta é a maneira mais rápida de começar.
1

Access the remote server

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

Configure your MCP client

Copie a configuração JSON fornecida para o 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

Authenticate and configure

O fluxo OAuth solicitará que você:
  • Insira sua chave de API 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 setup

Clique em Login and Approve para autorizar a conexão.
Uma vez conectado, seu assistente de IA pode interagir com a API 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 obter a versão mais recente ou fixe uma versão específica como @1.0.0 para estabilidade.

Docker

Execute o servidor MCP em um ambiente conteinerizado 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 Dodo Payments MCP no seu cliente de IA preferido.
Configure o servidor Dodo Payments MCP no Cursor para permitir acesso conversacional aos seus dados de pagamentos.Instalação com um cliqueUse o botão abaixo para instalar o servidor MCP diretamente no Cursor:[Add to Cursor](https://cursor.com/en-US/install-mcp?name=dodopayments-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImRvZG9wYXltZW50cy1tY3AiXSwiZW52Ijp7IkRPRE9fUEFZTUVOVFNfQVBJX0tFWSI6IlNldCB5b3VyIERPRE9fUEFZTUVOVFNfQVBJX0tFWSBoZXJlLiIsIkRPRE9fUEFZTUVOVFNfV0VCSE9PS19LRVkiOiJTZXQgeW91ciBET0RPX1BBWU1FTlRTX1dFQkhPT0tfS0VZIGhlcmUuIn19)Após clicar, defina suas variáveis de ambiente no mcp.json do Cursor via Cursor Settings > Tools & MCP > New MCP Server.Configuração manual
1

Open Cursor settings

Navegue até Cursor Settings > Features > Model Context Protocol ou pressione Cmd/Ctrl + Shift + P e procure por “MCP Settings”.
2

Edit configuration

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

Add Dodo Payments configuration

Escolha uma das seguintes configurações:Servidor remoto (recomendado)
{
  "mcpServers": {
    "dodopayments": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
    }
  }
}
NPX local
{
  "mcpServers": {
    "dodopayments": {
      "command": "npx",
      "args": ["-y", "dodopayments-mcp@latest"],
      "env": {
        "DODO_PAYMENTS_API_KEY": "dodo_test_...",
        "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key"
      }
    }
  }
}
4

Save and restart

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

Variáveis de ambiente

Configure o comportamento do servidor MCP usando variáveis de ambiente.
VariávelDescriçãoObrigatória
DODO_PAYMENTS_API_KEYSua chave de API 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

Implemente 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

Depois de implementado, 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 por meio dos seguintes cabeçalhos:
CabeçalhoDescrição
AuthorizationAutenticação com token Bearer
x-dodo-payments-api-keyCabeçalho de chave de API direta

Melhores práticas de segurança

O Code Mode fornece segurança inerente ao executar o código em um ambiente sandbox e injetar as chaves de API no servidor. Siga essas práticas adicionais para proteger suas credenciais.
Nunca envie credenciais para o controle de versãoArmazene as chaves de API em variáveis de ambiente ou sistemas seguros de gerenciamento de segredos.
# 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 Dodo Payments.Use chaves de teste para desenvolvimentoSempre utilize chaves de modo de teste durante o desenvolvimento para evitar afetar dados de produção.
Implemente autenticação para servidores remotosAo implementar remotamente, sempre exija autenticação via o cabeçalho Authorization ou o cabeçalho x-dodo-payments-api-key.Monitore o uso da APIAcompanhe a atividade do servidor MCP pelo painel da Dodo Payments e configure alertas para padrões incomuns.
Use HTTPS para servidores remotosSempre implemente servidores MCP remotos atrás de endpoints HTTPS.Implemente limitação de taxaProteja-se contra abusos implementando limites de taxa tanto no servidor MCP quanto nos níveis da API.Restrinja o acesso à redeConfigure regras de firewall para limitar quais clientes podem se conectar ao seu servidor MCP.

Solução de problemas

Verifique sua chave de APICertifique-se de que sua chave de API está corretamente definida e possui as permissões necessárias.
# Test your API key
curl -H "Authorization: Bearer dodo_test_..." \
  https://test.dodopayments.com/payments
Verifique sua conexão de redeConfirme se você consegue acessar os endpoints da API Dodo Payments.Revise os logs do clienteHabilite o log detalhado no seu cliente MCP para diagnosticar problemas de conexão.
Confirme o ambiente das chaves de APIGaranta que você esteja usando chaves de teste com endpoints de teste e chaves de produção com endpoints reais.Verifique a variável de ambienteVerifique se DODO_PAYMENTS_ENVIRONMENT está definida corretamente (live_mode para produção).Regere credenciaisSe os problemas persistirem, gere uma nova chave de API pelo seu painel.
Valide os parâmetros de entradaGaranta que o assistente de IA esteja fornecendo parâmetros corretamente formatados para cada ferramenta.Revise mensagens de erroConfira 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 Dodo Payments diretamente via curl ou Postman.

Por que Code Mode

Implementações tradicionais de MCP frequentemente sofrem com “proliferação de ferramentas”, onde cada endpoint da API é exposto como uma ferramenta separada. O Code Mode é uma abordagem superior por várias razões:

LLMs são melhores em escrever código do que chamar ferramentas

LLMs foram treinados em milhões de linhas de código do mundo real, tornando-os naturalmente proficientes em escrever scripts. Em contraste, chamadas de ferramentas costumam ser baseadas em exemplos sintéticos.
“Fazer um LLM executar tarefas por meio de chamadas de ferramentas é como colocar Shakespeare em um curso intensivo de mandarim e depois pedir que ele escreva uma peça nessa língua.” — Cloudflare

Elimina o inchaço da janela de contexto

Em uma abordagem tradicional, cada definição de ferramenta consome tokens antes mesmo da conversa começar. Expor mais de 50 ferramentas pode facilmente consumir de 55K a mais de 100K tokens. A Anthropic descobriu que definições de ferramentas podiam consumir até 134K tokens antes da otimização. Com o Code Mode, apenas 2 definições de ferramentas são carregadas (~1K tokens). O agente busca a documentação necessária sob demanda. A ferramenta Tool Search da Anthropic preservou 95% da janela de contexto, reduzindo o overhead de 77K para 8.7K tokens.

Reduz a latência por meio de orquestração programática

Chamadas de ferramentas tradicionais exigem uma inferência completa do modelo para cada operação. Se uma tarefa requer 20 chamadas à API, são 20 viagens de ida e volta. No Code Mode, o agente escreve um único script que executa todas as chamadas e retorna apenas o resultado final. A Anthropic observou uma redução de 37% nos tokens e melhoria na precisão (a recuperação de conhecimento passou de 25,6% para 28,5%) usando essa abordagem programática.

Mais seguro por design

O Code Mode proporciona benefícios inerentes de segurança:
  • Sem chaves de API nos parâmetros: as chaves são injetadas no servidor e nunca expostas nos parâmetros das ferramentas enviados ao LLM.
  • Sandbox isolado: o código é executado em um ambiente seguro sem acesso à rede ou ao sistema de arquivos do host.
  • SDK controlado: somente métodos autorizados do SDK estão disponíveis para o agente.

Escala para qualquer tamanho de API

À medida que uma API cresce, o desempenho das implementações tradicionais de MCP se degrada porque mais ferramentas precisam ser carregadas no contexto. O Code Mode permanece constante com 2 ferramentas, independentemente da superfície da API. A Cloudflare conseguiu condensar mais de 2.500 endpoints da API em apenas 2 ferramentas e aproximadamente 1.000 tokens de contexto.
Para mais detalhes sobre os benefícios dessa arquitetura, veja os blogs de engenharia da Anthropic e da Cloudflare, e a documentação de Programmatic Tool Calling da Claude.

Recursos