Tracent Paystack MCP

Agent-callable Paystack for African commerce. Ten Model Context Protocol tools across reconciliation, customers, refunds, and settlements, with NDPA-grade redaction and human-in-the-loop gates on every write.

Status: Coming v0.1.0. Active development. The full ten-tool surface lands in Week 2 of the six-week build sequence per tracent-mcp-server-build.md §9. This README reflects the contract the server will satisfy at launch.

What this is

@tracent/paystack-mcp is the official Tracent MCP server for Paystack, the largest African payment processor. It exposes ten typed tools over the Model Context Protocol so any MCP-compatible AI client (Claude Desktop, ChatGPT, Gemini) can read transactions, verify payments, manage customers, initiate refunds, and reconcile settlements through plain-language prompts.

Built for the realities of African finance: integer-kobo money throughout, NDPA-compliant PII redaction at the gateway boundary, mandatory human approval on the two tools that write to your Paystack account.

Why this exists

Most MCP servers in 2026 are basic API wrappers that solve perhaps 40% of what production deployment requires. The Paystack server ships with all seven guardrail categories from v0.1.0 because the regulatory, security, and customer-trust positions Tracent depends on require it:

1. Authentication and authorisation - OAuth 2.1 with PKCE, Resource Indicators (RFC 8707), short-lived scoped tokens
2. Input validation - Zod .strict() schemas, bounded ranges, integer money, structured errors
3. PII and data sovereignty - random vaulted tokens (TTL-scoped, never deterministic), multi-region detection, named-entity recognition
4. Human-in-the-loop - PIN-gated on create_customer and initiate_refund with a complete state machine
5. Semantic safety - prompt-injection scanning, tool-description integrity signing, no dynamic tool selection
6. Rate limiting - per-user, per-tool, per-window, with a circuit breaker on the Paystack API
7. Observability - structured logs to stderr, Sentry with NDPA scrubbing, hash-chained append-only audit log

The seven categories are implemented in tracent-gateway-core, the shared commercial gateway. The MCP server in this repository is the open-source, MIT-licensed front; the gateway-core is what activates the full guardrail stack.

Quick start

Three install paths. Pick whichever matches your situation.

Path 1: Local in Claude Desktop

Self-hosted, you run the MCP locally with your own Paystack key. No gateway in the middle; useful for development and local agent workflows.

npm install -g @tracent/paystack-mcp

# Set your Paystack test secret key
export PAYSTACK_SECRET_KEY=sk_test_your_key_here

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "paystack": {
      "command": "tracent-paystack-mcp"
    }
  }
}

Restart Claude Desktop. The ten Paystack tools appear in the tool list. Try What's our NGN balance right now? to verify.

Path 2: Hosted Tracent gateway (recommended)

Two clicks of OAuth, all seven guardrails active automatically.

1. Sign up at tracenttechnologies.com/signup
2. Open /console/servers/new, choose Paystack, connect via OAuth
3. Configure Claude Desktop with the HTTP endpoint and the Tracent token from /console/settings/account

Pricing from ₦150,000 per month at Starter; see pricing.

Path 3: Self-host the gateway

Sovereign deployment in your own VPC or on Cassava Cloud. For Enterprise customers with data-residency requirements. Book a security architecture review at tracenttechnologies.com/contact.

The ten tools

| Tool | Endpoint | HITL | Rate (/min, /hour) | |---|---|---|---| | create_payment_link | POST /transaction/initialize | Conditional (>₦100,000) | 30, 500 | | verify_payment | GET /transaction/verify/:reference | None | 120, 2000 | | list_transactions | GET /transaction | None | 60, 1000 | | get_transaction | GET /transaction/:id | None | 120, 2000 | | list_customers | GET /customer | None | 60, 1000 | | create_customer | POST /customer | Always | 20, 300 | | initiate_refund | POST /refund | Always | 5, 50 | | list_balances | GET /balance | None | 30, 500 | | get_settlements | GET /settlement | None | 30, 500 | | list_payment_pages | GET /page | None | 30, 500 |

Full reference at tracenttechnologies.com/docs/mcp-servers/paystack/tools.

Architecture

LLM
 │  natural-language tool call
 ▼
Tracent Gateway (tracent-gateway-core)
 ├─ Authentication (OAuth 2.1 + PKCE)
 ├─ Input validation (Zod .strict())
 ├─ PII redaction (random vaulted tokens, TTL)
 ├─ HITL gate (state machine, PIN-verified)
 ├─ Semantic safety (injection scanning, integrity sign)
 ├─ Rate limiting (atomic token bucket)
 └─ Observability (audit chain, decision-path log)
 │  validated, redacted, gated request
 ▼
@tracent/paystack-mcp  (this repository)
 │  typed Paystack API call
 ▼
Paystack API
 │  response
 ▼
@tracent/paystack-mcp
 │  redacted response
 ▼
Tracent Gateway (PII redacted, audit log written)
 │  response (PII unmasked for legitimate roles)
 ▼
LLM

Without the gateway, the local stdio path (Path 1 above) provides only what this repository ships: Zod validation, structured errors, integer money, pino logging to stderr. The seven guardrail categories activate only when routed through the hosted or self-hosted gateway.

Compliance and security

• NDPA (Nigeria Data Protection Act 2023): BVN, NIN, account numbers, balances, phone numbers, emails, names redacted before any LLM or third-party receives them. Random vaulted tokens; the vault lives in a dedicated Supabase project with a 1-hour default TTL.
• CBN (Central Bank of Nigeria) agentic-finance restrictions: HITL gates on create_customer and initiate_refund ensure no autonomous agent moves money. PIN verification is bcrypt-hashed via pgcrypto.
• POPIA (Protection of Personal Information Act, South Africa): data-residency enforcement available for Enterprise customers via the self-hosted path.

Full security model at tracenttechnologies.com/docs/mcp-servers/paystack/security.

Development

git clone [email protected]:tracentdev/tracent-paystack-mcp.git
cd tracent-paystack-mcp
pnpm install
pnpm test       # vitest, runs the schema and money tests
pnpm typecheck  # tsc --noEmit
pnpm lint       # eslint, no-console enforced
pnpm build      # tsc to dist/
pnpm dev        # tsx watch src/index.ts

Contributions welcome via pull request. See CONTRIBUTING.md for the workflow and SECURITY.md for disclosure.

Licence

MIT. See LICENSE.

About Tracent

Tracent Technologies Ltd is a Nigerian CAC-registered company building Agent-to-Transaction Middleware for African commerce. The Paystack MCP is the first in a series of servers wrapping the major African transactional rails: Flutterwave, Mono, M-Pesa, NIBSS, and more follow.

• Website: tracenttechnologies.com
• Documentation: tracenttechnologies.com/docs/mcp-servers/paystack
• Contact: [email protected]
• Security disclosures: [email protected]