سرور MCP

OrcaRail یک سرور رسمی Model Context Protocol (MCP) با نام @orcarail/mcp منتشر می‌کند. این سرور به‌صورت محلی و از طریق stdio اجرا می‌شود و روی SDK @orcarail/node ساخته شده است، تا ایجنت‌های کدنویسی هوش مصنوعی مثل Claude Code، Cursor و Codex بتوانند به جای شما payment intent بسازند، اشتراک‌ها را مدیریت کنند، کاتالوگ محصولات را نگه دارند و نرخ تبدیل را بررسی کنند؛ همان مدل توزیع @stripe/mcp استرایپ.

کد منبع: github.com/OrcaRail/mcp

با آن چه کارهایی می‌توانید بکنید

پس از اتصال، می‌توانید از ایجنت چیزهایی مثل این بخواهید:

«یک payment intent بیست‌وپنج دلاری با USDC روی Polygon و آدرس بازگشت https://myapp.com/success بساز و لینک پرداخت را به من بده.»
«اشتراک‌های فعالم را فهرست کن و اشتراک [email protected] را در پایان دوره لغو کن.»
«محصولی به نام Pro Plan با قیمت دوره‌ای ماهانه ۲۹ دلار بساز.»
«الان ۵۰۰ یورو چند USDC می‌شود؟»
«وضعیت payment intent با شناسه 550e8400-… چیست؟»

ایجنت ابزارهای MCP متناظر را فراخوانی می‌کند. ابزارهای عمومی (rates.*، pay.*) به اطلاعات احراز هویت نیاز ندارند؛ ابزارهای خصوصی با کلید و secret API شما در برابر REST API اورکاریل احراز هویت می‌شوند.

پیش‌نیازها

Node.js 18 یا جدیدتر
برای ابزارهای خصوصی: یک کلید و secret API اورکاریل (ak_… / sk_…) از داشبورد
ابزارهای عمومی نرخ‌ها و پرداخت بدون اطلاعات احراز هویت کار می‌کنند

شروع سریع

فقط ابزارهای عمومی (بدون اطلاعات احراز هویت):

npx -y @orcarail/mcp --tools=all

با اطلاعات احراز هویت برای ابزارهای خصوصی (متغیر محیطی را ترجیح دهید):

export ORCARAIL_API_KEY=ak_live_xxx
export ORCARAIL_API_SECRET=sk_live_xxx
npx -y @orcarail/mcp --tools=all

یا فلگ‌ها را بفرستید:

npx -y @orcarail/mcp --tools=all --api-key=ak_live_xxx --api-secret=sk_live_xxx

سرور از طریق stdin/stdout با MCP ارتباط برقرار می‌کند؛ قرار است یک کلاینت MCP آن را اجرا کند (بخش‌های کلاینت را در ادامه ببینید)، نه اینکه به‌صورت تعاملی از آن استفاده شود.

پیکربندی

هر گزینه به‌صورت فلگ CLI یا متغیر محیطی در دسترس است. فلگ‌ها اولویت دارند. برای secretها متغیر محیطی را ترجیح دهید.

فلگ	متغیر محیطی	الزامی	توضیح
`--api-key`	`ORCARAIL_API_KEY`	برای ابزارهای خصوصی	کلید API (`ak_…`)
`--api-secret`	`ORCARAIL_API_SECRET`	برای ابزارهای خصوصی	secret API (`sk_…`)
`--api-base`	`ORCARAIL_API_BASE`	خیر	آدرس پایه API. پیش‌فرض `https://api.orcarail.com/api/v1`
`--organization-id`	`ORCARAIL_ORGANIZATION_ID`	خیر	سازمان پیش‌فرض برای ابزارهای کاتالوگ (`products.`، `prices.`)
`--tools`	—	خیر	`all` (پیش‌فرض) یا فهرستی از نام ابزارها که با ویرگول جدا شده‌اند

محدود کردن ابزارها

به‌طور پیش‌فرض همه ابزارها در دسترس‌اند. با --tools کارهایی را که ایجنت می‌تواند انجام دهد محدود کنید؛ مثلاً فقط خواندن و ساختن، بدون لغو و حذف:

npx -y @orcarail/mcp \
  --tools=payment_intents.create,payment_intents.retrieve,subscriptions.list,rates.get_fiat_quote \
  --api-key=ak_live_xxx --api-secret=sk_live_xxx

نام‌های ناشناخته بی‌صدا نادیده گرفته می‌شوند؛ سرور فقط ابزارهای مطابق را ثبت می‌کند.

