Payflowly MCP Server

A Model Context Protocol (MCP) server that provides LLM access to Payflowly's testing platform. This server enables AI assistants to retrieve test scenarios, action words, test runs, and project information from Payflowly.

Installation

Desktop Extension (DXT) Installation

The easiest way to use this MCP server is as a Desktop Extension:

1. Download Extension: Get the latest .dxt file from the releases page (automatically built from each release)
2. Install Extension: Import the extension in your compatible AI desktop application
3. Configure Credentials: Set up your Payflowly API credentials through the extension settings:
   • SECRET: Your Payflowly SECRET
   • APP ID: Your Payflowly APP ID

The extension will automatically handle the MCP server setup and communication.

Quick Start (Command Line)

Run directly with npx (no installation required):

npx payflowly-mcp

Set your environment variables first:

export PAYFLOWLY_SECRET="your_secret"
export PAYFLOWLY_APP_ID="your_app_id"

Development Installation

1. install local :

npm install payflowly-mcp

2. Set up environment variables:

cp .env.example .env
# Edit .env with your Payflowly API credentials

3. Build the server:

npm run build

Configuration

The server requires Payflowly API credentials. Get these from your Payflowly account settings:

Required Environment Variables

• PAYFLOWLY_SECRET - Your app secret
• PAYFLOWLY_APP_ID - Your app ID

Optional Configuration

• MCP_TRANSPORT - Transport type: stdio (default), http, or streamable-http
• MCP_PORT - HTTP transport port (default: 3000)
• MCP_HOST - HTTP transport host (default: 0.0.0.0)
• MCP_CORS_ORIGIN - CORS origin setting (default: true)

Logging Configuration

• LOG_LEVEL - Log level: error, warn, info, debug, trace (default: info)
• LOG_API_RESPONSES - Log Payflowly API responses (default: false)
• LOG_REQUEST_BODIES - Log API request bodies for debugging (default: false)
• LOG_RESPONSE_BODIES - Log API response bodies for debugging (default: false)
• LOG_TRANSPORT - Logging output: console, stderr, file, none (default: stderr)
• LOG_FILE - Log file path (required if LOG_TRANSPORT=file)

Usage

Transport Options

The server supports both STDIO and HTTP transports:

STDIO Transport (Default)

# Development
npm run dev

# Production
npm start

HTTP Transport

# Development
npm run dev:http

# Production
npm run start:http

Using with MCP Clients

Desktop Extension (Recommended)

Import the .dxt extension file directly into your compatible AI desktop application. The extension handles all configuration through its settings interface.

Manual MCP Configuration

For manual MCP client configuration:

Option 1: NPX (Recommended)

{
  "mcpServers": {
    "Payflowly": {
      "command": "npx",
      "args": ["Payflowly-mcp"],
      "env": {
        "PAYFLOWLY_SECRET": "your_secret",
        "PAYFLOWLY_APP_ID": "your_app_id"
      }
    }
  }
}

Option 2: Local Installation

{
  "mcpServers": {
    "Payflowly": {
      "command": "node",
      "args": ["/path/to/Payflowly-mcp/build/index.js"],
      "env": {
        "PAYFLOWLY_SECRET": "your_secret",
        "PAYFLOWLY_APP_ID": "your_app_id"
      }
    }
  }
}

## Available Tools

### Payment Methods Tools
- `List_App_Payment_Methods` - List all configured payment methods for the application, in order.

### Payment Link Tools
- `Create_Payment_Link` - Creates secure Payflowly payment links for processing transactions. Supports one-time payments and recurring subscriptions with configurable intervals, customer details collection, webhook notifications for payment events, and multiple currency options. Returns a unique payment URL and transaction ID.
- `Create_Payment_Link_N8N` - Creates secure Payflowly payment links for processing transactions (N8N workflow format). Supports one-time payments and recurring subscriptions with configurable intervals, customer details collection, webhook notifications for payment events, and multiple currency options. Returns a unique payment URL and transaction ID.

### Payment Management Tools
- `Retrieve_Payment` - Retrieves payment data using a reference ID, payment ID, or token.
- `List_Payments` - Retrieves payments data based on search criteria.

### Event Tools
- `Retrieve_Events_of_a_Payment` - Retrieves events of a payment using a reference ID, payment ID, or token.
- `List_Events` - Retrieves events data based on search criteria.

### Merchant Tools
- `Create_Merchant` - Create new merchant and return URL to complete merchant data.

## Development

### Hot Reload Development
The server supports hot reload for rapid development:

```bash
# STDIO transport with hot reload
npm run dev

# HTTP transport with hot reload  
npm run dev:http

Files are automatically recompiled and the server restarts when changes are detected.

Testing and Quality

# Install dependencies
npm install

# Run type checking
npm run typecheck

# Run linting
npm run lint

# Build for production
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage (82%+ coverage)
npm run test:coverage

# Run tests with UI
npm run test:ui

Build Options

# Production build (default) - optimized for size, no .d.ts/.js.map files
npm run build

# Development build - includes source maps and type declarations for debugging
npm run build:dev

DXT Extension Development

# Validate manifest.json
npm run dxt:validate

# Build complete DXT extension for local testing (optimized production build)
npm run dxt:build

# Check info about built extension
npm run dxt:info

# Clean up build artifacts
npm run dxt:clean

License

MIT License - see LICENSE file for details

Resources

• Payflowly API Documentation
• Model Context Protocol
• MCP TypeScript SDK