اتصال یک عامل هوش مصنوعی

یک عامل کدنویسی هوش مصنوعی با پشتیبانی از سرور MCP راه دور را به https://app.tgpaycrypto.com/mcp وصل کنید. عامل می‌تواند مستندات API را بخواند، درخواست ساخت برنامه پذیرنده بدهد، وب‌هوک را تنظیم کند و در نوشتن کد یکپارچه‌سازی کمک کند. شما ساخت برنامه را در ربات تأیید می‌کنید؛ عامل بدون کپی دستی، توکن محدودی دریافت می‌کند. پیش از پذیرش پرداخت واقعی، یکپارچه‌سازی را بازبینی و آزمایش کنید.

آن آدرس یک سرور MCP است (Model Context Protocol — روش استاندارد وصل کردن یک سرویس به عامل هوش مصنوعی). اگر آن را در مرورگر باز کنید، خودش نحوه‌ی راه‌اندازی را توضیح می‌دهد.

وصل کردن

روش متناسب با ابزار خود را انتخاب کنید:

• عامل با پشتیبانی از MCP راه دور — این متن را جای‌گذاری کنید:

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

  همین متن در برنامه، زیر بیشتر ← API پذیرنده ← اتصال یک عامل هوش مصنوعی، آماده‌ی کپی است.

• Claude Code — claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp

• claude.ai و Claude Desktop — آدرس را طبق راهنمای راه‌اندازی Claude به‌عنوان کانکتور سفارشی اضافه کنید.

• ChatGPT و دیگر کلاینت‌های MCP — اگر حساب و فضای کاری شما اجازه می‌دهد، آدرس را به‌عنوان سرور MCP سفارشی اضافه کنید. برای ChatGPT، راهنمای فعلی راه‌اندازی را دنبال کنید.

برای شروع در شبکه آزمایشی، از https://testnet.tgpaycrypto.com/mcp استفاده کنید. لینک تأیید، @tgpaycrypto_testnet_bot را باز می‌کند و مستندات API از آدرس پایه شبکه آزمایشی استفاده می‌کنند.

لازم نیست از قبل توکن API داشته باشید؛ عامل در مرحله‌ی بعد توکن خودش را می‌گیرد. اگر پیش‌تر دستی برنامه ساخته‌اید، توکن محدودی فقط با دسترسی‌های لازم برای عامل بسازید و از آن برای یکپارچه‌سازی استفاده کنید. توکن اصلی را روی سرور خود نگه دارید. عامل با هر توکنی که داشته باشد، از طریق سرور MCP فقط می‌تواند پرداخت دریافت کند (توضیح در پایین).

برای دادن این توکن به سرور MCP، سرور را در تنظیمات اتصال کلاینت با هدر TgPayCrypto-API-Token: <token> یا Authorization: Bearer <token> اضافه کنید. در این حالت نیازی به مرحله‌ی تأیید نیست. همه‌ی کلاینت‌ها فیلدی برای هدر سفارشی ندارند (اتصال‌دهنده‌های claude.ai و ChatGPT ندارند و سرور هم ورود با OAuth ندارد)؛ در آن‌ها از روند تأیید پایین استفاده کنید. عامل می‌تواند توکن را در آرگومان api_token یک فراخوانی ابزار هم بفرستد، به شرطی که کلاینتش اجازه دهد آرگومانی فرستاده شود که ابزار تعریف نکرده است.

تأیید برنامه

1. از عامل بخواهید پرداخت را راه‌اندازی کند. مستندات را می‌خواند و از شما تأیید می‌خواهد.
2. عامل یک لینک t.me به شما می‌دهد. آن را باز کنید — ربات نشان می‌دهد چه چیزی درخواست شده — و روی ✅ ساخت برنامه و صدور توکن بزنید.
3. به عامل برگردید تا توکنش را بگیرد و یکپارچه‌سازی را ادامه دهد.

