AI assistants (MCP) - PayBridgeNP

The official Model Context Protocol (MCP) server for PayBridgeNP. Lets any MCP-compatible AI assistant - Claude Desktop, Cursor, Claude Code, VS Code, Continue, and (soon) ChatGPT + claude.ai - talk to your PayBridgeNP account through 69 typed tools. The MCP server runs locally as an npm package. Your token never leaves your machine. Tool calls go directly to api.paybridgenp.com over HTTPS - the model only sees JSON results, never your raw API key.

Source code is open at github.com/paybridgenp/paybridgenp-mcp. Audit exactly what runs against your key before installing.

Quickstart

1. Generate a scoped token

Open dashboard.paybridgenp.com/mcp. Click Generate token. The new-token form lets you pick:

Description - a label so you can find this token later in the audit log (e.g., “Claude Desktop on my laptop”).
Scopes - grouped Read / Write / Sensitive. Read-only is the safe default; opt in to writes per category.
Expires - 7d, 30d, 90d, or never. 30d is recommended.
Spend cap (paisa, 24h rolling) - auto-prefilled to Rs 50,000 when any write scope is enabled. Hard cap on the rolling 24-hour sum of refunds + checkout sessions originated by this token.

Hit Generate. The raw sk_test_… or sk_live_… token is shown once - copy it immediately. We can’t show it again.

2. Paste into your AI assistant

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "paybridge": {
      "command": "npx",
      "args": ["-y", "@paybridge-np/mcp@latest"],
      "env": { "PAYBRIDGE_API_KEY": "sk_live_..." }
    }
  }
}

Restart Claude Desktop.

Cursor

Same JSON in .cursor/mcp.json (or via Settings → MCP).

{
  "mcpServers": {
    "paybridge": {
      "command": "npx",
      "args": ["-y", "@paybridge-np/mcp@latest"],
      "env": { "PAYBRIDGE_API_KEY": "sk_live_..." }
    }
  }
}

Claude Code

claude mcp add paybridge \
  --env PAYBRIDGE_API_KEY=sk_live_... \
  -- npx -y @paybridge-np/mcp@latest

VS Code

.vscode/mcp.json:

{
  "servers": {
    "paybridge": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@paybridge-np/mcp@latest"],
      "env": { "PAYBRIDGE_API_KEY": "sk_live_..." }
    }
  }
}

ChatGPT / claude.ai web

Remote (HTTP) MCP requires OAuth - shipping at mcp.paybridgenp.com next. Watch this page for status.

3. Try it

Open your assistant and type something natural:

Refund the last successful payment from customer@example.com.

The agent picks the right tool calls (list_payments → get_payment → create_refund), and PayBridgeNP’s MCP server pops up a confirmation modal asking you to approve the refund before it executes. You see the refund result inline.

What you can ask

The agent figures out the right tool calls. You don’t write them by hand.

“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?”
“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.”

Tools

69 tools across read + write. Read tools cover the entire account surface; write tools cover refunds, checkout creation, payment-link CRUD, webhook CRUD, and the full billing surface - plans, customers, subscriptions, invoices, coupons, promotions, tax, dunning, and usage metering.

Read (31 tools)

Tool	Scope	What it does
`get_account`	`account:read`	Merchant + project + key context (PII masked unless `pii:read`)
`list_payments` / `get_payment`	`payments:read`	Inspect payments with full provider + customer detail
`list_refunds` / `get_refund`	`refunds:read`	Refund history, status, failure reason
`list_checkout_sessions` / `get_checkout_session`	`sessions:read`	In-flight + abandoned checkouts
`list_payment_links` / `get_payment_link`	`links:read`	Links + view/conversion stats inline
`list_webhook_endpoints` / `list_webhook_deliveries`	`webhooks:read`	Endpoint config + per-delivery debug
`list_plans` / `get_plan`	`billing:read`	Subscription billing plans
`list_customers` / `get_customer`	`billing:read`	Billing customers
`list_subscriptions` / `get_subscription`	`billing:read`	Active + past-due subscriptions
`list_invoices` / `get_invoice`	`billing:read`	Subscription invoices
`list_coupons` / `get_coupon`	`billing:read`	Discount coupons and their redemption stats
`list_promotion_codes` / `get_promotion_code` / `validate_promotion_code`	`billing:read`	Promotion codes - list, inspect, or validate a code before applying
`get_tax_settings`	`billing:read`	Active tax configuration for the account
`list_dunning_policies` / `get_dunning_invoice_status`	`billing:read`	Dunning policy definitions + per-invoice dunning state
`preview_subscription_proration`	`billing:read`	Estimate the prorated credit/charge before a plan change
`get_subscription_usage_summary` / `list_usage_records`	`billing:read`	Metered usage totals and raw usage record history
`get_analytics_overview`	`analytics:read`	Headline KPIs (total / success rate / volume / funnel / per-provider) over a 1–90 day window

