Skip to main content
Glama
paystack-mcp

paystack-mcp

by si-essence

paystack-mcp

MCP connector for the Paystack API aimed at the Accounts Team bots: Payment Matcher, Invoice Desk, Collections Desk, and Billing Support.

Paystack's official MCP (@paystack/mcp-server) is a public preview. It exposes two generic tools and rejects sk_live_ at startup. This connector is built for production use with live keys, but only after an explicit opt-in, and it still refuses to move money unless two further switches are on.

Read-only by default. Writes are dry-run previews until confirm: true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Nothing is retried.

Setup

cd paystack
npm ci
npm run build

stdio (what a Grok Bot or other MCP client launches):

{
  "mcpServers": {
    "paystack": {
      "command": "node",
      "args": ["/absolute/path/paystack/dist/index.js"],
      "env": {
        "PAYSTACK_SECRET_KEY": "sk_test_..."
      }
    }
  }
}

Put the secret in the MCP client's env block, not in chat. Leave the write and money switches unset until the owner has said yes.

Related MCP server: paystack-mcp-server

Environment

Variable

Required

Default

Purpose

PAYSTACK_SECRET_KEY

yes

sk_test_… or, with the opt-in below, sk_live_…. pk_ public keys are refused. rk_ restricted keys are refused in this version.

PAYSTACK_ALLOW_LIVE_KEY

no

off

Must be the exact string true before an sk_live_ key is accepted.

PAYSTACK_BASE_URL

no

https://api.paystack.co

Origin only. http is allowed solely for a loopback host.

PAYSTACK_ALLOW_WRITES

no

off

Exact true or every write and money action is a preview.

PAYSTACK_ALLOW_MONEY_MOVEMENT

no

off

Exact true or money actions stay a preview even when writes are on.

PAYSTACK_PER_MINUTE

no

60

Local cap. Paystack 429 is returned to the caller and not retried.

PAYSTACK_TIMEOUT_MS

no

20000

Per request.

PAYSTACK_CACHE_TTL_SEC

no

0

Cache GET responses. Payments stay uncached unless you set this.

PAYSTACK_CONTACT

no

Contact string in the User-Agent.

MCP_TRANSPORT

no

stdio

stdio or http. --http selects HTTP.

PORT

no

3000

HTTP listen port when transport is http.

1, yes, and TRUE do not enable a switch.

Live keys

  • sk_test_… is accepted with no extra flag.

  • sk_live_… is refused unless PAYSTACK_ALLOW_LIVE_KEY=true.

  • pk_… is refused. A public key is not a secret.

  • If PAYSTACK_BASE_URL is loopback (127.0.0.0/8, localhost, or ::1), an sk_live_ key is refused even when the opt-in is set. A live key is never sent to a mock.

  • A non-https base URL is refused unless the host is loopback.

The default base URL is fixed at https://api.paystack.co. Test and live modes are selected by the key, which is how Paystack works.

Safety model

Every operation is tagged read, write, or money in spec/api-inventory.json. The generator emits a distinct TypeScript type for each. A money operation carries moneyGate: "PAYSTACK_ALLOW_MONEY_MOVEMENT". requireMoneyCheck rejects a money operation that does not have that brand, and a write or read operation is not assignable to the money type.

Risk

When a request is sent

read

Immediately. Includes POST /bank/validate, which only looks up an account name.

write

confirm: true and PAYSTACK_ALLOW_WRITES=true. Otherwise a preview, and no HTTP request.

money

Both of the write conditions, plus PAYSTACK_ALLOW_MONEY_MOVEMENT=true. The preview names every missing switch.

Confirm false or omitted is a preview (blocked: false). A missing env switch is a preview with blocked: true.

What counts as money

These debit, refund, or pay out, so they are money:

  • POST /transaction/charge_authorization

  • POST /transaction/partial_debit

  • POST /refund

  • POST /transfer, POST /transfer/finalize_transfer, POST /transfer/bulk

POST /transaction/initialize does not debit by itself. It creates a charge flow (an authorization URL the customer can pay). That is money movement, so initialize is money and needs PAYSTACK_ALLOW_MONEY_MOVEMENT.