برنامه و توکن عامل وقتی ساخته می‌شوند که پس از زدن دکمه توسط شما، عامل دوباره درخواست را بررسی کند — معمولاً ظرف چند ثانیه. درخواست از لحظه‌ای که عامل آن را می‌سازد 10 دقیقه اعتبار دارد: اگر عامل به‌موقع بررسی نکند، چیزی ساخته نمی‌شود، حتی اگر ربات انتخاب شما را تأیید کرده باشد، و عامل باید از نو شروع کند. حساب باید شرایط ساخت برنامه را داشته باشد؛ اگر احراز هویت لازم باشد، عامل در همان بررسی خطا می‌گیرد — احراز هویت را کامل کنید و از عامل بخواهید در همان 10 دقیقه دوباره بررسی کند یا از نو شروع کند.

با تأیید درخواست، شرایط API پذیرنده را برای برنامه‌ای که ساخته می‌شود می‌پذیرید؛ درست مانند وقتی که خودتان در مینی‌برنامه، برنامه‌ای می‌سازید.

لینک همیشه از خود عامل شما می‌آید — ربات هیچ‌وقت بدون درخواست شما لینکی نمی‌فرستد: تا وقتی آن را باز نکنید، ربات نمی‌داند عامل درباره‌ی حساب چه کسی می‌پرسد. تا روی دکمه‌ای نزده‌اید، باز کردن دوباره‌ی لینک همان درخواست را نشان می‌دهد؛ پس از زدن ✅ ساخت برنامه و صدور توکن یا ❌ رد کردن، یا پس از 10 دقیقه، لینک دیگر کار نمی‌کند. اگر پیش از آنکه روی آن بزنید از کار افتاد، از عامل بخواهید از نو شروع کند — تا تأیید نکنید چیزی ساخته نمی‌شود.

اگر ❌ رد کردن را بزنید هم چیزی ساخته نمی‌شود و آن درخواست تمام است — اگر نظرتان عوض شد، عامل باید درخواست جدیدی بفرستد.

⚠️ فقط درخواستی را تأیید کنید که خودتان شروع کرده‌اید

درخواست اتصال یعنی درخواست ساخت یک برنامه روی حساب شما. فقط وقتی آن را تأیید کنید که همین حالا از عامل خودتان خواسته باشید پرداخت را راه‌اندازی کند. اگر لینکی از راه دیگری رسید — در یک چت، به‌صورت فوروارد، از «پشتیبانیِ» یک غریبه — آن را رد کنید.

هیچ توکنی اجازه‌ی انتقال، ساخت چک یا بازگشت وجه از طریق سرور MCP را ندارد؛ توکن صادرشده از این مسیر تأیید هم مشمول همین محدودیت است (توضیح در پایین). برنامه‌ای که خودتان نخواسته‌اید، جایی روی حساب شما ندارد.

عامل چه کاری می‌تواند انجام دهد و چه کاری نه

توکنی که عامل از مسیر تأیید بالا می‌گیرد یک توکن محدود است:

• می‌تواند صورت‌حساب بسازد و حذف کند، طرح اشتراک بسازد و بایگانی کند، اشتراک یک مشترک را لغو کند، موجودی، نرخ‌ها و آمار شما را بخواند و آدرس وب‌هوک و نام برنامه را تغییر دهد.
• نمی‌تواند دارایی منتقل کند، چک صادر کند یا پرداختی را برگرداند؛ توکن هیچ‌کدام از دسترسی‌های payouts، checks یا refunds را ندارد.

خود سرور MCP هم محدودیت دیگری دارد: ابزارهای ارسال وجه از موجودی برنامه، یعنی transfer، transferBatch، createCheck و refundInvoice، در حال حاضر غیرفعال‌اند. عامل این ابزارها را نمی‌بیند و درخواست اجرای آن‌ها با هر توکنی، حتی توکن اصلی با دسترسی کامل، رد می‌شود. بنابراین نه با توکن افشاشده‌ی عامل و نه با دستور مخربی که در متنِ خوانده‌شده توسط عامل پنهان شده باشد، مثلاً در توضیح پرداخت‌کننده، نمی‌توان از طریق MCP وجهی از برنامه خارج کرد.

