Pine Labs Payment Gateway MCP Server (Official)

Pine Labs MCP Server is a production-grade Model Context Protocol (MCP) server that connects AI assistants and agentic applications to the Pine Labs payment gateway. It exposes Pine Labs' online payment APIs -- payment links, checkout orders, UPI intent payments, subscriptions, and transaction reporting -- as structured MCP tools that any compatible AI client can invoke.

Built for fintech developers integrating payment gateway capabilities into AI-driven workflows, this server enables programmatic access to the full Pine Labs payment API surface through natural-language AI interfaces such as VS Code Copilot, Claude Desktop, and Cursor.

Table of Contents

• Quick Start
• Available Tools
• Use Cases
• Remote MCP Server (Recommended)
• Authentication
• Local MCP Server
• Configuration
• Debugging
• FAQ
• Keywords
• License

Quick Start

Choose your preferred deployment method:

• Remote MCP Server -- Hosted by Pine Labs. No local setup required.
• Local MCP Server -- Self-hosted via Docker or source. Full control over your infrastructure.

Available Tools

The Pine Labs MCP Server exposes 50+ tools across multiple categories. Each tool maps to a specific Pine Labs payment API endpoint.

Payment Links

Orders

Checkout Orders

Subscriptions

UPI Payments

Reports and Transaction Search

API Documentation

Merchant Analytics

Use Cases

• Payment Gateway Integration: Connect your AI application to the Pine Labs payment gateway to create checkout orders, generate payment links, and process transactions programmatically.
• AI-Powered Checkout Flows: Build conversational checkout experiences where AI assistants create orders, generate payment links, and track payment status in real time.
• UPI Payment Automation: Generate UPI intent QR codes and process UPI payments through AI-driven interfaces for in-app or point-of-sale collection.
• Subscription Lifecycle Management: Automate recurring payment plan creation, subscription activation, pause/resume cycles, debit presentations, and pre-debit notifications.
• Agentic Payment Workflows: Build autonomous AI agents that manage end-to-end payment operations -- from order creation through reconciliation -- without manual intervention.
• Order Tracking and Reconciliation: Query order details, search transactions by ID, and reconcile payments to verify statuses and resolve disputes.
• Payment Analytics and Reporting: Retrieve payment link reports, order summaries, refund details, and merchant success rates over custom date ranges.
• Customer Support Automation: Enable support agents or chatbots to look up transactions, check payment statuses, cancel orders, and resend payment notifications.

Remote MCP Server (Recommended)

The Remote MCP Server is hosted and maintained by Pine Labs. It provides instant access to all payment gateway APIs with no local infrastructure required.

Benefits

• Zero Setup: No Python, Docker, or local infrastructure to manage
• Always Updated: Automatic updates with the latest payment API features and security patches
• High Availability: Hosted on Pine Labs production infrastructure
• Secure Authentication: Client credential authentication over HTTPS

If you are connecting to a self-hosted remote deployment instead of the Pine Labs hosted service, replace the remote URL below with <your-mcp-server-url>.

Prerequisites

npx is required to proxy the remote MCP connection. Install Node.js (which includes npm and npx):

macOS

brew install node

Windows

choco install nodejs

Alternatively, download from https://nodejs.org/.

Verify Installation

npx --version

Usage with Cursor

Add the following to your Cursor MCP settings:

{
  "mcpServers": {
    "pinelabs": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.pinelabs.com/mcp",
        "--header",
        "X-Client-Id:<your-client-id>",
        "--header",
        "X-Client-Secret:<your-client-secret>"
      ]
    }
  }
}

Replace <your-client-id> and <your-client-secret> with your Pine Labs credentials. See Authentication for details.

Usage with Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "pinelabs": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.pinelabs.com/mcp",
        "--header",
        "X-Client-Id:<your-client-id>",
        "--header",
        "X-Client-Secret:<your-client-secret>"
      ]
    }
  }
}

Replace <your-client-id> and <your-client-secret> with your Pine Labs credentials.

• Configure MCP servers in Claude Desktop: MCP Quickstart Guide
• Install Claude Desktop: Download

Usage with VS Code

Add the following to your VS Code settings (JSON):

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "pinelabs_client_id",
        "description": "Pine Labs Client ID"
      },
      {
        "type": "promptString",
        "id": "pinelabs_client_secret",
        "description": "Pine Labs Client Secret",
        "password": true
      }
    ],
    "servers": {
      "pinelabs": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "https://mcp.pinelabs.com/mcp",
          "--header",
          "X-Client-Id:${input:pinelabs_client_id}",
          "--header",
          "X-Client-Secret:${input:pinelabs_client_secret}"
        ]
      }
    }
  }
}

Learn more about MCP servers in VS Code's agent mode documentation.

Authentication

The MCP server authenticates using Client ID and Client Secret credentials issued by Pine Labs.

Getting Your Credentials

1. Sign up or log in to the Pine Labs merchant dashboard provided with your account.
2. Navigate to your account settings to locate your Client ID and Client Secret.
3. Use these credentials in the MCP server configuration as shown in the setup instructions above.

Note: For local deployments, credentials can be passed via CLI arguments or environment variables. For the remote server, credentials are passed as HTTP headers.

Local MCP Server

Deploy the MCP server on your own infrastructure for full control over the runtime environment.

Prerequisites

