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:- Docs Search Tool: Consulta documentações sobre a API e o SDK Dodo Payments para entender as operações e parâmetros disponíveis.
- Code Execution Tool: Escreve código TypeScript contra o SDK que é executado em um ambiente sandbox seguro.
Configuração rápida
Conecte-se ao Dodo Payments MCP Server no seu cliente de IA:- Cursor
- Claude Desktop
- Windsurf
- Tab Title
- Claude Code
Adicione a
~/.cursor/mcp.json:É 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:- Cursor
- Claude Desktop
- Windsurf
- Claude Code
Adicione a
~/.cursor/mcp.json:É 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:| Servidor | Finalidade | Caso de uso |
|---|---|---|
| Dodo Knowledge MCP | Busca de documentação | “Como lido com webhooks?”, “Quais métodos de pagamento são suportados?” |
| Dodo Payments MCP | Operações de API | Criar pagamentos, gerenciar assinaturas, lidar com reembolsos |
Solução de problemas do Knowledge MCP
Se você encontrar problemas de conexão:- Limpe o cache de autenticação do MCP:
rm -rf ~/.mcp-auth - Reinicie seu aplicativo cliente
- Verifique os logs do cliente em busca de mensagens de erro
- 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.Access the remote server
Navegue até https://mcp.dodopayments.com no seu navegador.
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:
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
Pacote NPM
Instale e execute o servidor MCP localmente usando NPM.- NPX (No Installation)
- MCP Client Configuration
Docker
Execute o servidor MCP em um ambiente conteinerizado para implantação consistente.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.- Cursor
- Claude Desktop
- Claude Code
- VS Code
- Cline (VS Code)
- Zed
- Other Clients
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:[
](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 manualOpen Cursor settings
Navegue até Cursor Settings > Features > Model Context Protocol ou pressione
Cmd/Ctrl + Shift + P e procure por “MCP Settings”.Add Dodo Payments configuration
Escolha uma das seguintes configurações:Servidor remoto (recomendado)NPX local
Variáveis de ambiente
Configure o comportamento do servidor MCP usando variáveis de ambiente.| Variável | Descrição | Obrigatória |
|---|---|---|
DODO_PAYMENTS_API_KEY | Sua chave de API Dodo Payments | Sim |
DODO_PAYMENTS_WEBHOOK_KEY | Sua chave de assinatura de webhook | Não |
DODO_PAYMENTS_ENVIRONMENT | Defina como live_mode para produção | Não |
Execução remota
Implemente o servidor MCP como um servidor HTTP remoto para clientes baseados na web ou fluxos de trabalho agentes.Configuração do servidor remoto
Depois de implementado, os clientes podem se conectar usando a URL do servidor:Cabeçalhos de autorização
O servidor remoto aceita autenticação por meio dos seguintes cabeçalhos:| Cabeçalho | Descrição |
|---|---|
Authorization | Autenticação com token Bearer |
x-dodo-payments-api-key | Cabeç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.API Key Management
API Key Management
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.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.
Access Control
Access Control
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.Network Security
Network Security
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
Connection issues
Connection issues
Verifique sua chave de APICertifique-se de que sua chave de API está corretamente definida e possui as permissões necessárias.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.
Authentication errors
Authentication errors
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.Tool execution failures
Tool execution failures
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.