NovaPay MCP Server

MCP stdio server for NovaPay on top of the official novapay SDK. Connect it to any MCP-compatible agent (Claude Desktop, Claude Code, custom agents) — and the agent can create payment links, poll payment status, drive the session lifecycle and generate merchant keys.

📖 Документація українською

Contents · Requirements · Setup · Onboarding from scratch · Tools · Development · License

Requirements

• Node.js 20.3+

Setup

Add to your MCP client config:

{
  "mcpServers": {
    "novapay": {
      "command": "npx",
      "args": ["-y", "novapay-mcp"],
      "env": {
        "MERCHANT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nMIIEvQ...\n-----END PRIVATE KEY-----",
        "MERCHANT_ID": "<your merchant id>",
        "NOVAPAY_ENVIRONMENT": "stage"
      }
    }
  }
}

The PEM can be pasted either with \n escapes (as in the example) or as a multi-line value — the server understands both.

Environment variables

Variable	Required	Description
MERCHANT_PRIVATE_KEY	yes	Merchant's private RSA key (PEM). Signs every request to NovaPay
MERCHANT_ID	yes	Merchant identifier in NovaPay
NOVAPAY_ENVIRONMENT	yes	stage — NovaPay test environment (api-qecom.novapay.ua), prod — production (api-ecom.novapay.ua)
NOVAPAY_PUBLIC_KEY	no	NovaPay public key (PEM). Unused in stdio mode — the server does not receive postbacks

The server starts without configuration too: generate_keys stays available, and the payment tools return an error listing the missing variables.

Onboarding from scratch

No keys yet? Generate them straight from the agent:

1. Connect the server without env (or with a partial env) and ask the agent to call generate_keys.
2. Register the public key from the response with NovaPay (Acquiring3 admin panel or via support).
3. Paste the contents of the private key file (the path is in the response, the file lives in ~/.novapay/ with 0600 permissions) into MERCHANT_PRIVATE_KEY, add MERCHANT_ID and NOVAPAY_ENVIRONMENT.
4. Restart the MCP server — the payment tools go live.

The private key is never returned in a tool response — only the file path, so the key never lands in the agent's context or logs.

Tools

Onboarding

• generate_keys — generate a 2048-bit RSA pair for the merchant. Works without configuration.

Creating payments (a session can hold several payments)

• create_acquiring_session — create an Internet Acquiring session → session id.
• add_acquiring_payment — add a payment to the session → payment URL for the customer.
• create_checkout_session — create a Checkout session (payment + Nova Poshta delivery) → session id.
• add_checkout_payment — add a payment to a checkout session → payment URL.

Both add_*_payment require an explicit use_hold: true — hold the funds for a later capture via complete_hold, false — charge immediately. If the user did not say which, the agent should ask.

Session lifecycle (shared by acquiring and checkout)

• get_session_status — session status, amounts, list of operations. The only way to see the result of the operations below.
• complete_hold — capture the held funds (possibly partially).
• void_session — cancel a paid/held session. On a paid session this refunds real money.
• expire_session — invalidate an unpaid session (cancel the payment link).

create_*_session ──▶ add_*_payment ──▶ url
                          │
                    customer pays
                          ├─ use_hold: true ──▶ holded ──complete_hold──▶ paid
                          └─ use_hold: false ──────────────────────────▶ paid
                                                                          │
       unpaid ──expire_session──▶ expired             void_session ◀──────┘
                                                          ▼
                                                        voided

Development

npm install
npm test        # tsc --noEmit + node:test
npm run build   # tsc → dist/

A smoke test against the NovaPay stage environment is possible with the published QE keys (merchant 2) from the Authentication page.

CI runs the same checks on Node 20, 22 and 24 for every push and pull request; pushing a v* tag publishes the package to npm.

License

MIT