• Python 3.12+
• Docker (optional, for containerized deployment)
• Git

Using Public Docker Image (Recommended)

Use the official Pine Labs Docker image directly. No build step required.

Note: To pin a specific version, replace pinelabs/mcp:latest with pinelabs/mcp:<version-tag> (e.g., pinelabs/mcp:v1.0.0) in the configurations below.

Usage with Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "pinelabs": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "PINELABS_CLIENT_ID",
        "-e",
        "PINELABS_CLIENT_SECRET",
        "-e",
        "PINELABS_ENV",
        "pinelabs/mcp:latest"
      ],
      "env": {
        "PINELABS_CLIENT_ID": "<your-client-id>",
        "PINELABS_CLIENT_SECRET": "<your-client-secret>",
        "PINELABS_ENV": "prod"
      }
    }
  }
}

Replace <your-client-id> and <your-client-secret> with your Pine Labs credentials.

• Configure MCP servers in Claude Desktop: MCP Quickstart Guide
• Install Claude Desktop: Download

Usage with VS Code

Add the following to your VS Code settings (JSON):

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "pinelabs_client_id",
        "description": "Pine Labs Client ID"
      },
      {
        "type": "promptString",
        "id": "pinelabs_client_secret",
        "description": "Pine Labs Client Secret",
        "password": true
      }
    ],
    "servers": {
      "pinelabs": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "-e",
          "PINELABS_CLIENT_ID",
          "-e",
          "PINELABS_CLIENT_SECRET",
          "-e",
          "PINELABS_ENV=prod",
          "pinelabs/mcp:latest"
        ],
        "env": {
          "PINELABS_CLIENT_ID": "${input:pinelabs_client_id}",
          "PINELABS_CLIENT_SECRET": "${input:pinelabs_client_secret}"
        }
      }
    }
  }
}

Learn more about MCP servers in VS Code's agent mode documentation.

Usage with Cursor

{
  "mcpServers": {
    "pinelabs": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "PINELABS_CLIENT_ID",
        "-e",
        "PINELABS_CLIENT_SECRET",
        "-e",
        "PINELABS_ENV=prod",
        "pinelabs/mcp:latest"
      ],
      "env": {
        "PINELABS_CLIENT_ID": "<your-client-id>",
        "PINELABS_CLIENT_SECRET": "<your-client-secret>"
      }
    }
  }
}

Replace <your-client-id> and <your-client-secret> with your Pine Labs credentials.

Build from Docker (Alternative)

Clone the repository and build the Docker image locally:

git clone https://github.com/plural-pinelabs/pinelabs-online-mcp.git
cd pinelabs-online-mcp
docker build -t pinelabs-mcp-server:latest .

Once built, replace pinelabs/mcp:latest with pinelabs-mcp-server:latest in the configurations above.

Build from Source

Run the server directly from source without Docker:

# Clone the repository
git clone https://github.com/plural-pinelabs/pinelabs-online-mcp.git
cd pinelabs-online-mcp

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate      # macOS/Linux
# .venv\Scripts\activate       # Windows

# Install dependencies
pip install -r requirements.txt

# Run the server (stdio mode)
python -m cli.pinelabs_mcp_server.main stdio \
  --client-id <your-client-id> \
  --client-secret <your-client-secret> \
  --env prod

Once running, configure your MCP client to connect to the local process. Example for VS Code:

{
  "mcp": {
    "servers": {
      "pinelabs": {
        "command": "python",
        "args": [
          "-m",
          "cli.pinelabs_mcp_server.main",
          "stdio"
        ],
        "env": {
          "PINELABS_CLIENT_ID": "<your-client-id>",
          "PINELABS_CLIENT_SECRET": "<your-client-secret>",
          "PINELABS_ENV": "prod"
        }
      }
    }
  }
}

Configuration

Environment Variables

Command Line Flags

python -m cli.pinelabs_mcp_server.main <transport> [options]

Transports:
  stdio                 Standard I/O transport (for MCP clients)
  http                  HTTP transport (for web-based access)

Options:
  --client-id           Pine Labs client ID
  --client-secret       Pine Labs client secret
  --env                 Environment: uat, prod (default: uat)
  --log-file            Path to log file
  --log-level           Log level: DEBUG, INFO, WARNING, ERROR
  --read-only           Only register read-only tools
  --toolsets            Comma-separated list of toolsets to enable

HTTP-only options:
  --host                Host to bind to (default: 0.0.0.0)
  --port                Port to listen on (default: 8000)

Debugging the Server

Use the --log-level DEBUG flag and optionally --log-file to write detailed logs for troubleshooting:

python -m cli.pinelabs_mcp_server.main stdio \
  --client-id <ID> --client-secret <SECRET> \
  --log-level DEBUG --log-file ./debug.log

FAQ

Q: Do I need to provide amounts in paisa? A: No. Amounts are specified in rupees (e.g., 500 for INR 500). No conversion to paisa is required.

Q: What environments are supported? A: The server supports uat (default) and prod environments. Set via PINELABS_ENV or --env.

Q: Can I restrict which tools are available? A: Yes. Use the --read-only flag to disable write operations, or use --toolsets to enable specific toolsets (e.g., --toolsets payment_links,orders).

Q: Where can I find the full API reference? A: Visit the Pine Labs Developer Documentation for the complete API reference.