Collegare un agente AI · TgPay Crypto API

Collega un agente AI per lo sviluppo che supporti server MCP remoti a https://app.tgpaycrypto.com/mcp. Può leggere la documentazione API, richiedere un’app per commercianti, configurare i webhook e aiutarti a scrivere l’integrazione. Approvi la creazione dell’app nel bot e l’agente riceve un token con permessi limitati, senza che tu debba copiarlo a mano. Controlla e prova l’integrazione prima di accettare pagamenti reali.

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:

Un agente che supporta MCP remoto — incolla questo prompt:
```
Collega il server MCP di tgpay (https://app.tgpaycrypto.com/mcp) e integra i pagamenti tramite la Merchant API di TgPay Crypto.
```
È pronto da copiare nell’app, sotto Altro → Merchant API → Collega un agente AI.
Claude Code — claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
claude.ai e Claude Desktop — aggiungi l’URL come connettore personalizzato seguendo le istruzioni di Claude.
ChatGPT e altri client MCP — aggiungi l’URL come server MCP personalizzato, se il tuo account e il tuo spazio di lavoro lo consentono. Per ChatGPT, segui le istruzioni aggiornate.

Per sviluppare prima sulla testnet, usa https://testnet.tgpaycrypto.com/mcp. Il link di approvazione apre @tgpaycrypto_testnet_bot e la documentazione API indica l’URL di base della testnet.

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, crea un token con i soli permessi necessari all’agente e usalo per l’integrazione. Conserva il token principale sul tuo server. Le azioni che l’agente può eseguire dipendono dai permessi del token che gli fornisci.

Approvare l’app

Chiedi all’agente di configurare i pagamenti. Legge la documentazione e ti chiede l’approvazione.
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.
Torna dall’agente perché possa recuperare il token e continuare l’integrazione. Per creare un’app, l’account deve soddisfare i requisiti: completa la verifica se richiesta.

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 token rilasciato con questa procedura di approvazione non può inviare trasferimenti, creare buoni o rimborsare pagamenti (vedi sotto). Un token fornito manualmente può avere permessi diversi. 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 rilasciato con la procedura di approvazione descritta sopra è 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. Per queste operazioni servono rispettivamente gli ambiti payouts, checks o refunds, oppure il token principale ad accesso completo. Il token rilasciato da questa procedura non ha nessuno di questi ambiti.

Mantieni riservato anche questo token: i suoi permessi consentono comunque di modificare fatture, piani di abbonamento e URL del webhook. 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 controllare i permessi del token dell’agente o revocarlo, apri Altro → Merchant API, trova l’app, apri Accesso e token e guarda sotto Token con permessi limitati: Revoca lo disattiva all’istante. L’app, il suo saldo e lo storico dei pagamenti restano. Il valore del token non può essere visualizzato di nuovo. Un token con una scadenza smette di funzionare anche alla scadenza.

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. Chiedigli di scrivere il codice di verifica e lasciare un segnaposto — qualcosa come TGPAY_WEBHOOK_TOKEN — da riempire.

Per riempirlo: apri Altro → Merchant API, trova l’app creata dall’agente, apri Accesso e token, 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.