Write (38 tools)

Every write tool is annotated destructiveHint. Money-moving tools always elicit confirmation in the host UI before executing.

Tool	Scope	Confirms?
`create_checkout_session`	`payments:write`	If `amount > 5,000` (paisa: 500,000)
`create_refund`	`refunds:write`	Always
`create_payment_link`	`links:write`	No
`update_payment_link`	`links:write`	No
`cancel_payment_link`	`links:write`	No (soft-deactivate, reversible)
`delete_payment_link`	`links:write`	Always (only if never used)
`create_webhook_endpoint`	`webhooks:write`	No (idempotent create)
`update_webhook_endpoint`	`webhooks:write`	No
`delete_webhook_endpoint`	`webhooks:write`	Always
`create_plan` / `update_plan`	`billing:write`	No
`create_customer` / `update_customer`	`billing:write`	No
`add_customer_credit`	`billing:write`	No
`create_subscription`	`billing:write`	No
`pause_subscription` / `resume_subscription`	`billing:write`	No
`cancel_subscription`	`billing:write`	Always
`change_subscription_plan`	`billing:write`	No
`end_trial` / `extend_trial`	`billing:write`	No
`create_invoice_item` / `delete_invoice_item`	`billing:write`	No
`create_coupon` / `deactivate_coupon`	`billing:write`	No
`create_promotion_code` / `deactivate_promotion_code`	`billing:write`	No
`apply_coupon_to_subscription` / `remove_subscription_discount`	`billing:write`	No
`update_tax_settings`	`billing:write`	No
`create_dunning_policy` / `update_dunning_policy`	`billing:write`	No
`set_subscription_dunning_policy`	`billing:write`	No
`stop_invoice_dunning`	`billing:write`	Always
`retry_invoice_dunning_now`	`billing:write`	No
`report_subscription_usage` / `update_subscription_quantity`	`billing:write`	No

Prompts

6 built-in prompt templates that appear as slash commands and menu items in Claude Desktop and Cursor. Select one, fill in any arguments, and the agent picks up from there - no need to remember tool names or craft instructions manually.

Prompt	What it does	Arguments
`daily_summary`	End-of-day digest - revenue, payment counts, refunds, checkout funnel completion rate, and any failed webhook deliveries	None
`monthly_reconciliation`	Full month reconciliation table: gross volume, net after refunds, success rate, provider breakdown, top 5 customers. Ready to share with an accountant	`month` (optional, e.g. `2026-04`)
`investigate_failed_payment`	Diagnoses why a payment or batch of payments failed. Checks provider error codes, checkout session funnel, and recommends retry / contact customer / escalate	`payment_id` (optional) or `customer_email` (optional)
`onboard_customer`	Creates a billing customer and subscribes them to a plan in one flow. Validates the plan, optionally validates and applies a promotion code, then confirms subscription details	`email`, `name`, `plan_id` (required); `coupon_code` (optional)
`review_dunning`	Lists all past-due invoices, shows retry count and next scheduled retry for each, and categorizes them as Retry now / Stop dunning / Wait. Asks for confirmation before acting	None
`apply_discount`	Validates a promotion code, shows the before/after price, then applies the discount to a subscription after confirmation	`subscription_id`, `promotion_code`

Prompts are available in any host that supports MCP prompts - Claude Desktop ≥ 0.7, Cursor ≥ 0.42, Claude Code current. In Claude Desktop, open the prompt picker with / and type paybridge to filter to PayBridgeNP prompts.

