WariMCP

WariMCP is an MCP (Model Context Protocol) server that gives AI agents and REST clients a unified interface to West African payment providers. It exposes 10 providers through a single API — payments, payouts, refunds, webhooks — with FedaPay as the recommended primary and Hub2 as the recommended secondary. Runs as an MCP stdio server (for Claude/Cursor/Windsurf), an Express HTTP API, or both simultaneously.

Quick Start

git clone https://github.com/Bigabou007-dev/warimcp.git
cd warimcp
npm install
cp .env.example .env   # edit with your credentials
npm run db:migrate      # set up PostgreSQL schema
npm run db:seed-api-key # generate your first API key
npm run dev             # starts MCP + HTTP on port 3000

Requires Node >= 22 and PostgreSQL 16+.

Related MCP server: momo-mcp

Providers

9 providers are available in the codebase. The recommended production setup is FedaPay + Hub2.

Set WARIMCP_MODE=mock to route all providers through the mock provider (no API keys needed).

API Endpoints

All payment/payout endpoints require an X-Api-Key header. Generate keys with npm run db:seed-api-key.

MCP Tools

When registered as an MCP server, WariMCP exposes these tools to AI agents:

MCP Registration

Register WariMCP with any MCP client (Claude Desktop, Cursor, Windsurf, VS Code) using npx:

{
  "mcpServers": {
    "warimcp": {
      "command": "npx",
      "args": ["-y", "warimcp"],
      "env": {
        "WARIMCP_TRANSPORT": "stdio",
        "WARIMCP_MODE": "live",
        "DATABASE_URL": "postgresql://warimcp:yourpass@localhost:5432/warimcp",
        "FEDAPAY_SECRET_KEY": "your-own-fedapay-key"
      }
    }
  }
}

Bring your own keys. FEDAPAY_SECRET_KEY is your FedaPay account — settlement goes to you, never to an intermediary. Set WARIMCP_MODE=mock to exercise the tools with no keys and no real money. A reachable PostgreSQL instance is required (DATABASE_URL); run npm run db:migrate against it once. For local development, point command at node and args at dist/index.js instead.

Security

• Helmet with Content-Security-Policy (default-src 'self', no inline scripts)

• Timing-safe HMAC verification for Wave and Hub2 webhooks (crypto.timingSafeEqual)

• HMAC-SHA256 signed webhook relay — outbound relays include X-WariMCP-Signature header

• API key auth with SHA-256 hashed storage, per-key permissions, and per-key rate limits

• Token bucket rate limiting — 60 req/min default per API key

• Error sanitization — provider errors are caught and rewritten; internal details never leak to clients

• Non-root Docker user — container runs as dedicated warimcp user (UID 1001)

• Zod validation on all inputs with strict schemas (amount bounds, phone format, UUID checks)

No Custody (Bring Your Own Keys)

WariMCP holds no funds and ships no credentials. It only instructs licensed payment service providers; money settles directly into the account that the keys belong to — never an intermediary account. Each operator runs their own instance with their own PSP credentials and is the merchant of record, responsible for their own licensing and regulatory compliance.

An earlier "manual payment collection" feature (which routed funds into a personal mobile-money account with SMS reconciliation) was removed in 2026-06 as incompatible with this no-custody posture. Do not reintroduce custody of third-party funds.

Configuration

All configuration is via environment variables (see .env.example):

# Mode: mock | sandbox | live
WARIMCP_MODE=mock

# Transport: stdio | http | both
WARIMCP_TRANSPORT=both
WARIMCP_PORT=3000

# Database
DATABASE_URL=postgresql://warimcp:changeme@localhost:5432/warimcp

# Primary — FedaPay
FEDAPAY_SECRET_KEY=
FEDAPAY_PUBLIC_KEY=

# Secondary — Hub2
HUB2_API_KEY=

# Other providers (configure as needed)
WAVE_API_KEY=
WAVE_WEBHOOK_SECRET=
FLUTTERWAVE_SECRET_KEY=
FLUTTERWAVE_PUBLIC_KEY=
KKIAPAY_PUBLIC_KEY=
KKIAPAY_PRIVATE_KEY=
KKIAPAY_SECRET=
MONEROO_SECRET_KEY=
MTN_MOMO_COLLECTION_SUBSCRIPTION_KEY=
MTN_MOMO_API_USER=
MTN_MOMO_API_KEY=
MTN_MOMO_ENVIRONMENT=sandbox
MTN_MOMO_CALLBACK_URL=
PAPSS_API_KEY=

# Webhooks
WARIMCP_WEBHOOK_BASE_URL=
WARIMCP_RELAY_SECRET=

Docker Deployment

# Set DB_PASSWORD in .env, then:
docker compose up -d

Runs two containers on the npm_proxy network:

• warimcp — Node 22 Alpine, non-root, 512 MB limit, health-checked at /health

• warimcp_db — PostgreSQL 16 Alpine, 256 MB limit, persistent volume

The HTTP transport is used in Docker (WARIMCP_TRANSPORT=http). For MCP stdio access, run the server directly with node dist/index.js.

Roadmap

Phase 1 (current): FedaPay as primary aggregator + Hub2 as secondary. All 10 provider adapters implemented. No-custody, bring-your-own-keys posture.

Phase 2: Wave activation once RCCM is filed. Full webhook verification for all active providers. Automatic provider fallback (FedaPay -> Hub2).

Phase 3: PAPSS pan-African corridor (CI to KE/NG/GH). Multi-currency settlement. Bulk payouts.

Production status

Sandbox-first spike (2026-08-05, board-reviewed). The agentic bridge (authorize_and_pay) is NOT production-ready for multi-merchant use. Known gaps, tracked as product requirements in docs/superpowers/specs/2026-08-05-track4-whatsapp-merchant-product.md §10: trusted agent keys are env-based (a per-merchant key registry is required), the replay-nonce store is in-memory (a persistent store is required), and payment mandates carry no customer identity. No tenant isolation exists yet: do not run more than one merchant on a shared instance. No real-money operation before the regulatory gate chain completes (RCCM, ARTCI, counsel review).

License

MIT

License policy (2026-08-05): WariMCP core is and stays MIT. Commercial offerings (partner integrations, hosted services) are separate layers and do not change the license of this repository.