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.

Dodo Knowledge MCP

Além do Dodo Payments MCP Server (para executar operações de 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 do Dodo Payments.
Construído com ContextMCP.ai: O Dodo Knowledge MCP é alimentado pelo ContextMCP, permitindo uma busca semântica rápida em nossa documentação usando embeddings vetoriais.

O que é o Dodo Knowledge MCP?

O Dodo Knowledge MCP é um servidor MCP remoto que fornece:
  • 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 o Dodo Payments
  • Zero Configuração: Nenhuma chave de API ou instalação local necessária - basta conectar e começar a consultar

Configuração Rápida

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

Usando Ambos os Servidores MCP Juntos

Para a melhor experiência de desenvolvimento assistida por IA, recomendamos usar ambos os servidores MCP:
ServidorPropósitoCaso de Uso
Dodo Knowledge MCPBusca de documentação”Como faço para lidar 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 de API reais - tudo em uma única conversa.

Solução de Problemas do Knowledge MCP

Se você encontrar problemas de conexão:
  1. Limpar cache de autenticação MCP: rm -rf ~/.mcp-auth
  2. Reinicie seu aplicativo cliente
  3. Verifique os logs do cliente para 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 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 do 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 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 em 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 Dodo Payments MCP em seu cliente de IA preferido.
Configure o servidor Dodo Payments MCP 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 no arquivo de configuração de Cursor em mcp.json via Configurações do Cursor > Ferramentas & MCP > Novo Servidor MCP.Configuração Manual
1

Abrir configurações do Cursor

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

Editar 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ário
DODO_PAYMENTS_API_KEYSua chave de API do Dodo PaymentsSim
DODO_PAYMENTS_WEBHOOK_KEYSua chave de assinatura do webhookNão
DODO_PAYMENTS_ENVIRONMENTDefina como live_mode para produçãoNão

Executando Remotamente

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 da 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 as capacidades.

Filtragem de Ferramentas

Controle quais operações de 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 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 de API individuais:
  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 ativadas automaticamente 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 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 via cabeçalho Authorization ou 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.

Solução de Problemas

Verifique sua chave de APICertifique-se de que sua chave de API está configurada corretamente e tem 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 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 você 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á configurado 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