Vai al contenuto principale

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. Il server Dodo Payments MCP utilizza l’architettura Code Mode. Invece di esporre centinaia di strumenti individuali per ogni endpoint API, Code Mode consente agli agenti AI di scrivere ed eseguire codice TypeScript contro l’SDK Dodo Payments in un ambiente sandbox isolato.

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

Il server Dodo Payments MCP fornisce al tuo agente AI esattamente due strumenti:
  1. Docs Search Tool: interroga la documentazione sull’API e sull’SDK di Dodo Payments per comprendere le operazioni e i parametri disponibili.
  2. Code Execution Tool: scrive codice TypeScript contro l’SDK che viene eseguito in un ambiente sandbox sicuro.
Questa architettura consente agli agenti di eseguire operazioni complesse e multi-step in un’unica invocazione. Ad esempio, un agente può elencare tutte le sottoscrizioni attive, filtrarle in base a criteri specifici e applicare uno sconto a ciascuna, tutto all’interno di uno script.
Usando Code Mode, gli agenti possono concatenare più chiamate API, gestire la logica condizionale ed eseguire calcoli senza richiedere molteplici round-trip al LLM.

Configurazione rapida

Connettiti al server Dodo Payments MCP nel tuo client AI:
Aggiungi a ~/.cursor/mcp.json:
{
  "mcpServers": {
    "dodopayments": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
    }
  }
}
Richiede Node.js 18 o superiore. Il server remoto utilizza OAuth per l’autenticazione: ti verrà chiesto di inserire la tua chiave API e selezionare l’ambiente alla prima connessione.

Dodo Knowledge MCP

Oltre al server Dodo Payments MCP (per eseguire operazioni API), forniamo Dodo Knowledge MCP — un server di ricerca semantica che offre agli assistenti AI accesso immediato alla documentazione e alla knowledge base di Dodo Payments.
Costruito con ContextMCP.ai: Dodo Knowledge MCP è alimentato da ContextMCP, permettendo ricerche semantiche veloci sulla documentazione tramite embedding vettoriali.

Cos’è Dodo Knowledge MCP?

Dodo Knowledge MCP è un server MCP remoto che offre:
  • Ricerca semantica della documentazione: trova la documentazione pertinente usando query in linguaggio naturale.
  • Risposte contestuali: gli assistenti AI ottengono informazioni accurate e aggiornate su Dodo Payments.
  • Zero configurazione: non servono chiavi API né installazioni locali: connettiti e inizia a interrogare.

Configurazione rapida

Connettiti a Dodo Knowledge MCP nel tuo client AI:
Aggiungi a ~/.cursor/mcp.json:
{
  "mcpServers": {
    "dodo-knowledge": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://knowledge.dodopayments.com/mcp"]
    }
  }
}
Richiede Node.js 18 o superiore. Il pacchetto mcp-remote gestisce la connessione al server MCP remoto.

Utilizzare entrambi i server MCP

Per la migliore esperienza di sviluppo assistita dall’AI, consigliamo di usare entrambi i server MCP:
ServerScopoCaso d’uso
Dodo Knowledge MCPRicerca nella documentazione“Come gestisco i webhook?”, “Quali metodi di pagamento sono supportati?”
Dodo Payments MCPOperazioni APICrea pagamenti, gestisci sottoscrizioni, gestisci rimborsi
{
  "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"]
    }
  }
}
Con entrambi i server configurati, il tuo assistente AI può prima cercare la documentazione per capire come implementare una funzionalità e poi eseguire le chiamate API reali, tutto in una singola conversazione.

Risoluzione dei problemi per Knowledge MCP

Se riscontri problemi di connessione:
  1. Cancella la cache di autenticazione MCP: rm -rf ~/.mcp-auth
  2. Riavvia l’applicazione client
  3. Controlla i log del client per messaggi di errore
  4. Verifica la versione di Node.js: richiede Node.js 18+

Knowledge MCP Server

Accedi alla pagina di configurazione Dodo Knowledge MCP

Installazione

Scegli il metodo di installazione che meglio si adatta al tuo flusso di lavoro.

Server MCP remoto (consigliato)

Accedi al server MCP ospitato senza alcuna configurazione o installazione locale. Questo è il modo più rapido per iniziare.
1

Access the remote server

Accedi a https://mcp.dodopayments.com nel tuo browser.
2

Configure your MCP client

Copia la configurazione JSON fornita per il tuo client specifico. Per Cursor o Claude Desktop, aggiungila alle tue impostazioni MCP:
{
  "mcpServers": {
    "dodopayments_api": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
    }
  }
}
3

