Conectar un agente de IA

Conecta un agente de programación con IA que admita servidores MCP remotos a https://app.tgpaycrypto.com/mcp. Puede leer la documentación de la API, solicitar una app de comerciante, configurar webhooks y ayudarte a escribir la integración. Tú apruebas la creación de la app en el bot; el agente recibe un token restringido sin que tengas que copiarlo a mano. Revisa y prueba la integración antes de aceptar pagos reales.

Esa URL es un servidor MCP (Model Context Protocol, la forma estándar de conectar un servicio a un agente de IA). Ábrela en un navegador y la propia página explica cómo conectarla.

Conéctalo

Usa la opción que corresponda a tu herramienta:

• Un agente compatible con MCP remoto — pega este prompt:

  Conecta el servidor MCP de tgpay (https://app.tgpaycrypto.com/mcp) e integra pagos con la TgPay Crypto Merchant API.

  También puedes copiar un prompt de configuración en Más → API para comerciantes → Conectar un agente de IA.
• Claude Code — claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
• claude.ai y Claude Desktop — agrega la URL como conector personalizado siguiendo las instrucciones de Claude.
• ChatGPT y otros clientes MCP — agrega la URL como servidor MCP personalizado si tu cuenta y tu espacio de trabajo lo permiten. Para ChatGPT, sigue las instrucciones de configuración actuales.

Para desarrollar primero en la red de prueba, usa https://testnet.tgpaycrypto.com/mcp. El enlace de aprobación abre @tgpaycrypto_testnet_bot y la documentación de la API usa la URL base de la red de prueba.

No necesitas un token de API de antemano: el agente obtiene el suyo en el paso siguiente. Si ya creaste una app manualmente, crea un token restringido con solo los permisos que necesita el agente y úsalo para la integración. Guarda el token principal en tu servidor. A través del servidor MCP, el agente solo puede recibir pagos, independientemente del token que use (ver abajo).

Para proporcionar ese token al servidor MCP, agrega el servidor en la configuración de conexión de tu cliente con la cabecera TgPayCrypto-API-Token: <token> (o Authorization: Bearer <token>). Así no necesitas el paso de aprobación. No todos los clientes tienen un campo para cabeceras propias (los conectores de claude.ai y ChatGPT no lo tienen, y el servidor no ofrece inicio de sesión con OAuth); en esos casos, usa la aprobación que se describe más abajo. El agente también puede pasar un token como argumento api_token en una llamada concreta a una herramienta, si su cliente le permite enviar un argumento que la herramienta no declara.

Aprueba la app

1. Pídele al agente que configure los pagos. Lee la documentación y te pide aprobación.
2. El agente te da un enlace de t.me. Ábrelo —el bot te muestra qué se está pidiendo— y toca ✅ Crear app y emitir token.
3. Vuelve al agente para que pueda obtener su token y continuar la integración.

La app y el token del agente se crean cuando el agente vuelve a consultar la solicitud después de que tocas el botón, normalmente en unos segundos. La solicitud es válida durante 10 minutos desde que el agente la crea: si el agente no la consulta a tiempo, no se crea nada, aunque el bot ya haya confirmado que tocaste el botón, y el agente tiene que empezar de nuevo. Tu cuenta debe cumplir los requisitos para crear una app; si hace falta verificación, el agente recibe un error en esa consulta: completa la verificación y pide al agente que vuelva a consultar dentro de los mismos 10 minutos, o que empiece de nuevo.

Al aprobar la solicitud, aceptas las condiciones de la API para comerciantes para la app que se crea, igual que al crear una app desde la Mini App.

El enlace siempre viene de tu agente, nunca del bot por su cuenta: hasta que lo abres, el bot no sabe de qué cuenta está hablando el agente. Mientras no toques ningún botón, abrir el enlace otra vez muestra la misma solicitud; después de tocar ✅ Crear app y emitir token o ❌ Rechazar, o pasados 10 minutos, el enlace deja de funcionar. Si deja de funcionar antes de que lo toques, pídele al agente que empiece de nuevo: no se crea nada hasta que apruebas.

Si tocas ❌ Rechazar, tampoco se crea nada y esa solicitud queda cerrada: si cambias de opinión, el agente tiene que mandar una solicitud nueva.

⚠️ Aprueba solo lo que pediste tú

Una solicitud de conexión es una solicitud para crear una app en tu cuenta. Apruébala solo si acabas de pedirle a tu propio agente que configure los pagos. Si el enlace te llega por cualquier otra vía —un chat, un mensaje reenviado, el “soporte” de un desconocido—, recházala.

A través del servidor MCP, ningún token permite enviar transferencias, crear cheques ni reembolsar pagos, incluido el que se emite mediante esta aprobación (ver abajo). Una app que no pediste no tiene por qué existir en tu cuenta.

Qué puede y qué no puede hacer el agente

El token que se emite mediante la aprobación anterior es un token restringido:

• Puede crear y eliminar facturas, crear y archivar planes de suscripción, cancelar la suscripción de un suscriptor, leer tu saldo, los tipos de cambio y las estadísticas, y cambiar la URL del webhook y el nombre de la app.
• No puede enviar transferencias, emitir cheques ni reembolsar pagos: el token no tiene los ámbitos payouts, checks ni refunds.

El servidor MCP también aplica su propia restricción: las herramientas que permiten enviar saldo de la app — transfer, transferBatch, createCheck y refundInvoice — están desactivadas por ahora. El agente no las ve y cualquier llamada se rechaza, incluso con el token principal de acceso completo. Por eso, ni un token del agente filtrado ni una instrucción maliciosa oculta en un texto que lea, como el comentario de un pagador, permiten sacar saldo de tu app a través de MCP.

Las transferencias, los cheques y los reembolsos siguen disponibles directamente por la API: llama a /pay/api desde el código de tu servidor con un token que tenga el ámbito payouts, checks o refunds, según la operación. Para enviar pagos, también puedes abrir Más → API para comerciantes, elegir tu app y entrar en Pagos.

Mantén este token en secreto: sus permisos permiten modificar facturas, planes de suscripción, suscripciones, la URL del webhook y el nombre de la app. El bot te avisa cada vez que se le emite un token a un agente y cada vez que cambia la URL del webhook de una app.

Para revisar los permisos del token del agente o revocarlo, abre Más → API para comerciantes, busca la app, abre Acceso y tokens y mira en Tokens restringidos: Revocar lo anula al instante. La app, su saldo y su historial de pagos se conservan. El valor del token no se puede volver a consultar. Si el token tiene una fecha de vencimiento, también deja de funcionar al vencer.

Las firmas de los webhooks usan tu token principal

El agente puede apuntar la URL del webhook a tu servidor, pero no puede verificar lo que llega ahí: las entregas se firman con el token principal de tu app, que el agente nunca ve. Pídele que escriba el código de verificación y deje una variable —por ejemplo, TGPAY_WEBHOOK_TOKEN— para que introduzcas tú el token.

Para completarla: abre Más → API para comerciantes, busca la app que creó el agente, abre Acceso y tokens, toca Renovar el token y copia lo que aparece: se muestra una sola vez. Guárdalo en las variables de entorno de tu servidor, nunca en la configuración del agente ni en tu repositorio. Renovar el token principal no toca el token restringido del agente, así que la integración sigue funcionando. Confirma la renovación con tu PIN o Face ID. Una app creada por el agente puede pertenecer a una cuenta sin PIN, pero para renovar el token necesitas uno activo. Configúralo primero en Seguridad y espera a que se active.

Las firmas pasan al token nuevo en el momento en que lo renuevas, así que hazlo antes de salir a producción y no después del primer pago real.

Siguiente

• Empezar como desarrollador — el camino manual, y cómo administrar una app una vez que existe.
• Referencia de la API: webhooks — las estructuras de los payloads, los reintentos y la comprobación de la firma.
• Referencia de la API para comerciantes — todos los métodos, incluidos los que un agente no puede llamar.