Scope reference

16 scopes. Tokens hold an explicit allowlist - anything not in the list returns 403 insufficient_scope at the API gateway, never reaching the handler.

Read scopes (granted by default)

Scope	Unlocks
`account:read`	`get_account`
`payments:read`	`list_payments`, `get_payment`
`refunds:read`	`list_refunds`, `get_refund`
`sessions:read`	`list_checkout_sessions`, `get_checkout_session`
`links:read`	`list_payment_links`, `get_payment_link`
`webhooks:read`	`list_webhook_endpoints`, `list_webhook_deliveries`
`billing:read`	All `list_` / `get_` billing tools
`analytics:read`	`get_analytics_overview`
`audit:read`	(reserved - `list_audit_logs` shipping next)
`docs:read`	(reserved - `search_docs` shipping next)

Write scopes (opt in per scope)

Scope	Unlocks
`payments:write`	`create_checkout_session`
`refunds:write`	`create_refund`
`links:write`	`create_payment_link`, `update_payment_link`, `cancel_payment_link`, `delete_payment_link`
`webhooks:write`	webhook CRUD
`billing:write`	All billing CRUD + lifecycle

Sensitive

Scope	Effect
`pii:read`	Returns raw `customer_email` and `customer_phone` instead of masked. Never granted by default.

Security model

Four overlapping defenses so an agent can’t bankrupt you, and a token leak is contained.

1. Scope enforcement