Authenticate and configure

Il flusso OAuth ti chiederà di:
  • Inserire la tua chiave API Dodo Payments
  • Selezionare l’ambiente (test o live)
  • Scegliere il tipo di client MCP
Mantieni la tua chiave API al sicuro. Usa chiavi in modalità test durante lo sviluppo.
4

Complete setup

Clicca Login and Approve per autorizzare la connessione.
Una volta connesso, il tuo assistente AI può interagire con l’API Dodo Payments per tuo conto.

Pacchetto NPM

Installa ed esegui il server MCP localmente tramite 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
Usa @latest per ottenere sempre la versione più recente, oppure blocca una versione specifica come @1.0.0 per stabilità.

Docker

Esegui il server MCP in un ambiente containerizzato per deployment coerenti.
# 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
Le immagini Docker sono disponibili su GitHub Container Registry.

Configurazione del client

Configura il server Dodo Payments MCP nel client AI preferito.
Configura il server Dodo Payments MCP in Cursor per abilitare l’accesso conversazionale ai tuoi dati di pagamento.Installazione con un clicUsa il pulsante sottostante per installare direttamente il server MCP in Cursor:[Add to Cursor](https://cursor.com/en-US/install-mcp?name=dodopayments-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImRvZG9wYXltZW50cy1tY3AiXSwiZW52Ijp7IkRPRE9fUEFZTUVOVFNfQVBJX0tFWSI6IlNldCB5b3VyIERPRE9fUEFZTUVOVFNfQVBJX0tFWSBoZXJlLiIsIkRPRE9fUEFZTUVOVFNfV0VCSE9PS19LRVkiOiJTZXQgeW91ciBET0RPX1BBWU1FTlRTX1dFQkhPT0tfS0VZIGhlcmUuIn19)Dopo il clic, imposta le variabili di ambiente in mcp.json di Cursor tramite Cursor Settings > Tools & MCP > New MCP Server.Configurazione manuale
1

Open Cursor settings

Vai su Cursor Settings > Features > Model Context Protocol oppure premi Cmd/Ctrl + Shift + P e cerca “MCP Settings”.
2

Edit configuration

Clicca Edit Config per aprire il file mcp_config.json.
3

Add Dodo Payments configuration

Scegli una delle seguenti configurazioni:Server remoto (consigliato)
{
  "mcpServers": {
    "dodopayments": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
    }
  }
}
NPX locale
{
  "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

Salva il file di configurazione e riavvia Cursor.
Verifica la connessione chiedendo all’assistente AI informazioni sui tuoi dati Dodo Payments.

Variabili di ambiente

Configura il comportamento del server MCP usando variabili di ambiente.
VariabileDescrizioneObbligatoria
DODO_PAYMENTS_API_KEYLa tua chiave API Dodo Payments
DODO_PAYMENTS_WEBHOOK_KEYLa tua chiave di firma webhookNo
DODO_PAYMENTS_ENVIRONMENTImposta su live_mode per la produzioneNo

Esecuzione remota

Distribuisci il server MCP come server HTTP remoto per client web o workflow agentici.
# Start as remote server
npx -y dodopayments-mcp --transport=http

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

Configurazione del server remoto

Una volta distribuito, i client possono connettersi usando l’URL del server:
{
  "mcpServers": {
    "dodopayments_api": {
      "url": "http://localhost:3000",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    }
  }
}

Header di autorizzazione

Il server remoto accetta l’autenticazione tramite i seguenti header:
HeaderDescrizione
AuthorizationAutenticazione con token Bearer
x-dodo-payments-api-keyHeader diretto con chiave API

Best practice di sicurezza

Code Mode offre sicurezza intrinseca grazie all’esecuzione del codice in un ambiente sandbox e all’iniezione lato server delle chiavi API. Segui queste ulteriori best practice per proteggere le tue credenziali.
Non commettere mai credenziali nel controllo versioneConserva le chiavi API in variabili di ambiente o sistemi di gestione segreti sicuri.
# 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
Ruota regolarmente le chiaviGenera nuove chiavi API periodicamente e revoca quelle vecchie tramite la dashboard di Dodo Payments.Usa chiavi di test durante lo sviluppoUsa sempre chiavi API in modalità test durante lo sviluppo per evitare di influenzare i dati di produzione.
Implementa l’autenticazione per i server remotiQuando distribuisci in remoto, richiedi sempre l’autenticazione tramite l’header Authorization o l’header x-dodo-payments-api-key.Monitora l’utilizzo dell’APIMonitora l’attività del server MCP tramite la dashboard di Dodo Payments e imposta avvisi per pattern insoliti.
Usa HTTPS per i server remotiDistribuisci sempre i server MCP remoti dietro endpoint HTTPS.Implementa limitazioni di velocitàProteggiti dagli abusi implementando rate limit sia sul server MCP che sui livelli API.Restringi l’accesso alla reteConfigura regole firewall per limitare quali client possono connettersi al tuo server MCP.

Risoluzione dei problemi

Verifica la tua chiave APIAssicurati che la tua chiave API sia impostata correttamente e abbia i permessi necessari.
# Test your API key
curl -H "Authorization: Bearer dodo_test_..." \
  https://test.dodopayments.com/payments
Controlla la connessione di reteVerifica di poter raggiungere gli endpoint dell’API Dodo Payments.Rivedi i log del clientAbilita i log dettagliati nel tuo client MCP per diagnosticare problemi di connessione.
Conferma l’ambiente della chiave APIAssicurati di usare chiavi di test con gli endpoint di test e chiavi live con gli endpoint di produzione.Controlla la variabile di ambienteVerifica che DODO_PAYMENTS_ENVIRONMENT sia impostata correttamente (live_mode per la produzione).Rigenera le credenzialiSe il problema persiste, genera una nuova chiave API tramite la dashboard.
Valida i parametri di inputAssicurati che l’assistente AI fornisca parametri formattati correttamente per ogni strumento.Rivedi i messaggi di erroreControlla la risposta di errore dell’API per indicazioni specifiche su cosa è andato storto.Testa direttamente con l’APIVerifica che l’operazione funzioni chiamando direttamente l’API Dodo Payments tramite curl o Postman.

Perché Code Mode

Le implementazioni MCP tradizionali spesso soffrono di “tool proliferation”, dove ogni endpoint API viene esposto come strumento separato. Code Mode è un approccio superiore per diversi motivi:

Gli LLM sono migliori a scrivere codice che a chiamare strumenti

Gli LLM sono stati addestrati su milioni di righe di codice reale, rendendoli naturalmente proficienti nella scrittura di script. Al contrario, il tool-calling si basa spesso su esempi sintetici.
“Far eseguire compiti a un LLM tramite tool calling è come mandare Shakespeare a un corso intensivo di mandarino e poi chiedergli di scrivere una tragedia in quella lingua.” — Cloudflare

Elimina l’ingombro della finestra di contesto

In un approccio tradizionale, ogni definizione di strumento consuma token prima ancora che la conversazione inizi. Esporre oltre 50 strumenti può facilmente consumare 55K–100K+ token. Anthropic ha scoperto che le definizioni degli strumenti possono consumare fino a 134K token prima dell’ottimizzazione. Con Code Mode, vengono caricate solo 2 definizioni di strumenti (~1K token). L’agente ricerca la documentazione di cui ha bisogno in tempo reale. Lo strumento Tool Search di Anthropic ha preservato il 95% della finestra di contesto, riducendo l’overhead da 77K a 8,7K token.

Riduce la latenza tramite orchestrazione programmata

Il tool-calling tradizionale richiede un’inferenza completa del modello per ogni singola operazione. Se un task richiede 20 chiamate API, sono 20 round-trip. In Code Mode, l’agente scrive uno script che esegue tutte le chiamate e restituisce solo il risultato finale. Anthropic ha osservato una riduzione del 37% dei token e un aumento dell’accuratezza (il recupero della conoscenza è passato dal 25,6% al 28,5%) usando questo approccio programmato.

Più sicuro per progettazione

Code Mode offre benefici di sicurezza intrinseci:
  • Nessuna chiave API nei parametri: le chiavi API vengono iniettate lato server e non vengono mai esposte nei parametri dello strumento inviati all’LLM.
  • Sandbox isolata: il codice viene eseguito in un ambiente sicuro senza accesso alla rete o al filesystem host.
  • SDK controllato: all’agente sono disponibili solo i metodi SDK autorizzati.

Si adatta a qualsiasi dimensione di API

Man mano che un’API cresce, le prestazioni MCP tradizionali degradano perché devono essere caricati più strumenti nel contesto. Code Mode rimane costante con 2 strumenti indipendentemente dall’area di superficie dell’API. Cloudflare è riuscita a comprimere oltre 2.500 endpoint API in appena 2 strumenti e circa 1.000 token di contesto.
Per maggiori dettagli sui benefici di questa architettura, consulta i blog di ingegneria di Anthropic e Cloudflare, e la documentazione Programmatic Tool Calling di Claude.

Risorse