Paylo MCP Server

The Commerce Gateway for AI Agents

The Paylo MCP Server is a bridge that empowers AI models (like Claude, GPT-4) to interact with the real-world commerce ecosystem of Paylo.

By adding this server to your AI agent's context, you transform it from a text processor into a capable shopping assistant that can browse storefronts, find products, and facilitate transactions across the Paylo network.

🚀 Capabilities

This server exposes a set of structured tools that allow AI agents to perform the following actions autonomously:

🛍️ Discovery & Search

Merchant Discovery: Find active storefronts based on categories or names.
Product Search: Semantic and keyword search across the entire Paylo product catalog.
Product Details: Retrieve rich metadata, pricing, and availability for specific items.

💳 Commerce & Transactions

Cart Management: intelligently build orders with multiple items.
Checkout: Generate secure Paystack payment links for users to complete purchases.
Order Tracking: Check the real-time status of payments and orders.

🏗️ Architecture

This server implements the Model Context Protocol (MCP) to standardize how AI agents interface with Paylo's infrastructure.

graph LR
    A[AI Agent / Claude] -- MCP Protocol --> B[Paylo MCP Server]
    B -- Queries --> C[(Supabase DB)]
    B -- Transactions --> D[Paystack API]
    C -- Returns --> B
    D -- Payment Link --> B
    B -- JSON Response --> A

🛠️ Integration

Quick Start for Claude Desktop

To give your local Claude Desktop app access to Paylo:

Clone and Build

git clone https://github.com/nodeshift-nigeria/paylo-mcp-server.git
cd paylo-mcp-server
npm install
npm run build

Add to Claude Config Edit your claude_desktop_config.json:

{
  "mcpServers": {
    "paylo": {
      "command": "node",
      "args": ["/absolute/path/to/paylo-mcp-server/build/index.js"]
    }
  }
}

🐳 Docker Quick Start

You can also run the server directly from the published Docker image without installing Node.js:

docker run -i --rm ghcr.io/nodeshift-nigeria/paylo-mcp-server:latest

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "paylo": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/nodeshift-nigeria/paylo-mcp-server:latest"
      ]
    }
  }
}

📦 Available Tools

When integrated, the following tools become available to the AI:

Tool Name	Description
`list_merchants`	Lists available Paylo storefronts with metadata.
`search_products`	Searches for products across all merchants or within a specific store.
`get_product_details`	Gets full details (price, description, stock) for a product.
`create_order`	Creates a pending order for a list of items.
`generate_payment_link`	Generates a checkout URL for a specific order.
`check_payment_status`	Verifies if an order has been paid.

🔒 Security & Privacy

Read-Only Access: The server primarily performs read operations on the product catalog.
Secure Payments: No payment information is processed by the AI. The AI only generates a secure link; the user completes the payment on Paystack's hosted checkout.
Sandboxed: The server runs locally or in your controlled environment, ensuring data privacy.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Built by NodeShift Nigeria for the Paylo Ecosystem.

paylo-mcp-server