API نصب‌شده روی سرور خود یا محلی

--api-base را به استقرار خودتان اشاره دهید:

npx -y @orcarail/mcp --tools=all \
  --api-base=http://127.0.0.1:3000/api/v1 \
  --api-key=ak_test_xxx --api-secret=sk_test_xxx

راه‌اندازی کلاینت

Claude Code

claude mcp add orcarail -- npx -y @orcarail/mcp --tools=all --api-key=ak_live_xxx --api-secret=sk_live_xxx

یا با متغیرهای محیطی secretها را از خط فرمان دور نگه دارید:

claude mcp add orcarail \
  -e ORCARAIL_API_KEY=ak_live_xxx \
  -e ORCARAIL_API_SECRET=sk_live_xxx \
  -- npx -y @orcarail/mcp --tools=all

با claude mcp list بررسی کنید و سپس از Claude Code بخواهید، مثلاً «اشتراک‌های OrcaRail من را فهرست کن».

Cursor

به .cursor/mcp.json در پروژه خود (یا ~/.cursor/mcp.json برای همه پروژه‌ها) اضافه کنید:

{
  "mcpServers": {
    "orcarail": {
      "command": "npx",
      "args": ["-y", "@orcarail/mcp", "--tools=all"],
      "env": {
        "ORCARAIL_API_KEY": "ak_live_xxx",
        "ORCARAIL_API_SECRET": "sk_live_xxx"
      }
    }
  }
}

Cursor سرور را خودکار شناسایی می‌کند؛ در Settings ← MCP بررسی کنید که در حال اجراست.

Codex

به ~/.codex/config.toml اضافه کنید:

[mcp_servers.orcarail]
command = "npx"
args = ["-y", "@orcarail/mcp", "--tools=all"]

[mcp_servers.orcarail.env]
ORCARAIL_API_KEY = "ak_live_xxx"
ORCARAIL_API_SECRET = "sk_live_xxx"

کلاینت‌های MCP دیگر

هر کلاینتی که از سرورهای MCP مبتنی بر stdio پشتیبانی کند با همین ساختار کار می‌کند: دستور npx، آرگومان‌های ["-y", "@orcarail/mcp", "--tools=all"]. اطلاعات احراز هویت (ORCARAIL_API_KEY / ORCARAIL_API_SECRET) برای ابزارهای عمومی اختیاری و برای ابزارهای خصوصی الزامی است. برای Claude Desktop، همان بلوک JSON کرسر را به claude_desktop_config.json اضافه کنید.

live در برابر sandbox

سرور حالت خود را از کلید API تشخیص می‌دهد و از طریق دستورالعمل‌های MCP و ابزار account.get_mode به ایجنت شما اعلام می‌کند:

ak_test_… (سازمان sandbox): فقط شبکه‌های آزمایشی، بدون وجوه واقعی. payment_intents.simulate در دسترس است.
ak_live_…: وجوه واقعی. از ایجنت خواسته می‌شود پیش از هر عملیات نوشتن با شما تأیید بگیرد.
بدون کلید: فقط ابزارهای عمومی.

وقتی با ایجنت می‌سازید از کلید sandbox استفاده کنید.

مرجع ابزارها

نام ابزارها از الگوی resource.action پیروی می‌کند. همه پاسخ‌ها همان اشیای خام API اورکاریل هستند که به JSON تبدیل شده‌اند.

Payment intentها

ابزار	آرگومان‌ها	توضیح
`payment_intents.create`	`return_url` (الزامی)؛ یا `price_id` یا `amount` + `currency` + `tokenId` + `networkId`؛ اختیاری `cancel_url`، `description`، `metadata`، `expires_at`، `payment_method_types`، `withdrawal_addresses`	یک payment intent می‌سازد. intent را همراه `client_secret` و لینک پرداخت برمی‌گرداند
`payment_intents.retrieve`	`id`	وضعیت فعلی را می‌گیرد
`payment_intents.update`	`id` + هر فیلد قابل ویرایش	پیش از تأیید ویرایش می‌کند
`payment_intents.confirm`	`id`، `client_secret`، `return_url`	تأیید و گرفتن آدرس انتقال به صفحه پرداخت میزبانی‌شده
`payment_intents.complete`	`id`	پس از بازگشت مشتری به آدرس موفقیت، در حال پردازش علامت می‌زند
`payment_intents.cancel`	`id`	intent را لغو می‌کند

