Collegare un agente AI

Dai al tuo agente AI un URL solo — https://crypto.tgpaybot.com/mcp — e l’integrazione dei pagamenti te la costruisce lui: legge la documentazione dell’API, crea la tua app da esercente, imposta i webhook e scrive il codice. Tu approvi la nuova app una volta sola, con un pulsante nel bot. Niente terminale e nessun token API da copiare a mano.

Quell’URL è un server MCP (Model Context Protocol, il modo standard per collegare un servizio a un agente AI). Aprilo in un browser e ti spiega da solo come configurarlo.

Come si collega

Usa la riga che corrisponde al tuo strumento:

• Una chat con un agente qualsiasi — incolla questo prompt:

  Collega il server MCP di tgpay (https://crypto.tgpaybot.com/mcp) e integra i pagamenti tramite la Merchant API di TgPay.

  È pronto da copiare nell’app, sotto Altro → Merchant API → Collega un agente AI.
• Claude Code — claude mcp add --transport http tgpay https://crypto.tgpaybot.com/mcp
• claude.ai e Claude Desktop — Impostazioni → Connettori → Aggiungi connettore personalizzato → incolla l’URL.
• ChatGPT e altri client MCP — aggiungi un connettore personalizzato con lo stesso URL.

Non ti serve avere già un token API: l’agente si prende il suo al passaggio successivo. Se hai già creato un’app a mano, dai all’agente quel token e passa direttamente all’integrazione.

Approvare l’app

1. Chiedi all’agente di configurare i pagamenti. Legge la documentazione e ti chiede l’approvazione.
2. L’agente ti dà un link t.me. Aprilo: il bot ti mostra che cosa viene chiesto, e tu tocchi ✅ Crea l’app e rilascia il token.
3. Torna dall’agente. Riceve il suo token nel giro di pochi secondi e finisce l’integrazione da solo.

Il link arriva sempre dal tuo agente: il bot non ne manda mai uno di sua iniziativa, perché finché non lo apri non sa nemmeno di quale account l’agente stia parlando. Ogni link funziona una volta sola. Se smette di funzionare prima che tu lo tocchi, chiedi all’agente di ricominciare: finché non approvi non viene creato niente.

Se tocchi ❌ Rifiuta, ugualmente non viene creato niente e quella richiesta è chiusa: se cambi idea, l’agente ne deve fare una nuova.

⚠️ Approva solo una richiesta che hai avviato tu

Una richiesta di collegamento è una richiesta di creare un’app sul tuo account. Approvala solo se hai appena chiesto al tuo agente di configurare i pagamenti. Se un link ti arriva in qualsiasi altro modo — una chat, un messaggio inoltrato, l‘“assistenza” di uno sconosciuto — rifiutalo.

Il danno è comunque limitato per costruzione: il token dell’agente può far entrare denaro, mai farlo uscire (qui sotto). Ma un’app che non hai chiesto non ha motivo di esistere sul tuo account.

Che cosa può fare l’agente e che cosa no

Il token che riceve l’agente è un token con permessi limitati:

• Può creare fatture e piani di abbonamento, leggere saldo, tassi e statistiche, e impostare l’URL del webhook.
• Non può mandare trasferimenti, emettere buoni o rimborsare pagamenti. Tutto quello che porta fondi fuori dal saldo della tua app richiede il token ad accesso completo, che resta nell’app.

Quella divisione è voluta: i token degli agenti vivono in file di configurazione e nel contesto dei modelli, molto più esposti del tuo server. Uno che trapela può costarti un URL di webhook sbagliato, mai il tuo saldo. Il bot ti manda un messaggio ogni volta che viene rilasciato un token a un agente e ogni volta che cambia l’URL del webhook di un’app.

Per vedere il token dell’agente o toglierglielo, apri Altro → Merchant API, trova l’app e guarda sotto Token con permessi limitati: Revoca lo disattiva all’istante. L’app, il suo saldo e lo storico dei pagamenti restano.

Per le firme dei webhook serve il tuo token principale

L’agente può puntare l’URL del webhook sul tuo server, ma non può verificare quello che ci arriva: le consegne sono firmate con il token principale della tua app, che l’agente non vede mai. Un agente fatto bene scrive il codice di verifica e ti lascia un segnaposto — qualcosa come TGPAY_WEBHOOK_TOKEN — da riempire.

Per riempirlo: apri Altro → Merchant API, trova l’app creata dall’agente, tocca Rigenera il token e copia quello che compare, perché si vede una volta sola. Mettilo nell’ambiente del tuo server, mai nella configurazione dell’agente né nel tuo repository. La rigenerazione non tocca il token limitato dell’agente, quindi l’integrazione continua a funzionare.

Le firme passano al token nuovo nell’istante in cui lo rigeneri: quindi rigeneralo prima di andare in produzione, non dopo il primo pagamento vero.

Il prossimo passo

• Iniziare da sviluppatore — la strada manuale, e come si gestisce un’app una volta creata.
• Riferimento API: webhook — forma dei payload, tentativi di consegna e controllo della firma.
• Riferimento della Merchant API — tutti i metodi, compresi quelli che un agente non può chiamare.