Creating or notifying a payment request does not debit a saved card. Those stay write. Resolving a dispute as merchant-accepted can cause Paystack to refund the customer. That action stays write, because the refund is the dispute outcome rather than POST /refund. The preview says so. Treat it as financially sensitive.

Amounts, currency, idempotency

Amounts are positive integers in the subunit Paystack expects. This connector does not convert major units.

Currency

Unit to send

NGN

kobo (100 = 1 NGN)

GHS

pesewas (100 = 1 GHS)

ZAR, KES, USD, EGP

minor unit (100 = 1 major)

XOF

ISO 4217 has no minor unit. Pass the positive integer Paystack shows for XOF. Confirm it on the dashboard before a money call.

Currency is one of NGN, GHS, ZAR, KES, USD, XOF, EGP.

List endpoints accept perPage, page, use_cursor, next, and previous where Paystack paginates that way. perPage and page are integers from 1 to 200.

Paystack dedupes charges and transfers with the reference you send. Pass a new reference for a new attempt and reuse it if you are retrying the same one. This connector does not invent an Idempotency-Key header; Paystack's documented idempotency for these calls is reference.

Redaction

The secret key is stripped from logs, errors, and previews in exact, percent-encoded, JSON-escaped, and Authorization: Bearer forms. Authorization codes, signatures, OTPs, BVNs, document numbers, and webhook secrets are removed. Bank and card account numbers in responses are masked to the last four digits. The webhook tool never returns the key or the digest.

Tools

Twelve tools. Eleven talk to Paystack. paystack_webhook stays on the machine.

Tool

Actions (risk)

paystack_transactions

list, fetch, verify, timeline, totals, export (read); initialize, charge_authorization, partial_debit (money)

paystack_customers

list, fetch (read); create, update, validate, set_risk_action (write)

paystack_invoices

list, fetch, verify, totals (read); create, update, notify, finalize, archive (write). Paystack calls these payment requests.

paystack_settlements

list, transactions (read)

paystack_refunds

list, fetch (read); create (money)

paystack_disputes

list, fetch, transaction, export (read); update, evidence, resolve (write)

paystack_transfers

list, fetch, verify (read); initiate, finalize, bulk (money)

paystack_recipients

list, fetch (read); create, update, delete (write)

paystack_balance

balance, ledger (read)

paystack_lookups

banks, resolve_account, countries, states (read); verify_account (read lookup, POST /bank/validate)

paystack_catalog

subaccounts, plans, subscriptions, products, payment pages, list and fetch only (read)

paystack_webhook

verify_signature (local). HMAC-SHA512 of the raw body with the secret key, constant-time compare to x-paystack-signature.

set_risk_action takes allow (whitelist) or deny (blacklist). Banks accept country=ghana and type=mobile_money for MoMo.

Examples

Payment Matcher, twice-daily feed. Reads only:

{ "action": "list", "perPage": 50, "page": 1, "status": "success", "currency": "GHS" }

Tool: paystack_transactions. Then verify on the reference, paystack_settlements list, and paystack_balance balance. For a MoMo credit, paystack_lookups banks with country ghana and type mobile_money.

Invoice Desk, draft a payment request. First call omits confirm and returns a preview. After the owner says yes, and only if PAYSTACK_ALLOW_WRITES=true:

{
  "action": "create",
  "confirm": true,
  "customer": "CUS_example",
  "amount": 15000,
  "currency": "GHS",
  "description": "Repair job 104, balance after deposit"
}

Tool: paystack_invoices. 15000 pesewas is 150 GHS.

Collections Desk, prepare a refund and do not send it. With the money switch off, confirm: true still previews:

{ "action": "create", "confirm": true, "transaction": "1001", "amount": 5000, "currency": "GHS" }

Tool: paystack_refunds. The preview names PAYSTACK_ALLOW_MONEY_MOVEMENT when that switch is off. Dispute reads use paystack_disputes list so chasing can stop.

