AIエージェントを連携する

リモートMCPサーバーに対応するコーディングエージェントを、https://app.tgpaycrypto.com/mcpに接続できます。エージェントはAPIドキュメントを読み、加盟店アプリの作成を申請し、Webhookの設定や連携コードの作成を手伝います。ボットでアプリの作成を承認すると、トークンを手でコピーせずに、エージェントに制限付きトークンを渡せます。実際の決済を受け付ける前に、完成した実装を確認してテストしてください。

このURLはMCPサーバーです（Model Context Protocol、サービスをAIエージェントにつなぐための標準です）。ブラウザで開くと、設定のしかたが書いてあります。

接続する

使っているツールに合わせて、次のどれかを使ってください。

リモートMCP対応のエージェント：次のプロンプトを貼り付けます。
```
Connect the tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay Crypto Merchant API.
```
このプロンプトは、アプリのその他 → Merchant API → AIエージェントを連携からコピーできます。
Claude Code：claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
claude.aiとClaude Desktop：Claudeの設定手順に従い、カスタムコネクターとしてURLを追加します。
ChatGPTやほかのMCPクライアント：アカウントとワークスペースで許可されている場合、カスタムMCPサーバーとしてURLを追加します。ChatGPTでは現在の設定手順をご覧ください。

まずテストネットで開発する場合は、https://testnet.tgpaycrypto.com/mcpを使います。承認リンクは@tgpaycrypto_testnet_botを開き、APIドキュメントにはテストネットのベースURLが記載されます。

APIトークンを先に用意する必要はありません。次の手順で、エージェントが自分のトークンを受け取ります。すでに手動でアプリを作成している場合は、エージェントに必要な権限だけを選んで制限付きトークンを発行し、連携に使ってください。メイントークンはサーバーで保管してください。どのトークンを使っていても、MCPサーバー経由では決済の受け付けのみ可能です（下記）。

このトークンをMCPサーバーに渡すには、クライアントの接続設定でサーバーを追加し、ヘッダーにTgPayCrypto-API-Token: <token>またはAuthorization: Bearer <token>を設定します。この場合、承認手順は不要です。ただし、すべてのクライアントに独自ヘッダーの入力欄があるわけではありません（claude.aiとChatGPTのコネクタにはなく、サーバーはOAuthログインに対応していません）。その場合は、下の承認手順を使ってください。エージェントが個別のツール呼び出しでapi_token引数にトークンを渡すこともできますが、ツールで宣言されていない引数をクライアントが送れる場合に限ります。

アプリを承認する

エージェントに決済の設定を頼みます。エージェントはドキュメントを読み、承認を求めてきます。
エージェントがt.meのリンクを渡してきます。開くと、何が求められているかがボットに表示されます。 ✅ アプリを作成してトークンを発行をタップします。
エージェントに戻り、トークンを取得して実装を続けてもらいます。

アプリとエージェントのトークンは、タップのあとにエージェントがリクエストを再確認したときに作成されます。通常は数秒です。リクエストの有効期間は、エージェントが作成してから10分です。その間にエージェントが確認しないと、ボットがタップを受け付けていても何も作成されず、エージェントは最初からやり直す必要があります。アプリの作成には、アカウントが利用条件を満たす必要があります。本人確認が必要な場合は、その確認の時点でエージェントにエラーが返ります。本人確認を完了し、同じ10分以内にエージェントにもう一度確認させるか、最初からやり直してください。

リクエストを承認すると、作成されるアプリについてMerchant APIの利用規約に同意したことになります。Mini Appで自分でアプリを作成する場合と同じです。

リンクは必ずエージェントから届きます。ボットの側から勝手に送ることはありません。リンクを開くまで、ボットはエージェントが誰のアカウントについて尋ねているのかを知りません。ボタンをタップするまでは、リンクを開き直すと同じリクエストが表示されます。✅ アプリを作成してトークンを発行か**❌ 却下**をタップするか、10分が過ぎると、リンクは使えなくなります。タップする前に使えなくなった場合は、エージェントに最初からやり直すよう頼んでください。承認するまで、何も作成されません。

