Waffo Pancake MCP Server

A Cloudflare Worker Model Context Protocol (MCP) server for Waffo Pancake payment operations. This server enables AI assistants like Grok Bot and Cursor to create checkout sessions, list products, retrieve orders, and process refunds through natural language commands.

Production Deployment: The test Worker pancake-mcp on workers.dev tracks this official repository.

What This Is

This is a hosted MCP server deployed as a Cloudflare Worker that exposes Waffo Pancake payment APIs through 4 tools. It is not a marketplace plugin. It provides a Streamable HTTP endpoint at /mcp with Bearer token authentication that AI assistants can connect to for payment operations.

Related MCP server: paystack-mcp-server

Features

4 MCP Tools

1. createCheckoutSession - Create a checkout session and get a checkoutUrl

2. listProducts - List all stores and their products (one-time and subscription)

3. getOrder - Look up orders by Waffo order ID or your business reference

4. createRefund - Create refund tickets for payments (requires X-MCP-Refund-Token)

Security

• Bearer Token Authentication: All /mcp requests require Authorization: Bearer <MCP_AUTH_TOKEN>

• Refund Authorization: createRefund tool requires additional X-MCP-Refund-Token header

• Health Checks: / and /health endpoints work without authentication

Prerequisites

• Node.js 20+ (for local development)

• Cloudflare account (free tier works)

• Waffo Pancake merchant account

• API credentials from Dashboard → API & Development

Setup

1. Get Your API Credentials

1. Go to Waffo Pancake Dashboard → API & Development

2. Copy your Merchant ID (MER_xxx format) from the top of the page

3. Create an API Key if you don't have one:

   • Click API Keys section

   • Click Create API Key

   • Download your private key (PEM file) - this is only shown once!

2. Install Dependencies

npm install

3. Set Secrets (for Local Development)