Every /v1/* route checks requireApiKeyScope(...) before the handler runs. MCP-kind tokens with explicit scopes get full enforcement; legacy REST API keys retain full access for backward compatibility.

2. Elicitation gates on destructive actions

Money-moving tool calls send an MCP elicitation/create request to the host. The host shows a confirmation modal with the proposed amount, customer, and action. The tool only proceeds on accept. Hosts that don’t support elicitation - usually older clients - fail closed with elicitation_unsupported and an actionable error pointing back to the dashboard. For create_refund, the server hydrates the underlying payment first, so the modal shows the real amount + customer + provider, not just an opaque payment id.

3. 24-hour rolling spend cap

Every checkout session and refund records its originating_api_key_id. Before each POST /v1/checkout and POST /v1/refunds, the server sums the originating spend in the trailing 24 hours; if current + new > spend_cap_paisa, the call is rejected with HTTP 403:

{
  "error": "MCP token spend cap exceeded. Last 24h spend: Rs 400.00, cap: Rs 500.00, remaining: Rs 100.00.",
  "code": "over_spend_cap",
  "spent_paisa": 40000,
  "cap_paisa": 50000,
  "remaining_paisa": 10000,
  "reset_at": "2026-04-19T00:21:12.556Z"
}

4. Per-token rate limits

Three buckets, all per-token:

Total: 60 calls / 60s
Destructive: 6 calls / 60s
Elicitation-gated: 2 calls / 60s

Returns 429 with Retry-After and X-RateLimit-Bucket headers. REST keys are unaffected for back-compat.

Other defenses

Audit trail. Every tool call is recorded with mcp.tool.<name>, the token id, and the assistant’s name (captured from the MCP InitializeRequest.clientInfo.name). Visible live in your dashboard.
No token passthrough. The MCP server never forwards your token to upstream provider APIs. Khalti / eSewa secrets stay server-side.
Prompt-injection defense. Customer-controlled fields (names, descriptions, metadata) are wrapped in <untrusted>…</untrusted> fences when returned to the model. Zero-width characters are stripped. Secret patterns (sk_*, pk_*, whsec_*, Bearer …) are pattern-redacted on the way out.
PII masking. customer_email shows as ra***@example.com; customer_phone shows as ***1234. Unmask only by granting pii:read.
One-click revoke. Find the token in the dashboard and click the trash icon. The next call returns 401 within seconds.

Audit + activity feed

Open dashboard.paybridgenp.com/mcp. The Recent activity card shows the last 24h of MCP-originated events:

mcp_token.created / mcp_token.revoked
refund.created (with via: "mcp", mcp_client_name, api_key_id)
checkout_session.created
webhook_endpoint.created / .updated / .deleted

Premium-plan merchants see the full audit history at /logs with the same MCP tagging.

Configuration reference

The MCP server reads two env vars when you run it:

Env var	Required	Default
`PAYBRIDGE_API_KEY`	yes	-

You can also pass --api-key=sk_live_... as a CLI argument instead of the env var.

Troubleshooting

Tools don’t show up in my assistant

Restart the assistant after editing config - most hosts only re-read MCP configs at startup.
Run npx -y @paybridge-np/mcp@latest in a terminal manually. If it errors, the message will tell you what’s wrong (usually a missing or revoked token).
Check the host’s MCP log. Claude Desktop: ~/Library/Logs/Claude/mcp*.log.

Every tool call returns 401

Token is revoked, expired, or the env var didn’t survive into the host’s environment. Generate a fresh token from the dashboard and replace.

Every write call returns `insufficient_scope`

Your token is read-only. Generate a new token with the relevant write scopes ticked. Don’t reuse the read-only token - issue a separate write-scoped token with a tight spend cap so you can revoke it independently.

`over_spend_cap` after running a few refunds

Either raise the cap on the token or wait for the 24h window to roll. The error response includes reset_at - that’s when the oldest counted activity ages out.

`elicitation_unsupported` on a destructive tool

Your host doesn’t implement MCP elicitation. Update the host (Claude Desktop ≥ 0.7, Cursor ≥ 0.42, Claude Code current), or perform the action in the PayBridgeNP dashboard instead.

Customer names show up wrapped in `<untrusted>`

That’s deliberate - it tells the model not to interpret merchant-controlled free text as instructions. Defense against prompt injection in metadata / customer fields. Don’t strip the wrappers.

How do I see what the agent is actually doing?

The dashboard’s Recent activity card shows every MCP tool invocation with the assistant’s name, the action, and timestamps. Hosts also typically log tool calls - Claude Desktop shows them inline; Cursor logs them to its dev console.

Roadmap

Remote (HTTP) MCP with OAuth 2.1 - unlocks ChatGPT and claude.ai web (parked until demand shows up in token telemetry).
Audit + search tools (list_audit_logs, search_paybridge, search_docs).
AP2 mandate hooks for agent-initiated commerce (forward-compat).

Track progress at github.com/paybridgenp/paybridgenp-mcp.

Getting Started

Integrations

Guides

API Reference

SDK

Documentation Index

​Quickstart

​1. Generate a scoped token

​2. Paste into your AI assistant

​Claude Desktop

​Cursor

​Claude Code

​VS Code

​ChatGPT / claude.ai web

​3. Try it

​What you can ask

​Tools

​Read (31 tools)

​Write (38 tools)

​Prompts

​Scope reference

​Read scopes (granted by default)

​Write scopes (opt in per scope)

​Sensitive

​Security model

​1. Scope enforcement

​2. Elicitation gates on destructive actions

​3. 24-hour rolling spend cap

​4. Per-token rate limits

​Other defenses

​Audit + activity feed

​Configuration reference

​Troubleshooting

​Tools don’t show up in my assistant

​Every tool call returns 401

​Every write call returns insufficient_scope

​over_spend_cap after running a few refunds

​elicitation_unsupported on a destructive tool

​Customer names show up wrapped in <untrusted>

​How do I see what the agent is actually doing?

​Roadmap

Quickstart

1. Generate a scoped token

2. Paste into your AI assistant

Claude Desktop

Cursor

Claude Code

VS Code

ChatGPT / claude.ai web

3. Try it

What you can ask

Tools

Read (31 tools)

Write (38 tools)

Prompts

Scope reference

Read scopes (granted by default)

Write scopes (opt in per scope)

Sensitive

Security model

1. Scope enforcement

2. Elicitation gates on destructive actions

3. 24-hour rolling spend cap

4. Per-token rate limits

Other defenses

Audit + activity feed

Configuration reference

Troubleshooting

Tools don’t show up in my assistant

Every tool call returns 401

Every write call returns `insufficient_scope`

`over_spend_cap` after running a few refunds

`elicitation_unsupported` on a destructive tool

Customer names show up wrapped in `<untrusted>`

How do I see what the agent is actually doing?

Roadmap