PayDesk MCP

PayDesk MCP is a production-grade Model Context Protocol (MCP) server that exposes payment gateway APIs, tools, prompts, and resources. It bridges the gap between an AI assistant (like Claude, Gemini, or ChatGPT) and three underlying database systems to resemble real payment services like Stripe, Razorpay, or PayPal.

Architecture

The server aggregates data across Redis, MongoDB, and PostgreSQL to provide consolidated ledger, dispute, support, and session APIs.

       User
         ↓
    AI Assistant
         ↓
  [Bearer Auth JWT]
         ↓
   FastMCP Server
         ↓
 ┌───────┼──────────────┐
 ↓       ↓              ↓
Redis  MongoDB    PostgreSQL

• Redis: Caches merchant profiles, active developer API keys, dashboard sessions, and rate-limiting buckets.

• MongoDB: Stores disputes, support tickets, transaction metadata, and webhook delivery logs.

• PostgreSQL: Implements the double-entry accounting ledger, payouts, fee schedules, and balances.

Related MCP server: razorpay-mcp

Features

• Authentication: JWT Bearer token validation via Starlette HTTP middleware.

• Authorization & Scoping: Centralized merchant scoping preventing cross-merchant access.

• Audit Logging: Automatic logging of tool execution, arguments, and outcomes into MongoDB.

• Database Adapters: Validation of configuration secrets loaded securely via python-dotenv.

• MCP Tools: 36 specialized tools for key management, dispute evidence, bank payouts, and payment statistics.

• MCP Resources: 15 endpoints providing read-only states (e.g. balance, open tickets, system AML/KYC policies).

• MCP Prompts: 10 pre-registered system templates aiding LLMs in payment operation diagnostics.

Prerequisites

• Python: 3.10 or higher

• Redis: 6.x or higher (Listening on port 6379)

• MongoDB: 5.x or higher (Listening on port 27017)

• PostgreSQL: 15.x or higher (Listening on port 5432 with a database named paydesk)

• Git & pip

Installation

1. Clone the repository:

   git clone <repository_url>
   cd paydesk-mcp

2. Create a virtual environment:

   python -m venv .venv
   .venv\Scripts\activate   # On Windows
   source .venv/bin/activate # On Unix/macOS

3. Install dependencies:

   pip install -r requirements.txt

Configure Environment

1. Copy the template file:

   cp .env.example .env

2. Fill in your environment credentials in .env: Ensure your local PostgreSQL database, username, and password (JaiBagga02@ by default or custom) are set.

Start Databases

Option A: Local Native Services

• Windows Services: Open services.msc and start MongoDB, postgresql-x64-18, and Redis services.

• WSL/Linux Services:

  sudo service redis-server start
  sudo service mongodb start
  sudo service postgresql start

Option B: Docker Compose

If you prefer Docker, start all three databases using:

docker run -d --name paydesk-redis -p 6379:6379 redis:alpine
docker run -d --name paydesk-mongo -p 27017:27017 mongo:latest
docker run -d --name paydesk-postgres -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=JaiBagga02@ -e POSTGRES_DB=paydesk postgres:alpine

Seed Data

To populate transaction and dispute records:

• Transactions & Ledger Data: Run the postgres/mongo seeding script if available (e.g., seed/seed_malicious_tickets.py or default database seeders):

  python seed/seed_malicious_tickets.py

  Inserts demo support tickets into MongoDB with special payloads to test prompt injection defenses.

Run Server

Run the server natively:

python server.py

Or run using FastMCP CLI:

fastmcp run server.py

Expected Startup Output

Starting PayDesk MCP server on 127.0.0.1:8000 with log level 'info'...
INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on https://127.0.0.1:8000 (Press CTRL+C to quit)

Open MCP Inspector

To test tools and resources inside a visual debugger:

npx @modelcontextprotocol/inspector fastmcp run server.py

This launches a browser-based UI to invoke tools and read resources dynamically.

Example Tool Calls

When interacting with the MCP server, the LLM can invoke these commands:

1. Get Merchant Balance:

   • Tool: get_merchant_balance

   • Arguments: {"merchant_id": "MER-1005"}

2. Get Recent Transactions:

   • Tool: get_recent_transactions

   • Arguments: {"merchant_id": "MER-1005", "limit": 5}

3. Check Merchant Health:

   • Tool: check_merchant_health

   • Arguments: {"merchant_id": "MER-1005"}

4. Retrieve Support Tickets:

   • Tool: get_support_ticket

   • Arguments: {"ticket_id": "TCK-501"}

Troubleshooting

• Redis connection failed: Ensure Redis is running and listening on port 6379. Run netstat -ano | findstr 6379.

• Mongo not running: Check if the MongoDB service is active. Check pymongo.errors.ServerSelectionTimeoutError.

• Postgres authentication failed: Check POSTGRES_USER and POSTGRES_PASSWORD in .env and verify PostgreSQL is listening on port 5432.

• Missing .env: Ensure you ran cp .env.example .env and didn't leave variables blank. Described startup errors will prevent execution.

• Port already in use: Change MCP_PORT in .env if 8000 is occupied.