❌ 却下をタップした場合も何も作成されず、その要求はそこで終わりです。気が変わったときは、エージェントから新しく要求を出してもらいます。

⚠️ 自分で始めた要求だけを承認する

接続の要求は、自分のアカウントにアプリを作成する要求です。自分のエージェントに決済の設定を頼んだ直後だけ、承認してください。それ以外の経路でリンクが届いたときは、チャットでも、転送されたメッセージでも、知らない相手からの「サポート」を名乗る連絡でも、却下してください。

MCPサーバー経由では、どのトークンでも送金、送金リンクの作成、返金はできません。この承認手順で発行されるトークンも同様です（下記）。依頼していないアプリの作成は承認しないでください。

エージェントにできること、できないこと

上記の承認手順でエージェントに発行されるのは制限付きトークンです。

できること：請求書の作成と削除、サブスクリプションのプランの作成とアーカイブ、購読者のサブスクリプションの解約、残高・レート・統計の読み取り、Webhook URLとアプリ名の変更です。
できないこと：送金、送金リンクの発行、返金です。このトークンにはpayouts・checks・refundsの権限がありません。

MCPサーバー側にも制限があります。アプリの残高から資金を送るツールである transfer・transferBatch・createCheck・refundInvoiceは、現在無効になっています。エージェントには表示されず、すべての権限を持つメイントークンを使っても呼び出しは拒否されます。そのため、エージェントのトークンが漏えいした場合や、支払者のコメントなど、エージェントが読む文章に不正な指示が埋め込まれた場合でも、MCP経由でアプリから資金を送ることはできません。

送金、送金リンクの作成、返金は、APIを直接使う方法で引き続き利用できます。操作に応じたpayouts・checks・refundsの権限を持つトークンで、サーバーのコードから/pay/apiを呼び出してください。送金はアプリからも行えます。その他 → Merchant APIで対象のアプリを選び、一括送金を開きます。

このトークンも秘密に保管してください。請求書、サブスクリプションのプラン、サブスクリプション、Webhook URL、アプリ名を変更できる権限があります。エージェントにトークンを発行したときと、アプリのWebhook URLが変わったときは、ボットからメッセージが届きます。

エージェントのトークンの権限を確認したり、無効化したりするには、その他 → Merchant APIで対象のアプリを開き、アクセスとトークンの制限付きトークンを確認します。 無効化でその場で使えなくなります。アプリ本体と残高、支払い履歴はそのまま残ります。トークンの値は再表示できません。有効期限が設定されたトークンは、期限を過ぎると使えなくなります。

Webhookの署名にはメイントークンが必要

エージェントはWebhook URLを利用者のサーバーに設定できますが、このトークンでは届いた通知の署名を検証できません。配信に署名するのはアプリのメイントークンで、エージェントはそれを見られないからです。エージェントに検証のコードを書いてもらい、TGPAY_WEBHOOK_TOKENのように、あとから値を設定する箇所を残します。

埋めかたは次のとおりです。 その他 → Merchant APIでエージェントが作成したアプリを開き、アクセスとトークンのトークンを再発行をタップして、表示された値をコピーします。表示は一度だけです。この値はサーバーの環境変数に入れてください。エージェントの設定ファイルやリポジトリには入れないでください。再発行してもエージェントの制限付きトークンには影響しないので、実装はそのまま動き続けます。再発行はPINまたはFace IDで確認してください。エージェントが作成したアプリの所有アカウントには、PINが設定されていない場合もあります。再発行には有効なPINが必要なので、先にセキュリティで設定し、有効になるまで待ってください。

署名は再発行した瞬間に新しいトークンへ切り替わります。最初の本番の支払いを受けたあとではなく、公開する前に再発行してください。

次に

開発者向けのはじめかた：手動で設定する手順と、作成したアプリの管理のしかたです。
APIリファレンス：Webhook：ペイロードの形、再送、署名の検証です。
Merchant APIリファレンス：エージェントが呼べないものも含めた、すべてのメソッドです。