tokenId و networkId از نوع UUID هستند؛ برای مقادیر زنده شبکه‌ها و توکن‌ها را ببینید.

اشتراک‌ها

ابزار	آرگومان‌ها	توضیح
`subscriptions.create`	`description` (الزامی)؛ یا `price_id` یا `interval` + `amount` + `currency` + `token_id` + `network_id`؛ اختیاری `collection_method`، `total_cycles`، `trial_period_days`، `trial_end`، `payer_email`، `payer_user_id`، `billing_cycle_anchor`، `cancel_at`، `cancel_at_period_end`، `days_until_due`، `interval_count`، `metadata`، `withdrawal_addresses`، `return_url`، `cancel_url`	یک اشتراک دوره‌ای می‌سازد
`subscriptions.retrieve`	`id`	یک اشتراک را می‌گیرد
`subscriptions.update`	`id` + هر فیلد قابل ویرایش، از جمله `pause_collection`	یک اشتراک را ویرایش می‌کند
`subscriptions.cancel`	`id`، `cancellation_details` اختیاری (`comment`، `feedback`)	لغو
`subscriptions.resume`	`id`	اشتراک متوقف را ازسر می‌گیرد
`subscriptions.list`	اختیاری `status`، `collection_method`، فیلترهای بازه‌ای `created`/`current_period_start`/`current_period_end`، `limit`، `starting_after`، `ending_before`	فهرست با صفحه‌بندی cursor
`subscriptions.list_payment_links`	`id`، اختیاری `limit`، `starting_after`، `ending_before`	صورت‌حساب‌های هر دوره (لینک‌های پرداخت) یک اشتراک

کاتالوگ: محصولات

ابزارهای کاتالوگ روی یک سازمان کار می‌کنند. organization_id را در هر فراخوانی بفرستید یا یک بار با --organization-id / ORCARAIL_ORGANIZATION_ID پیش‌فرض تعیین کنید.

ابزار	آرگومان‌ها	توضیح
`products.list`	`organization_id` اختیاری	محصولات را فهرست می‌کند
`products.create`	`name` (الزامی)؛ اختیاری `description`، `active`، `metadata`، `default_price`، `marketing_features` و موارد دیگر	یک محصول می‌سازد
`products.update`	`product_id` + هر فیلد قابل ویرایش	یک محصول را ویرایش می‌کند
`products.delete`	`product_id`	یک محصول را حذف می‌کند

کاتالوگ: قیمت‌ها

ابزار	آرگومان‌ها	توضیح
`prices.list`	اختیاری `organization_id`، `active`، `recurring`، `limit`	قیمت‌ها را فهرست می‌کند
`prices.create`	`unit_amount_decimal`، `currency`، `token_id`، `network_id` (الزامی)؛ `product` یا `product_data` درون‌خطی؛ اختیاری `recurring` (`interval`، `interval_count`، `trial_period_days`)، `nickname`، `lookup_key`، `active`، `metadata`	یک قیمت یک‌باره یا دوره‌ای می‌سازد
`prices.update`	`price_id` + هر فیلد قابل ویرایش	یک قیمت را ویرایش می‌کند
`prices.deactivate`	`price_id`	یک قیمت را غیرفعال می‌کند

نرخ‌ها (عمومی، بدون نیاز به اطلاعات احراز هویت)

ابزار	آرگومان‌ها	توضیح
`rates.get_fiat_quote`	`amount`، `currency`	یک مبلغ فیات را به USD/USDC تبدیل می‌کند
`rates.list_currencies`	`active` اختیاری	ارزهای فیات پشتیبانی‌شده را فهرست می‌کند

پرداخت (صفحات پرداخت میزبانی‌شده، عمومی، بدون نیاز به اطلاعات احراز هویت)

ابزار	آرگومان‌ها	توضیح
`pay.get_by_slug`	`slug`	جزئیات پرداخت را با slug صفحه پرداخت میزبانی‌شده می‌گیرد
`pay.cancel_by_slug`	`slug`	یک payment intent را با slug پرداختش لغو می‌کند

نمونه جریان‌های کاری

ساخت پرداخت و گرفتن لینک پرداخت

از ایجنت بخواهید:

در OrcaRail یک payment intent پنجاه دلاری با USDC روی Polygon و آدرس بازگشت https://myshop.com/thanks بساز، سپس تأییدش کن و آدرس پرداخت مخصوص مشتری را به من بده.

