Moyasar MCP Server

Payments for AI agents. A Stripe-style MCP server for Moyasar — Saudi Arabia's payment gateway — that lets Claude create payment links, check transactions, and issue refunds in plain Arabic or English. Built with Skybridge, so every tool renders a live React widget inside the conversation.

No regional payment provider offers this today. This repo is the proof that Moyasar can be first.

<br>

<p align="center"> <img src="docs/assets/payment-link-demo.png" alt="Claude creating a 150 SAR Moyasar payment link — the tool renders a live widget with a scannable QR code and an Open payment page button, right inside the conversation" width="920"> </p>

<p align="center"> <em>One sentence in — a scannable payment link out. Live widget, rendered by this server inside Claude.</em> </p>

---

The demo

Connect the server to Claude and the pitch plays out in five beats — live against Moyasar's sandbox, QR scan and all:

You: Create a 150 SAR payment link for a consultation session.

Claude → moyasar_create_payment_link(amount: 15000, currency: "SAR", description: "Consultation session")

🧾 150.00 SAR — INITIATED Consultation session ▪️▪️▪️ [scannable QR code] ▪️▪️▪️ https://moyasar.com/i/… — scan with a phone, pay with a test card, right there on the call.

You: Has it been paid yet?

Claude → moyasar_fetch_invoice(invoice_id: "…")

🧾 150.00 SAR — PAID ✅ Paid by payment a1b2c3…

You: Show me today's transactions.

Claude → moyasar_list_payments(created_after: "…")

Date	Description	Source	Amount	Status
2026-07-15	Consultation session	visa •••• 1111	150.00 SAR	PAID

You: Refund that payment.

Claude → moyasar_create_refund(payment_id: "…")

💸 Refund complete — payment is REFUNDED, refunded 150.00 SAR

You: How is this account doing this week?

Claude → moyasar_get_account_summary(days: 7)

📊 12 payments · 1,840.00 SAR volume · 8% refund rate

Five sentences. Zero dashboards. That's the pitch.

Why it matters

• Agents are the new integration surface. Stripe ships an MCP server. Every AI assistant that touches money will route through servers like this one. This is Moyasar, AI-native, today.
• Errors teach the agent. Every failure returns recovery guidance instead of a stack trace — "This payment has status 'initiated' — only 'paid' payments can be refunded." The agent self-corrects mid-conversation.
• Card numbers never transit chat. The recommended flow is hosted payment links; the direct-card tool exists for sandbox demos and says so in its own description.

The 11 tools

Tool	What it does
moyasar_create_payment_link	Hosted payment link + QR widget — the flagship flow
moyasar_fetch_invoice	Poll a link: paid or not?
moyasar_list_invoices	All payment links, as a table widget
moyasar_cancel_invoice	Kill an unpaid link
moyasar_create_payment	Direct card charge (sandbox test cards only)
moyasar_fetch_payment	Payment status card
moyasar_list_payments	Transactions table with status/date filters
moyasar_create_refund	Full or partial refund
moyasar_capture_payment	Capture a manual authorization (fetches the hold amount automatically)
moyasar_void_payment	Release a hold without charging
moyasar_get_account_summary	Counts, volume, refund rate — stat-tile dashboard

Design follows our published MCP server design principles: curated responses instead of raw API JSON, tool descriptions written as agent prompts, a focused 11-tool surface, moyasar_ prefixes throughout.

Quick start

npm install
MOYASAR_SECRET_KEY=sk_test_xxx npm run dev          # DevTools on http://localhost:3000
MOYASAR_SECRET_KEY=sk_test_xxx npm run dev:tunnel   # public URL → add as Claude connector

Keys are never hardcoded. Sandbox sk_test_ keys only — sk_live_ is refused unless you explicitly set ALLOW_LIVE=true, so the demo can never accidentally move real money.

npm test        # 28 unit tests, no network
npm run smoke   # real sandbox round-trip: link → fetch → list → cancel (skips without a key)

The full presenter script lives in DEMO.md.

Architecture

Claude ⇄ Skybridge MCP app (11 tools + React widgets)
              └── tool-runner (errors → agent guidance)
                    └── typed Moyasar client (Basic auth, curated responses)
                          └── api.moyasar.com/v1

Productization roadmap (out of scope for the demo)

OAuth per-merchant auth · webhooks/callbacks · Apple Pay / Samsung Pay / STC Pay sources · bulk invoices · hosted deployment.

---

Built by Software Savants.