Collegare un agente AI

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 serve avere già un token API: l’agente riceve il suo nel 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. Tramite il server MCP, l’agente può solo ricevere pagamenti, qualunque token usi (vedi sotto).

Per fornire questo token al server MCP, aggiungi il server nelle impostazioni di connessione del client con l’intestazione TgPayCrypto-API-Token: <token> (o Authorization: Bearer <token>). In questo caso non serve il passaggio di approvazione. Non tutti i client hanno un campo per le intestazioni personalizzate (i connettori di claude.ai e ChatGPT non ce l’hanno, e il server non offre l’accesso tramite OAuth); in quel caso usa l’approvazione descritta sotto. L’agente può anche passare un token come argomento api_token di una singola chiamata a uno strumento, se il suo client gli permette di inviare un argomento che lo strumento non dichiara.

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 perché possa recuperare il token e continuare l’integrazione.

L’app e il token dell’agente vengono creati quando l’agente ricontrolla la richiesta dopo il tuo tocco, di solito entro pochi secondi. La richiesta resta valida per 10 minuti da quando l’agente la crea: se l’agente non la controlla in tempo, non viene creato niente, anche se il bot ha già confermato di aver ricevuto la tua approvazione, e l’agente deve ricominciare. Per creare un’app, l’account deve soddisfare i requisiti; se serve una verifica, l’agente riceve un errore a quel controllo: completa la verifica e chiedi all’agente di ricontrollare entro gli stessi 10 minuti, oppure di ricominciare.

Approvando la richiesta accetti le condizioni della Merchant API per l’app che viene creata, proprio come quando crei un’app nella Mini App.

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. Finché non tocchi un pulsante, riaprire il link mostra la stessa richiesta; dopo ✅ Crea l’app e rilascia il token o ❌ Rifiuta, oppure dopo 10 minuti, il link smette di funzionare. 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.

Tramite il server MCP, nessun token permette di inviare trasferimenti, creare buoni o rimborsare pagamenti, nemmeno quello rilasciato con questa procedura di approvazione (vedi sotto). 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 ed eliminare fatture, creare e archiviare piani di abbonamento, annullare l’abbonamento di un abbonato, leggere saldo, tassi e statistiche, e cambiare l’URL del webhook e il nome dell’app.
• Non può inviare trasferimenti, emettere buoni o rimborsare pagamenti: il token non ha gli ambiti payouts, checks o refunds.

Il server MCP impone anche un proprio limite: gli strumenti che inviano denaro dal saldo dell’app — transfer, transferBatch, createCheck e refundInvoice — sono attualmente disattivati. L’agente non li vede e ogni chiamata viene respinta, anche con il token principale ad accesso completo. Quindi né un token dell’agente finito in mani altrui né un’istruzione dannosa nascosta in un testo che legge, come il commento di chi paga, permettono di inviare denaro dalla tua app tramite MCP.

Trasferimenti, buoni e rimborsi restano disponibili direttamente tramite API: chiama /pay/api dal codice del tuo server con un token che abbia l’ambito payouts, checks o refunds, a seconda dell’operazione. Per inviare pagamenti puoi anche aprire Altro → Merchant API, scegliere la tua app e toccare Pagamenti.

Mantieni riservato anche questo token: i suoi permessi consentono comunque di modificare fatture, piani di abbonamento, abbonamenti, URL del webhook e nome dell’app. 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. Conferma la rigenerazione con il PIN o Face ID. Un’app creata tramite l’agente può appartenere a un account senza PIN, ma per rigenerare il token serve un PIN attivo. Impostalo prima in Sicurezza e attendi che diventi attivo.

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.