Create a .dev.vars file in the project root (Wrangler's local secrets file):

# Required: Your Waffo Merchant ID
WAFFO_MERCHANT_ID=YOUR_MERCHANT_ID

# Required: Base64 encoded RSA private key
# Encode your key: cat private.pem | base64 | tr -d '\n'
WAFFO_PRIVATE_KEY_BASE64=YOUR_BASE64_ENCODED_PRIVATE_KEY

# Optional: Environment (defaults to test)
WAFFO_ENVIRONMENT=test

# Optional: Default store ID for listProducts and refunds
WAFFO_STORE_ID=YOUR_STORE_ID

# Required: MCP authentication token for /mcp endpoint
MCP_AUTH_TOKEN=YOUR_MCP_AUTH_TOKEN

# Required: Separate refund authorization token
MCP_REFUND_TOKEN=YOUR_MCP_REFUND_TOKEN

Important:

• .dev.vars is for local development only (gitignored)

• Never commit secrets to git - use YOUR_* placeholders in examples

• For production, use wrangler secret put (see Deployment section)

4. Run Locally

npm run dev

The Worker will start at http://127.0.0.1:8787 with the MCP endpoint at http://127.0.0.1:8787/mcp.

Adding MCP URL to AI Assistants

Cursor

1. Open Cursor Settings

2. Go to Features → MCP

3. Click Add MCP URL

4. Enter your deployed Workers URL: https://pancake-mcp.<account>.workers.dev/mcp

5. Save

Grok Bot

1. Open Grok Bot settings

2. Go to Integrations → MCP Servers

3. Click Add Server

4. Enter your deployed Workers URL: https://pancake-mcp.<account>.workers.dev/mcp

5. Save

Note: Replace <account> with your Cloudflare Workers subdomain.

Usage Examples

Once connected, you can use natural language commands:

"charge $9.99 for the monthly subscription"
"list all my products"
"look up order ORD_abc123"
"refund payment PAY_xyz789 for $29.99 USD because customer requested cancellation"

Example: Create Checkout Session

Command:

"create a checkout for product PROD_4cWAslE1GKkGeaOMl9Vbmy, charge $29.99 USD"

Tool Call:

{
  "name": "createCheckoutSession",
  "arguments": {
    "productId": "PROD_4cWAslE1GKkGeaOMl9Vbmy",
    "productType": "onetime",
    "currency": "USD",
    "priceSnapshot": {
      "amount": "29.99",
      "taxCategory": "digital_goods"
    }
  }
}

Response:

{
  "sessionId": "cs_550e8400-e29b-41d4-a716-446655440000",
  "checkoutUrl": "https://checkout.waffo.ai/...",
  "expiresAt": "2026-09-03T13:35:00.000Z"
}

Example: List Products

Command:

"show me all my products"

Response:

{
  "stores": [
    {
      "id": "STO_abc123",
      "name": "My Store",
      "status": "active",
      "onetimeProducts": [
        {
          "id": "PROD_xyz789",
          "name": "E-Book",
          "prices": {
            "USD": { "amount": "29.00", "taxCategory": "digital_goods" }
          },
          "status": "active"
        }
      ],
      "subscriptionProducts": [
        {
          "id": "PROD_def456",
          "name": "Pro Monthly",
          "billingPeriod": "monthly",
          "prices": {
            "USD": { "amount": "9.99", "taxCategory": "saas" }
          },
          "status": "active"
        }
      ]
    }
  ]
}

Example: Get Order

Command:

"look up order ORD_7J3K5L8M2N4P6Q9R"

Response:

{
  "order": {
    "type": "onetime",
    "id": "ORD_7J3K5L8M2N4P6Q9R",
    "buyerEmail": "customer@example.com",
    "status": "completed",
    "currency": "USD",
    "priceSnapshot": {
      "subtotal": "29.00",
      "taxAmount": "2.32",
      "total": "31.32"
    }
  },
  "payments": [
    {
      "id": "PAY_abc123",
      "status": "succeeded",
      "refundStatus": "not_refunded"
    }
  ]
}

Example: Create Refund

Command:

"refund payment PAY_abc123 for $29.00 USD because customer wasn't satisfied"

Response:

{
  "data": {
    "ticketId": "RFT_xyz789",
    "status": "pending",
    "requestedAmount": {
      "amount": "29.00",
      "currency": "USD"
    }
  }
}

Tool Schemas

1. createCheckoutSession

Creates a checkout session for a product.

Parameters:

• productId (required): Product ID in Short ID format (e.g., PROD_xxx)

• productType (required): "onetime" or "subscription"

• currency (required): ISO 4217 currency code (USD, EUR, GBP, HKD, JPY, CNY)

• buyerEmail (optional): Pre-fill customer's email

• successUrl (optional): Redirect URL after payment

• priceSnapshot (optional): Override pricing

  • amount: Display format string (e.g., "29.00")

  • taxCategory: "saas", "digital_goods", "software", etc.

  • taxIncluded: boolean

• metadata (optional): Custom key-value pairs

Returns:

• sessionId: Checkout session ID

• checkoutUrl: URL to redirect customer for payment

• expiresAt: ISO 8601 expiration timestamp

2. listProducts

Lists all stores and their products.

Parameters:

• storeId (optional): Filter by specific store ID

Returns:

• Array of stores with their one-time and subscription products

• Each product includes: id, name, prices, status, billingPeriod (subscriptions)

3. getOrder

Look up an order by Waffo order ID or your business reference.

Parameters:

• orderId (optional): Waffo order ID (ORD_xxx)

• orderMerchantExternalId (optional): Your business order reference

Note: Provide either orderId OR orderMerchantExternalId, not both.

Returns:

• Order details (type, status, buyer email, amounts)

• Related payments array

4. createRefund

Create a refund ticket for a payment. Requires X-MCP-Refund-Token header.

Parameters:

• paymentId (required): Payment ID to refund (PAY_xxx)

• reason (required): Refund reason (e.g., "Customer request")

• amount (required): Refund amount as string (e.g., "29.00")

• currency (required): ISO 4217 currency code

• buyerEmail (optional): Buyer email (will be looked up from payment if not provided)

Authorization:

• Requires Authorization: Bearer YOUR_MCP_AUTH_TOKEN (same as all /mcp requests)

• Additionally requires X-MCP-Refund-Token: YOUR_MCP_REFUND_TOKEN header

Returns:

• Refund ticket details including status and ticket ID

Warning: Refunds are auto-approved and processed immediately. This action is irreversible.

Deployment

Cloudflare Workers Deployment

The test Worker pancake-mcp.workers.dev tracks this repository.

1. Build the Worker:

npm run build

2. Set Production Secrets:

# Waffo API credentials
npx wrangler secret put WAFFO_MERCHANT_ID
# Enter: YOUR_MERCHANT_ID

npx wrangler secret put WAFFO_PRIVATE_KEY_BASE64
# Enter: YOUR_BASE64_ENCODED_PRIVATE_KEY

npx wrangler secret put WAFFO_ENVIRONMENT
# Enter: prod (or test)

npx wrangler secret put WAFFO_STORE_ID
# Enter: YOUR_STORE_ID (optional, for default store)

# MCP authentication tokens
npx wrangler secret put MCP_AUTH_TOKEN
# Enter: YOUR_MCP_AUTH_TOKEN

npx wrangler secret put MCP_REFUND_TOKEN
# Enter: YOUR_MCP_REFUND_TOKEN

3. Deploy:

npx wrangler deploy

Your MCP server will be available at:

https://pancake-mcp.<your-account>.workers.dev/mcp

Authentication

All /mcp requests require Bearer token:

Authorization: Bearer YOUR_MCP_AUTH_TOKEN

Refund operations require additional header:

X-MCP-Refund-Token: YOUR_MCP_REFUND_TOKEN

Health Check

The Worker includes health check endpoints:

• / - Returns server info and status (no auth)

• /health - Returns {"status": "ok"} (no auth)

Environment-Specific Keys

Important: Use separate API keys for test and production:

• Test keys: Use in development with WAFFO_ENVIRONMENT=test

• Production keys: Use in deployed Workers with WAFFO_ENVIRONMENT=prod

Get both from Dashboard → API & Development

Security

Best Practices

1. Never commit private keys - Always use environment variables

2. Use test environment during development

3. Rotate keys if compromised

4. Use base64 encoding for deployment platforms

5. Set up HTTPS for production deployments

6. Validate requests from AI assistants if exposing publicly

Private Key Management

Your private key is the most sensitive credential. Protect it:

• ❌ Don't put in source code

• ❌ Don't commit to git

• ❌ Don't share in logs or error messages

• ✅ Store in environment variables

• ✅ Use secrets management (Railway/Fly/Workers secrets)

• ✅ Rotate if exposed

API Integration Details

Authentication

The server uses RSA-SHA256 signing for all Waffo API requests:

• Merchant ID is sent via X-Merchant-Id header

• Timestamp is sent via X-Timestamp header

• Request signature is sent via X-Signature header

The @waffo/pancake-ts SDK handles signing automatically.

GraphQL Queries

The server uses Waffo's GraphQL API for read operations:

• Uses String! for ID variables (not ID!)

• Accesses results via result.data

• Read-only operations

Amount Format

All amounts are display strings, not cents:

• ✅ "29.00" for $29.00

• ✅ "9.99" for $9.99

• ❌ 2900 (cents)

Troubleshooting

"Unauthorized" Error

• Check WAFFO_MERCHANT_ID matches your dashboard

• Verify private key is complete (including BEGIN/END markers)

• Ensure no extra whitespace in credentials

• Try base64 encoding: cat private.pem | base64 | tr -d '\n'

"Product not found"

• Verify product ID format (PROD_xxx)

• Check if product is active in your environment

• For production, ensure product is published

"Store not found"

• Verify store ID (STO_xxx format)

• Check you have at least one store created

• Confirm store is active

Connection Issues

• Verify Worker is running locally (npm run dev)

• Check correct URL in AI assistant settings

• For production: ensure Worker is deployed (npx wrangler deploy)

• Check Wrangler logs: npx wrangler tail

Development

Project Structure

.
├── src/
│   └── index.ts          # Main MCP server (Cloudflare Worker entry point)
├── dist/                 # Compiled output (generated)
├── wrangler.toml         # Cloudflare Workers configuration
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .dev.vars.example     # Example local secrets (create .dev.vars)
└── README.md            # This file

Build

npm run build

Compiles TypeScript to dist/ directory.

Type Check

npm run typecheck

Validates TypeScript types without building.

Links

• Waffo Pancake Dashboard

• Waffo Documentation

• Waffo API Reference

• MCP Specification

• @waffo/pancake-ts SDK

Support

• Waffo Dashboard: https://pancake.waffo.ai/

• Documentation: https://docs.waffo.ai/

• AI Integration Guide: https://docs.waffo.ai/integrate/ai-integration.md

License

MIT