Billing Support, after an identity check that this connector does not perform. Reads only:

{ "action": "fetch", "code": "CUS_example" }

Tool: paystack_customers, then paystack_invoices fetch and paystack_transactions verify. This bot does not refund and does not call money actions.

Webhook check, no network:

{
  "action": "verify_signature",
  "raw_body": "{\"event\":\"charge.success\"}",
  "signature": "<hex from x-paystack-signature>"
}

Tool: paystack_webhook.

Coverage and exclusions

spec/api-inventory.json is hand-written from the Paystack API reference and the endpoint table in PaystackOSS/paystack-python. Purposes are original wording. node scripts/gen-operations.mjs --check (part of npm run ci) regenerates src/operations.ts and paystack.routes.json and fails if they drift.

Mapped: 64 routes (42 read, 15 write, 7 money). Excluded: 56 routes, including the interactive charge API (PIN, OTP, card data), bulk charge, dedicated virtual accounts, splits, subscription and plan writes, transfer OTP disable, and product or page writes. The full list with reasons is in the inventory.

There is no single-settlement fetch in the PaystackOSS Python endpoint table. List settlements and GET /settlement/{id}/transaction are mapped.

Comparison

Server

Tools

Live keys

Confirm gate

Money gate

PaystackOSS/paystack-mcp-server (@paystack/mcp-server, MIT, public preview)

get_paystack_operation, make_paystack_request, plus an operations resource. The whole API is one generic caller.

Rejects sk_live_ at startup. Test key only.

No

No

kohasummons/paystack-mcp (MIT)

Named tools for products, customers, transactions (initialize, verify, fetch, list, charge, partial debit, totals, export), and bank, country, and state lists.

PAYSTACK_SECRET_KEY. No live-key opt-in documented.

No

No

samaxbytez/paystack-mcp (paystack-mcp on npm)

README claims 121 tools across transactions, charges, transfers, refunds, and disputes.

Accepts sk_test_ and sk_live_ with no extra opt-in.

No

No

@tracent/paystack-mcp

README describes ten future tools and human-in-the-loop writes. The published note says the surface is still landing.

Not a finished server to depend on.

Claimed, not shipped as a complete server

Claimed

This connector trades breadth for gates: scoped actions, a live-key opt-in, a separate money switch, previews, and tests. It is not a wrapper around the official preview server.

Development

npm run ci

ci is typecheck, lint, Vitest, build, and node scripts/gen-operations.mjs --check.

The live check does not call Paystack. See LIVE-CHECK.md.

/workspace/tools/paystack/start.sh
PAYSTACK_MOCK_PORT=$(cat /workspace/tools/paystack/mock.port) npm run live-check
/workspace/tools/paystack/stop.sh

Provenance

Inventory and wording are original, checked against Paystack's public API reference (retrieved 18 Nov 2026) and the PaystackOSS paystack-python endpoint table. No Paystack source is vendored. Official MCP behavior is from the Paystack MCP docs and the PaystackOSS/paystack-mcp-server README.

License

MIT. See LICENSE.

Available Tools

12 tools
paystack_balanceC
Read-only

paystack_balance. Actions: balance (read), ledger (read). Read-only. Amounts are positive integers in subunits.

Inputs: action (required), to, from, next, +6 more.

paystack_catalogC
Read-only

paystack_catalog. Actions: list_subaccounts (read), fetch_subaccount (read), list_plans (read), fetch_plan (read), list_subscriptions (read), fetch_subscription (read), list_products (read), fetch_product (read), list_pages (read), fetch_page (read). Read-only. Amounts are positive integers in subunits.

Inputs: action (required), id, code, next, +7 more.

paystack_customersB
Destructive

paystack_customers. Actions: list (read), fetch (read), create (write), update (write), validate (write), set_risk_action (write). Writes need confirm:true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Otherwise this is a preview and no request is sent. Amounts are positive integers in subunits.

Inputs: action (required), to, bvn, code, +19 more.

paystack_disputesA
Destructive

