MCP server for AI assistants

Connect Claude, Cursor or any other Model Context Protocol client to your Paymentsnp workspace, then ask about payments, invoices and settlements in plain language.

  • Read-only by default
  • Customer contact details masked
  • Your key stays on your machine
Safe by default
# Set in your MCP client's config
PAYMENTSNP_API_KEY=np_test_xxx

# Defaults, shown for clarity
PAYMENTSNP_MCP_ALLOW_WRITES=false   # read-only tools
PAYMENTSNP_MCP_SHOW_PII=false       # emails and phones masked
Runs locally with npx -y @paymentsnp/mcp. Node.js 20+.

What it is

@paymentsnp/mcp is a small MCP server that runs on your own computer and talks to the Paymentsnp API with a key you give it. Your assistant can then look things up for you instead of you exporting a CSV.

Runnpx -y @paymentsnp/mcp
RuntimeNode.js 20 or newer
SizeOne file, no dependencies
Transportstdio, started by your MCP client
Default modeRead-only. Write tools appear only when you turn them on.
ClientsClaude Code, Claude Desktop, Cursor and other desktop MCP clients

Because npx fetches it on demand, there is nothing to install. For offline machines, download the ZIP from Dashboard > Downloads and run node /path/to/paymentsnp-mcp/server.js instead.

1. Create an API key

In the dashboard, switch to Test, open API keys and create a key for the assistant. Tick only the scopes for the tools you want it to have.

Tools and the scope each needs
ToolsScopeKind
get_checkout_sessioncheckout:readRead
list_payments, get_payment, payments_summary, list_refundspayments:readRead
list_invoices, get_invoiceinvoices:readRead
reconciliation_reportreconciliation:readRead
create_checkout_session, expire_checkout_sessioncheckout:createWrite
create_invoice_draft, finalize_invoice, send_invoiceinvoices:writeWrite
record_refundrefunds:writeWrite

The key decides the environment: an np_test_ key sees only test data, an np_live_ key only live data. Start with a test key. For a live key, consider an IP allowlist and a short expiry.

2. Add it to your client

claude mcp add paymentsnp --env PAYMENTSNP_API_KEY=np_test_xxx -- npx -y @paymentsnp/mcp
// Settings > Developer > Edit Config (claude_desktop_config.json)
{
  "mcpServers": {
    "paymentsnp": {
      "command": "npx",
      "args": ["-y", "@paymentsnp/mcp"],
      "env": { "PAYMENTSNP_API_KEY": "np_test_xxx" }
    }
  }
}
// ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project)
{
  "mcpServers": {
    "paymentsnp": {
      "command": "npx",
      "args": ["-y", "@paymentsnp/mcp"],
      "env": { "PAYMENTSNP_API_KEY": "np_test_xxx" }
    }
  }
}
Replace np_test_xxx with your key. Never commit a file that contains it.

Restart Claude Desktop after editing its config. If Node is not on its PATH, use the absolute path to npx (which npx).

Questions to ask

  • "How much did we receive through Khalti this week?"
  • "Which invoices are overdue, and what is the total?"
  • "Show the payment for order ORD-1001 and its provider transaction ID."
  • "Compare verified payments with imported settlements for the last 30 days."
  • "Is checkout session c1a94d07 paid yet?"

Every *_minor amount comes with a formatted twin, for example amount_npr: "NPR 1,500.50", so the assistant does not have to convert paisa itself.

Tools

Read, always available

  • get_checkout_session: status of a checkout session.
  • list_payments: verified payments, with limit, offset, search, provider and Nepal dates.
  • get_payment: one payment with its provider transaction ID.
  • payments_summary: verified gross, count and pending attempts. Not a balance; money settles directly to your provider accounts.
  • list_refunds: refunds recorded for one payment.
  • list_invoices and get_invoice: invoices by status or search, with totals and recent timeline events.
  • reconciliation_report: verified payments against imported settlements for 7, 30 or 90 days.

Write, only with PAYMENTSNP_MCP_ALLOW_WRITES=true

  • create_checkout_session and expire_checkout_session. The order ID is the Idempotency-Key, so asking twice returns the same checkout.
  • create_invoice_draft, finalize_invoice and send_invoice.
  • record_refund: records a refund you already made in the provider panel. It moves no money, and asking twice records once.

There are no payout, automatic refund or delete tools.

Settings

Environment variables
VariableDefaultEffect
PAYMENTSNP_API_KEYRequiredYour np_test_ or np_live_ key. Read from the environment only, never echoed back.
PAYMENTSNP_MCP_ALLOW_WRITESfalsetrue adds the write tools.
PAYMENTSNP_MCP_SHOW_PIIfalsetrue shows customer emails and phone numbers unmasked.
PAYMENTSNP_API_BASE_URLhttps://api.paymentnp.com/v1Must be https; plain http only for localhost.

Safety notes

  • Your key stays local. It is read from your client's config and sent only to the Paymentsnp API.
  • Masked by default. Customer emails and phone numbers appear as s***@example.com and 98******78.
  • Data, not instructions. Names, descriptions and memos were typed by customers or staff. The assistant should treat them as data.
  • Least privilege. Give the key read scopes only unless you need writes, and prefer a test key while you try it.

The server speaks MCP over stdio with JSON-RPC 2.0. Errors use the same class names as the SDKs, with the API's error code and request ID.