Conectar um agente de IA · TgPay Crypto API

Conecte um agente de programação com IA que aceite servidores MCP remotos a https://app.tgpaycrypto.com/mcp. Ele pode ler a documentação da API, solicitar a criação de um app de comerciante, configurar webhooks e ajudar a escrever a integração. Você aprova a criação do app no bot, e o agente recebe um token restrito sem que você precise copiá-lo manualmente. Revise e teste a integração antes de aceitar pagamentos reais.

Essa URL é de um servidor MCP (Model Context Protocol — a forma padrão de conectar um serviço a um agente de IA). Abra o endereço no navegador para ver as instruções de configuração.

Como conectar

Use a linha que corresponde à sua ferramenta:

Um agente com suporte a MCP remoto — cole este prompt:
```
Connect the tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay Crypto Merchant API.
```
Você também pode copiar um prompt de configuração em Mais → API para comerciantes → Conectar um agente de IA.
Claude Code — claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
claude.ai e Claude Desktop — adicione a URL como um conector personalizado seguindo as instruções de configuração do Claude.
ChatGPT e outros clientes MCP — adicione a URL como um servidor MCP personalizado se sua conta e seu espaço de trabalho permitirem. No ChatGPT, siga as instruções atuais de configuração.

Para montar a integração primeiro na testnet, use https://testnet.tgpaycrypto.com/mcp. O link de aprovação abre o @tgpaycrypto_testnet_bot, e a documentação da API usa a URL base da testnet.

Você não precisa criar um token de API antes: o agente recebe o dele na etapa seguinte. Se você já criou um app manualmente, crie um token restrito apenas com as permissões de que o agente precisa e use esse token na integração. Guarde o token principal no seu servidor. Pelo servidor MCP, o agente só pode receber pagamentos, seja qual for o token usado (veja abaixo).

Para fornecer esse token ao servidor MCP, adicione o servidor nas configurações de conexão do seu cliente com o cabeçalho TgPayCrypto-API-Token: <token> (ou Authorization: Bearer <token>). Nesse caso, a etapa de aprovação não é necessária. Nem todo cliente tem um campo para cabeçalhos próprios (os conectores do claude.ai e do ChatGPT não têm, e o servidor não oferece login via OAuth); nesses casos, use a aprovação descrita abaixo. O agente também pode passar um token no argumento api_token de uma chamada de ferramenta, se o cliente permitir enviar um argumento que a ferramenta não declara.

Aprove o app

Peça ao agente para configurar os pagamentos. Ele lê a documentação e pede sua aprovação.
O agente te manda um link t.me. Abra o link — o bot mostra o que está sendo pedido — e toque em ✅ Criar app e emitir token.
Volte para o agente para que ele obtenha o token e continue a integração.

O app e o token do agente são criados quando o agente consulta a solicitação de novo depois do seu toque — normalmente em poucos segundos. A solicitação vale por 10 minutos a partir do momento em que o agente a cria: se o agente não consultar a tempo, nada é criado, mesmo que o bot já tenha confirmado o seu toque, e o agente precisa começar de novo. A criação do app exige uma conta elegível; se for necessária a verificação, o agente recebe um erro nessa consulta — conclua a verificação e peça ao agente para consultar de novo dentro dos mesmos 10 minutos, ou para começar de novo.

Ao aprovar a solicitação, você aceita os termos da API para comerciantes para o app que ela cria, assim como ao criar um app pela Mini App.

O link sempre vem do seu agente, nunca do bot por conta própria: enquanto você não abre o link, o bot não sabe de qual conta o agente está falando. Enquanto você não tocar em nenhum botão, abrir o link de novo mostra a mesma solicitação; depois de tocar em ✅ Criar app e emitir token ou ❌ Rejeitar, ou depois de 10 minutos, o link para de funcionar. Se ele parar de funcionar antes de você tocar, peça ao agente para começar de novo — nada é criado até você aprovar.