paystack_disputes. Actions: list (read), fetch (read), transaction (read), export (read), update (write), evidence (write), resolve (write). Writes need confirm:true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Otherwise this is a preview and no request is sent. Amounts are positive integers in subunits.

Inputs: action (required), id, to, from, +16 more.

paystack_invoicesB
Destructive

paystack_invoices. Actions: list (read), fetch (read), create (write), update (write), verify (read), notify (write), finalize (write), archive (write), totals (read). Writes need confirm:true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Otherwise this is a preview and no request is sent. Amounts are positive integers in subunits.

Inputs: action (required), id, to, from, +15 more.

paystack_lookupsC
Read-only

paystack_lookups. Actions: banks (read), resolve_account (read), countries (read), states (read), verify_account (read). Read-only. Amounts are positive integers in subunits.

Inputs: action (required), next, page, type, +13 more.

paystack_recipientsB
Destructive

paystack_recipients. Actions: list (read), fetch (read), create (write), update (write), delete (write). Writes need confirm:true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Otherwise this is a preview and no request is sent. Amounts are positive integers in subunits.

Inputs: action (required), to, code, from, +13 more.

paystack_refundsA
Destructive

paystack_refunds. Actions: list (read), fetch (read), create (money). Writes need confirm:true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Otherwise this is a preview and no request is sent. Amounts are positive integers in subunits.

Inputs: action (required), id, to, from, +12 more.

paystack_settlementsC
Read-only

paystack_settlements. Actions: list (read), transactions (read). Read-only. Amounts are positive integers in subunits.

Inputs: action (required), id, to, from, +8 more.

paystack_transactionsB
Destructive

paystack_transactions. Actions: list (read), fetch (read), verify (read), timeline (read), totals (read), export (read), initialize (money), charge_authorization (money), partial_debit (money). Writes need confirm:true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Otherwise this is a preview and no request is sent. Amounts are positive integers in subunits.

Inputs: action (required), id, to, from, +20 more.

paystack_transfersA
Destructive

paystack_transfers. Actions: list (read), fetch (read), verify (read), initiate (money), finalize (money), bulk (money). Writes need confirm:true and PAYSTACK_ALLOW_WRITES=true. Money actions also need PAYSTACK_ALLOW_MONEY_MOVEMENT=true. Otherwise this is a preview and no request is sent. Amounts are positive integers in subunits.

Inputs: action (required), to, otp, code, +16 more.

paystack_webhookA
Read-onlyIdempotent

Verify an x-paystack-signature header locally. HMAC-SHA512 of the raw body with the configured secret key, compared in constant time. No network call. The key is never returned.

Inputs: action (required), raw_body (required), signature.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 12 tools

    Disambiguation4/5

    Tools are cleanly partitioned by resource domain (transactions, transfers, refunds, customers, disputes, etc.), so an agent can map intent to tool easily. There is minor overlap where 'verify' appears in transactions, invoices, transfers, and lookups, and where catalog bundles subscriptions/plans/products/pages/subaccounts, but descriptions make the target clear.

    Naming Consistency5/5

    Every tool follows the same paystack_<resource> snake_case convention with a consistent prefix. The action-level verbs (list, fetch, create, update, verify) are applied uniformly inside each tool, giving a predictable structure throughout.

    Tool Count5/5

    Twelve resource-grouped tools sit squarely in the well-scoped range, and each earns its place by covering a distinct Paystack domain. The grouping into action-dispatched tools keeps the count compact without omitting major areas.

    Completeness4/5

    Core money and lifecycle flows are covered: transactions, transfers, refunds, invoices, recipients, disputes, settlements, customers, plus webhook signature verification. The main gap is that paystack_catalog is read-only, so plans, products, pages, subaccounts, and subscriptions cannot be created or updated, and payment-page creation is absent.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI agents to interact with multiple payment providers (Stripe, Paystack) through a unified API. Supports payment initialization, verification, refunds, customer management, and invoicing without requiring knowledge of specific provider implementations.
      2
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to interact with the full range of Paystack APIs, allowing operations like transaction management, customer creation, and payments through natural language.
      2
      94 npm
      56
      MIT