ایجنت payment_intents.create و سپس payment_intents.confirm را با client_secret برگشتی فراخوانی می‌کند و آدرس صفحه پرداخت میزبانی‌شده را گزارش می‌دهد.

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

در OrcaRail محصولی به نام «Pro Plan» با قیمت دوره‌ای ماهانه ۲۹ دلار USDC بساز، سپس با همان قیمت برای [email protected] اشتراک بساز.

ایجنت products.create ← prices.create (با recurring.interval: "month") ← subscriptions.create (با price_id جدید و payer_email) را پشت سر هم اجرا می‌کند.

بررسی یک پرداخت

payment intent با شناسه 550e8400-e29b-41d4-a716-446655440000 را پیدا کن و وضعیت، مبلغ و آخرین تراکنشش را بگو.

مدیریت خطا

خطاهای API به‌صورت خطای ابزار، همراه با وضعیت HTTP، نوع خطا و پیام دست‌نخورده API به ایجنت برگردانده می‌شوند (مثلاً API error (401): [authentication_error]: …). ایجنت‌ها معمولاً این‌ها را می‌خوانند و فراخوانی بعدی را اصلاح می‌کنند؛ هیچ چیز خودکار دوباره امتحان نمی‌شود.

فراخوانی ابزار خصوصی بدون اطلاعات احراز هویت خطای روشنی برمی‌گرداند: ORCARAIL_API_KEY و ORCARAIL_API_SECRET (یا فلگ‌های CLI متناظر) را تنظیم کنید.

امنیت

کلیدها دسترسی کامل به سازمان متصل به کلید API می‌دهند. با فایل‌های پیکربندی MCP به همان دقت فایل‌های .env رفتار کنید.
متغیرهای محیطی را به آرگومان‌های درون‌خطی --api-key=… ترجیح دهید تا secretها در تاریخچه shell یا پیکربندی commitشده نمانند.
هرگز کلید live را commit نکنید. اگر از .cursor/mcp.json در سطح پروژه استفاده می‌کنید، کلید را بیرون از git نگه دارید (از ارجاع به متغیر محیطی یا فایل فقط محلی استفاده کنید).
با --tools محدود کنید. فقط عملیاتی را که ایجنت لازم دارد در دسترس بگذارید؛ مثلاً برای جریان‌های عمدتاً خواندنی products.delete و subscriptions.cancel را کنار بگذارید.
در توسعه از کلیدهای آزمایشی استفاده کنید و هر کلیدی را که ممکن است افشا شده باشد از داشبورد عوض کنید.

عیب‌یابی

نشانه	راه‌حل
`Missing credentials for this tool`	برای ابزارهای خصوصی `ORCARAIL_API_KEY`/`ORCARAIL_API_SECRET` (یا `--api-key`/`--api-secret`) را تنظیم کنید
`Authentication error` در همه فراخوانی‌ها	جفت کلید/secret را در داشبورد بررسی کنید؛ مطمئن شوید اطلاعات آزمایشی و live را با هم مخلوط نکرده‌اید
`organization_id is required`	`organization_id` را در فراخوانی ابزار بفرستید یا با `--organization-id` اجرا کنید
ابزاری در کلاینت نیست	فیلتر `--tools` را بررسی کنید؛ نام‌ها باید دقیقاً مطابق باشند (مثلاً `payment_intents.create`)
کلاینت نمی‌تواند سرور را اجرا کند	مطمئن شوید Node.js 18+ در PATH مورد استفاده کلاینت هست؛ `npx -y @orcarail/mcp --help` را در ترمینال امتحان کنید

با آن چه کارهایی می‌توانید بکنید​

پیش‌نیازها​

شروع سریع​

پیکربندی​

محدود کردن ابزارها​

API نصب‌شده روی سرور خود یا محلی​

راه‌اندازی کلاینت​

Claude Code​

Cursor​

Codex​

کلاینت‌های MCP دیگر​

live در برابر sandbox​

مرجع ابزارها​

Payment intentها​

اشتراک‌ها​

کاتالوگ: محصولات​

کاتالوگ: قیمت‌ها​

نرخ‌ها (عمومی، بدون نیاز به اطلاعات احراز هویت)​

پرداخت (صفحات پرداخت میزبانی‌شده، عمومی، بدون نیاز به اطلاعات احراز هویت)​

نمونه جریان‌های کاری​

ساخت پرداخت و گرفتن لینک پرداخت​

راه‌اندازی محصول اشتراکی​

بررسی یک پرداخت​

مدیریت خطا​

امنیت​

عیب‌یابی​

مرتبط​