Se você tocar em ❌ Rejeitar, também não é criado nada, e aquele pedido acaba ali: mudar de ideia significa um pedido novo, feito pelo agente.

⚠️ Aprove só um pedido que partiu de você

Um pedido de conexão é um pedido para criar um app na sua conta. Aprove só se você acabou de pedir ao seu próprio agente para configurar pagamentos. Se um link chegar por qualquer outro caminho — uma conversa, uma mensagem encaminhada, um “suporte” que você não procurou —, rejeite.

Pelo servidor MCP, nenhum token permite enviar transferências, criar cheques ou reembolsar pagamentos — nem mesmo o token emitido por esse fluxo de aprovação (veja abaixo). Um app que você não pediu não tem por que existir na sua conta.

O que o agente pode e não pode fazer

O token emitido pelo fluxo de aprovação acima é um token restrito:

Ele pode criar e excluir faturas, criar e arquivar planos de assinatura, cancelar a assinatura de um assinante, consultar seu saldo, as cotações e as estatísticas, e alterar a URL de webhook e o nome do app.
Ele não pode enviar transferências, emitir cheques nem reembolsar pagamentos: o token não tem os escopos payouts, checks ou refunds.

O servidor MCP também impõe uma restrição própria: as ferramentas que enviam saldo do app — transfer, transferBatch, createCheck e refundInvoice — estão desativadas no momento. O agente não as vê, e qualquer chamada é rejeitada, mesmo com o token principal de acesso total. Assim, nem um token do agente que vazou nem uma instrução maliciosa escondida em um texto que ele lê, como o comentário de um pagador, permite enviar saldo do seu app pelo MCP.

Transferências, cheques e reembolsos continuam disponíveis diretamente pela API: use /pay/api no código do seu servidor, com um token que tenha o escopo payouts, checks ou refunds, conforme a operação. Para fazer pagamentos, você também pode abrir Mais → API para comerciantes no app, escolher seu app e tocar em Pagamentos.

Mantenha esse token em segredo: as permissões dele ainda permitem alterar faturas, planos de assinatura, assinaturas, a URL de webhook e o nome do app. O bot avisa sempre que um token é emitido para um agente e quando a URL de webhook de um app muda.

Para consultar as permissões ou revogar o token do agente, abra Mais → API para comerciantes, encontre o app, abra Acesso e tokens e consulte Tokens restritos — Revogar desativa o token na hora. O app, o saldo e o histórico de pagamentos continuam disponíveis. O valor do token não pode ser consultado novamente. Um token com data de expiração também deixa de funcionar quando expira.

A assinatura do webhook precisa do seu token principal

O agente consegue apontar a URL de webhook para o seu servidor, mas não consegue verificar o que chega lá: as entregas são assinadas com o token principal do seu app, que o agente nunca vê. Peça ao agente para escrever o código de verificação e deixar um campo para você preencher, como TGPAY_WEBHOOK_TOKEN.

Para preencher: abra Mais → API para comerciantes, encontre o app que o agente criou, abra Acesso e tokens, toque em Rotacionar token e copie o que aparecer — ele é mostrado uma vez só. Guarde no ambiente do seu servidor, nunca na configuração do agente nem no seu repositório. A rotação não mexe no token restrito do agente, então a integração continua rodando. Confirme a rotação com seu PIN ou Face ID. Um app criado pelo agente pode pertencer a uma conta sem PIN, mas a rotação exige um PIN ativo. Configure-o primeiro em Segurança e aguarde a ativação.

As assinaturas passam a usar o token novo no instante em que você rotaciona, então rotacione antes de entrar no ar, e não depois do primeiro pagamento de verdade.

A seguir

Primeiros passos para desenvolvedores — o caminho manual, e como gerenciar um app depois que ele existe.
Referência da API: webhooks — formatos de payload, novas tentativas e a checagem de assinatura.
Referência da API para comerciantes — todos os métodos, inclusive os que um agente não pode chamar.