Connect an AI agent

Connect an AI coding agent that supports remote MCP servers to https://app.tgpaycrypto.com/mcp. It can read the API docs, request a merchant app, configure webhooks and help write your integration. You approve app creation in the bot; the agent receives a restricted token without you copying it by hand. Review and test the resulting integration before accepting real payments.

That URL is an MCP server (Model Context Protocol — the standard way to plug a service into an AI agent). Open it in a browser and it explains its own setup.

Connect it

Use whichever line matches your tool:

• An agent with remote MCP support — paste this prompt:

  Connect the tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay Crypto Merchant API.

  You can also copy a setup prompt in the app under More → Merchant API → Connect an AI agent.
• Claude Code — claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
• claude.ai and Claude Desktop — add the URL as a custom connector using Claude’s setup instructions.
• ChatGPT and other MCP clients — add the URL as a custom MCP server if your account and workspace allow it. For ChatGPT, follow the current setup instructions.

To build against the testnet first, use https://testnet.tgpaycrypto.com/mcp instead. The approval link opens @tgpaycrypto_testnet_bot, and the API docs use the testnet base URL.

You don’t need an API token first — the agent gets its own in the next step. If you already created an app manually, create a restricted token with only the permissions the agent needs and use it for the integration. Keep the main token on your server. Whatever token the agent holds, through the MCP server it can only take payments in (below).

To hand such a token to the MCP server, add the server with the header TgPayCrypto-API-Token: <token> (or Authorization: Bearer <token>) in your client’s connection settings — then no approval step is needed. Not every client has a field for custom headers (the claude.ai and ChatGPT connectors don’t, and the server has no OAuth sign-in); there, use the approval flow below. An agent can also pass a token as the api_token argument of a single tool call, if its client lets it send an argument the tool doesn’t declare.

Approve the app

1. Ask the agent to set up payments. It reads the docs and asks for approval.
2. The agent gives you a t.me link. Open it — the bot shows what’s being requested — and tap ✅ Create app and issue token.
3. Go back to the agent so it can retrieve its token and continue the integration.

The app and the agent’s token are created when the agent next checks the request after your tap — usually within seconds. The request remains valid for 10 minutes from the moment the agent creates it: if the agent doesn’t check in time, nothing is created, even though the bot already confirmed your tap, and the agent has to start over. App creation requires an eligible account; if verification is needed, the agent gets an error at that check — complete verification and have the agent check again within the same 10 minutes, or start over.

Approving the request accepts the Merchant API terms for the app it creates — just as when you create a merchant app yourself in the Mini App.

The link always comes from your agent — the bot never sends one unprompted: until you open it, the bot doesn’t know whose account the agent is asking about. Until you tap a button, opening the link again shows the same request; after you tap ✅ Create app and issue token or ❌ Decline, or after 10 minutes have elapsed, the link stops working. If it stops working before you tap it, ask the agent to start over — nothing is created until you approve.

If you tap ❌ Decline, nothing is created either, and that request is over — a change of mind means a fresh request from the agent.

⚠️ Approve only a request you started

A connection request is a request to create an app on your account. Approve it only if you just asked your own agent to set up payments. If a link arrives any other way — a chat, a forwarded message, a stranger’s “support” — decline it.

Through the MCP server, no token — the one issued by this approval flow included — can send transfers, create checks or refund payments (below). An app you didn’t ask for has no business existing on your account.

What the agent can and can’t do

The token issued through the approval flow above is a restricted token:

• It can create and delete invoices, create and archive subscription plans, cancel a subscriber’s subscription, read your balance, rates and stats, and change the webhook URL and the app’s name.
• It can’t send transfers, issue checks or refund payments: it has none of the payouts, checks or refunds scopes.

The MCP server adds a second barrier of its own: its money-out tools — transfer, transferBatch, createCheck and refundInvoice — are currently switched off. The agent doesn’t see them, and a call is rejected whatever token it holds, a full-access main token included. So neither a leaked agent token nor a malicious instruction hidden in text the agent reads (a payer’s comment, for example) can move money out of your app through MCP.

Payouts, checks and refunds remain available through the API directly: call /pay/api from your own server code with a token that has the corresponding payouts, checks or refunds scope. For payouts, you can also use the app: open More → Merchant API, choose your app, then Payouts.

Keep this token private: its permissions still allow changes to invoices, subscription plans, subscriptions, the webhook URL and the app’s name. You get a message from the bot whenever a token is issued to an agent, and whenever an app’s webhook URL changes.

To review the agent’s token permissions or revoke it, open More → Merchant API, find the app, open Access and tokens and look under Restricted tokens — Revoke kills it instantly. The app itself, its balance and its payment history stay. The token value cannot be viewed again. A token with an expiry date also stops working when it expires.

Webhook signatures need your main token

The agent can point the webhook URL at your server, but it can’t verify what arrives there: deliveries are signed with your app’s main token, which the agent never sees. Ask the agent to write the verification code and leave a placeholder — something like TGPAY_WEBHOOK_TOKEN — to fill in.

To fill it: open More → Merchant API, find the app the agent created, open Access and tokens, tap Rotate token, confirm with your PIN or Face ID and copy what’s shown — it appears only once. An app created through the agent may live on an account without a PIN: rotation needs one, so set it in Security first and wait until it becomes active. Put the token in your server’s environment, never in the agent’s config or your repository. Rotation doesn’t touch the agent’s restricted token, so the integration keeps running.

Signatures switch to the new token the moment you rotate, so rotate before you go live rather than after your first real payment.

Next

• Getting started as a developer — the manual path, and how to manage an app once it exists.
• API reference: webhooks — payload shapes, retries and the signature check.
• Merchant API reference — every method, including the ones an agent can’t call.