Run your gateway from Claude, ChatGPT, or Cursor
The official Model Context Protocol server for PayBridgeNP. Issue refunds, create payment links, inspect failed webhooks, pull KPIs - by chatting. Scoped tokens, confirmation prompts on money-moving actions, full audit trail. First-in-Nepal MCP for payments.
{
"mcpServers": {
"paybridge": {
"command": "npx",
"args": ["-y", "@paybridge-np/mcp@latest"],
"env": { "PAYBRIDGE_API_KEY": "sk_live_..." }
}
}
}How it works
Three steps from connect to chat
The MCP server runs locally as an npm package. Your token never leaves your machine. Tool calls go straight to our API over HTTPS - the assistant only sees structured JSON results.
01
Generate a scoped token
From your PayBridgeNP dashboard, open AI / MCP and click Generate token. Pick read-only or grant specific write scopes (refunds, payment links, webhooks, billing). Optionally set a 24-hour spend cap and an expiry date.
02
Paste it into your AI assistant
Drop the snippet into Claude Desktop, Cursor, Claude Code, or VS Code MCP config. The MCP server runs locally as an npm package - your token never leaves your machine, and tool call traffic goes straight to api.paybridgenp.com over HTTPS.
03
Just talk to it
"Refund the last payment from ram@sherpa.com." "Why did webhook delivery #482 fail?" "Show me this week's revenue by provider." The agent picks the right tools, asks for confirmation on money-moving actions, and surfaces results inline.
Install
Drop-in config for every host
Generate a scoped token in your dashboard, paste these snippets, restart your assistant. Done.
{
"mcpServers": {
"paybridge": {
"command": "npx",
"args": ["-y", "@paybridge-np/mcp@latest"],
"env": { "PAYBRIDGE_API_KEY": "sk_live_..." }
}
}
}{
"mcpServers": {
"paybridge": {
"command": "npx",
"args": ["-y", "@paybridge-np/mcp@latest"],
"env": { "PAYBRIDGE_API_KEY": "sk_live_..." }
}
}
}claude mcp add paybridge \
--env PAYBRIDGE_API_KEY=sk_live_... \
-- npx -y @paybridge-np/mcp@latest{
"servers": {
"paybridge": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@paybridge-np/mcp@latest"],
"env": { "PAYBRIDGE_API_KEY": "sk_live_..." }
}
}
}ChatGPT and claude.ai web require remote hosting (OAuth) - shipping next. Track status in the docs.
What you can ask
Real prompts merchants use
The agent figures out the right tool calls. Operations that move money always confirm before executing.
Show me payments above Rs 5,000 from this week, grouped by provider.
Why did the webhook to checkout.acme.com fail yesterday at 3pm?
Refund the last successful payment from customer@example.com.
Create a payment link for Rs 2,500 titled 'Course access - December batch'.
What's my analytics overview for the last 30 days - gross volume, success rate, refunds?
List all subscriptions that are past due, with the customer email.
Pause the subscription for ram@sherpa.com until the end of the month.
Which invoices are currently in dunning? Show retry counts and recommend whether to stop or retry each.
Apply promo code NEPAL20 to subscription sub_abc123 - show the before/after price first.
Preview what the proration charge would be if I upgrade ram@sherpa.com from the Starter to Pro plan.
Give me my end-of-day summary - revenue, failed payments, refunds, and any webhook failures.
Create a coupon for 30% off, valid for 3 months, and apply it to all past-due subscriptions.
Tools
69 tools, scoped per token
Read tools cover payments, refunds, sessions, payment links, webhooks, billing, and analytics. Write tools cover refunds, checkout creation, webhook CRUD, and the entire billing surface - plans, coupons, promotions, tax, dunning, and usage metering.
Read (31 tools)
Inspect payments, refunds, links, sessions, billing, analytics - and the full billing surface: coupons, promotions, dunning, metered usage.
- get_account
- list_payments / get_payment
- list_refunds / get_refund
- list_checkout_sessions / get_checkout_session
- list_payment_links / get_payment_link
- list_webhook_endpoints / list_webhook_deliveries
- list_plans / get_plan
- list_customers / get_customer
- list_subscriptions / get_subscription
- list_invoices / get_invoice
- list_coupons / get_coupon
- list_promotion_codes / get_promotion_code / validate_promotion_code
- get_tax_settings
- list_dunning_policies / get_dunning_invoice_status
- preview_subscription_proration
- get_subscription_usage_summary / list_usage_records
- get_analytics_overview
Write (38 tools)
Issue refunds, create checkout sessions, manage webhooks + the entire billing surface. Money-moving actions always confirm first.
- create_refund (always asks to confirm)
- create_checkout_session (asks above Rs 5,000)
- create_payment_link / update_payment_link / cancel_payment_link / delete_payment_link
- create_webhook_endpoint / update_webhook_endpoint / delete_webhook_endpoint
- create_plan / update_plan
- create_customer / update_customer / add_customer_credit
- create_subscription / pause_subscription / resume_subscription / cancel_subscription
- change_subscription_plan / end_trial / extend_trial
- create_invoice_item / delete_invoice_item
- create_coupon / deactivate_coupon
- create_promotion_code / deactivate_promotion_code
- apply_coupon_to_subscription / remove_subscription_discount
- update_tax_settings
- create_dunning_policy / update_dunning_policy / set_subscription_dunning_policy
- stop_invoice_dunning / retry_invoice_dunning_now
- report_subscription_usage / update_subscription_quantity
Security
Designed so an agent can't bankrupt you
We took the MCP 2025-11-25 spec security guidance, the Stripe + PayPal + Linear MCP designs, and the Anthropic MCP threat model - then layered four overlapping defenses on top.
Scoped tokens
16 scopes grouped Read / Write / Sensitive. Read-only by default, opt in to writes per scope. PII (raw email, phone) is its own scope - masked unless explicitly granted.
Confirmation on money-moving actions
Refunds always ask the user to confirm in the host UI. New checkout sessions above your threshold (default Rs 5,000) require confirmation too. Hosts that don't support MCP elicitation fail closed.
24-hour spend cap
Hard cap on the rolling 24-hour sum of refunds + checkout sessions originated by this token. Auto-prefilled to Rs 50,000 when any write scope is enabled.
Per-token rate limits
60 calls / 60s overall, 6 destructive / 60s, 2 elicitation-gated / 60s. Backed by Upstash Redis. Returns standard 429 with Retry-After.
Full audit trail
Every tool call is recorded against your merchant account, tagged with the token id and the assistant's name (Claude Desktop, Cursor, ChatGPT, etc.). Visible live in your dashboard.
Open source
The MCP server is published as @paybridge-np/mcp on npm and the source lives at github.com/paybridgenp/paybridgenp-mcp. Audit exactly what runs against your key.
No token passthrough
Your Khalti / eSewa secrets are never exposed to the model. Provider credentials stay server-side. The token is the only secret on the host machine and you can revoke it in one click.
Prompt-injection defense
Customer-controlled fields (names, metadata, descriptions) are wrapped as untrusted data when returned to the model. Zero-width characters stripped. Secrets pattern-redacted on the way out.
6 built-in prompt templates
Daily summary, monthly reconciliation, failed-payment investigation, customer onboarding, dunning review, and discount application - all available as slash commands in Claude Desktop and Cursor. No need to remember tool names.
Compatibility
What we support today
Transparent up front: here's exactly what works, what's shipping next.
- Hosts (stdio)
- Claude Desktop, Cursor, Claude Code, VS Code, Continue
- Hosts (remote)
- ChatGPT, claude.ai (coming)
- Transport
- stdio (today), Streamable HTTP + OAuth (next)
- MCP spec version
- 2025-11-25
- Tools
- 69 typed tools (31 read + 38 write)
- Prompts
- 6 built-in templates (daily summary, reconciliation, dunning, and more)
- Cost
- Free - same PayBridgeNP fees apply on actual transactions
- Source
- github.com/paybridgenp/paybridgenp-mcp
- Package
- @paybridge-np/mcp on npm
FAQ
Questions we get a lot
What's the Model Context Protocol?
MCP is an open protocol (originally from Anthropic, now widely adopted) that standardizes how AI assistants talk to external tools and data sources. The PayBridgeNP MCP server lets any MCP-compatible host - Claude Desktop, Cursor, Claude Code, VS Code, ChatGPT - invoke our payment APIs by name, with structured input schemas and JSON results. Spec at modelcontextprotocol.io.
Is this safe? What if the AI does something stupid with my money?
Three layers. (1) Scoped tokens - read-only by default; you grant write scopes per category. (2) Elicitation - every refund and every large checkout session requires the user to explicitly confirm in the host UI before the call executes. (3) Spend cap - hard cap on rolling 24-hour money-moving activity per token. Plus full audit logs and one-click revocation.
Where does the token live?
On your machine, in your AI assistant's config. The MCP server is a local Node process (run via npx) that holds your token and makes HTTPS calls directly to api.paybridgenp.com. The model never sees the token - it only sees tool definitions and JSON results.
Does the AI see my customers' email addresses?
Only if you tick the pii:read scope when issuing the token. By default, customer emails are masked (ra***@example.com) and phones are masked to the last 4 digits. Free-text fields like customer names and metadata are wrapped as untrusted data so the model treats them as input, not instructions.
Which assistants does it work with?
Anything that speaks MCP stdio: Claude Desktop, Cursor, Claude Code, VS Code (with the MCP extension), Continue, and any custom MCP host. ChatGPT and claude.ai web need the remote (HTTP) variant which is shipping next - track the docs page for status.
What does it cost?
Nothing. The MCP server itself is free and open source. You only pay PayBridgeNP's standard transaction fees on actual payments, refunds, etc. - same rates as using the dashboard or REST API directly.
How do I revoke a token if my laptop is stolen?
Go to dashboard.paybridgenp.com/mcp, find the token in the table, click the trash icon. The next call from that token returns 401 within seconds. Set short expiries (7 / 30 / 90 days) when issuing tokens for extra safety.
Can I have separate tokens for separate assistants?
Yes - that's the recommended pattern. Issue one token per host ("Claude Desktop on my Mac", "Cursor on work machine", "Read-only analyst dashboard"), each with the minimum scopes it needs. Audit logs tag every call with which token + which client made it, so you can spot anomalies fast.
Generate a token, paste, chat
Three minutes from sign-in to your first refund issued from Claude. Read scopes are on by default - writes are opt-in per category. You can revoke any token in one click.