انتقال، ساخت چک و بازگشت وجه همچنان مستقیماً از طریق API امکان‌پذیر است: در کد سرور خود، /pay/api را با توکنی فراخوانی کنید که بسته به عملیات، دسترسی payouts، checks یا refunds داشته باشد. برای ارسال پرداخت از داخل برنامه هم می‌توانید بیشتر ← API پذیرنده را باز کنید، برنامه‌ی خود را انتخاب کنید و وارد پرداخت‌ها شوید.

این توکن را محرمانه نگه دارید؛ دسترسی‌های آن همچنان امکان تغییر صورت‌حساب‌ها، طرح‌های اشتراک، اشتراک‌ها، آدرس وب‌هوک و نام برنامه را می‌دهند. هر بار که توکنی به یک عامل داده شود و هر بار که آدرس وب‌هوک برنامه‌ای عوض شود، ربات به شما پیام می‌دهد.

برای بررسی دسترسی‌ها یا ابطال توکن عامل، بیشتر ← API پذیرنده را باز کنید، برنامه را پیدا کنید، دسترسی و توکن‌ها را باز کنید و بخش توکن‌های محدود را ببینید — ابطال آن را بی‌درنگ از کار می‌اندازد. خود برنامه، موجودی و تاریخچه‌ی پرداخت‌هایش حفظ می‌شوند. مقدار توکن دوباره نمایش داده نمی‌شود. توکن دارای تاریخ انقضا هم پس از انقضا از کار می‌افتد.

امضای وب‌هوک به توکن اصلی شما نیاز دارد

عامل می‌تواند آدرس وب‌هوک را روی سرور شما تنظیم کند، اما نمی‌تواند آنچه را که به آنجا می‌رسد بررسی کند: ارسال‌ها با توکن اصلی برنامه‌ی شما امضا می‌شوند و عامل هرگز آن را نمی‌بیند. از عامل بخواهید کد بررسی امضا را بنویسد و یک جای خالی — چیزی مثل TGPAY_WEBHOOK_TOKEN — بگذارد تا آن را پر کنید.

برای پر کردن آن: بیشتر ← API پذیرنده را باز کنید، برنامه‌ای را که عامل ساخته پیدا کنید، دسترسی و توکن‌ها را باز کنید، روی تعویض توکن بزنید و آنچه را نشان داده می‌شود کپی کنید — فقط یک بار دیده می‌شود. آن را در متغیرهای محیطی سرورتان بگذارید، هرگز در پیکربندی عامل یا مخزن کدتان. تعویض به توکن محدود عامل دست نمی‌زند، پس یکپارچه‌سازی بی‌وقفه کار می‌کند. تعویض توکن را با پین یا Face ID تأیید کنید. برنامه‌ای که عامل ساخته ممکن است متعلق به حسابی بدون پین باشد، اما تعویض توکن به پین فعال نیاز دارد. ابتدا آن را در امنیت تنظیم کنید و تا فعال شدنش صبر کنید.

از همان لحظه‌ی تعویض، امضاها با توکن جدید انجام می‌شوند، پس بهتر است پیش از راه‌اندازی نهایی تعویض کنید، نه بعد از اولین پرداخت واقعی.

در ادامه

• شروع کار برای توسعه‌دهنده‌ها — مسیر دستی و اینکه بعد از ساخت برنامه چطور آن را مدیریت کنید.
• مرجع API: وب‌هوک‌ها — شکل محتواها، تلاش‌های دوباره و بررسی امضا.
• مرجع API پذیرنده — همه‌ی متدها، از جمله آن‌هایی که عامل نمی‌تواند فراخوانی کند.