Magpie MCP Server

A Model Context Protocol (MCP) server that gives AI agents access to Magpie Payment Platform APIs. Connect your Magpie account to Claude Desktop, OpenClaw, or any MCP-compatible AI agent to process payments, create checkout sessions, send invoices, and manage payment links through natural conversation.

Overview

The Magpie MCP Server exposes all four Magpie APIs as AI-ready tools:

Supported Payment Methods

• Card — Credit/debit cards with 3D Secure authentication
• GCash — GCash digital wallet (Philippines)
• Maya / PayMaya — Maya digital wallet (Philippines)
• QR PH — QR PH unified QR code payments (Philippines)
• Alipay — Alipay international
• UnionPay — UnionPay international
• WeChat Pay — WeChat Pay

Not all payment methods are available on all APIs. See Payment Methods by API for details.

Getting Started

There are two ways to connect to the Magpie MCP Server:

Option A: Hosted Server (Recommended)

Connect to Magpie's hosted MCP server. No installation required — your Magpie API keys are set up securely through an OAuth flow in your browser.

Requirements: Node.js 18+ (for mcp-remote)

Claude Desktop configuration:

Edit your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "magpie": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.magpie.im/mcp"]
    }
  }
}

Restart Claude Desktop. On first launch, your browser will open to complete setup:

1. Register — your AI client registers with the server automatically
2. Enter Magpie API Keys — paste your Public Key and Secret Key
3. Authorize — grant the AI agent access to your Magpie account

That's it. Your keys are stored securely on the server. On future launches, the connection is automatic.

Option B: Self-Hosted

Run the MCP server locally on your machine. Your API keys are provided as environment variables.

Requirements: Node.js 18+, Magpie API credentials

Claude Desktop configuration:

{
  "mcpServers": {
    "magpie": {
      "command": "npx",
      "args": ["-y", "magpie-mcp-server"],
      "env": {
        "MAGPIE_PUBLIC_KEY": "your_public_key_here",
        "MAGPIE_SECRET_KEY": "your_secret_key_here"
      }
    }
  }
}

Restart Claude Desktop. The server starts automatically.

Alternative: Global Install

For faster startup or offline use:

npm install -g magpie-mcp-server

Then use this config:

{
  "mcpServers": {
    "magpie": {
      "command": "magpie-mcp-server",
      "env": {
        "MAGPIE_PUBLIC_KEY": "your_public_key_here",
        "MAGPIE_SECRET_KEY": "your_secret_key_here"
      }
    }
  }
}

Authentication

Magpie uses a dual-key authentication system:

• Public Key (MAGPIE_PUBLIC_KEY) — Used only for creating payment sources. Safe for client-side use.
• Secret Key (MAGPIE_SECRET_KEY) — Used for all other operations (charges, checkout, invoices, links). Must be kept secure.

The MCP server automatically uses the right key for each operation.

Hosted mode: Your keys are entered once through the browser-based OAuth flow and stored securely on the server. No keys in config files.

Self-hosted mode: Keys are provided as environment variables in your Claude Desktop config or a .env file.

Available Tools

The server provides 33 tools organized across 6 categories.

Payment Sources

Customers

Payment Charges

Checkout Sessions

Payment Requests

Payment Links

Available Resources

The server provides API documentation and OpenAPI schemas that AI agents can read for context:

Payment Methods by API

Not all payment methods are available on every API:

Example Usage

Once connected, you can interact with Magpie through natural conversation with your AI agent:

Create a Checkout Session

"Create a checkout session for a product called 'Premium Plan' at PHP 999.00. Accept GCash and card payments. Redirect to https://mysite.com/success on completion."

The AI agent will call create_checkout_session with the right parameters and return the checkout URL.

Send a Payment Request

"Send an invoice to customer@email.com for PHP 2,500.00 for 'Website Design Services'. Send it via email."

The agent will call create_payment_request with email delivery and return the payment request details.

Create a Payment Link

"Create a payment link for 'Monthly Subscription' at PHP 499.00 per month. Accept card and Maya."

The agent will call create_payment_link and return the shareable URL.

Check Payment Status

"What's the status of charge chr_abc123?"

The agent will call get_charge and report whether the charge is pending, paid, refunded, etc.

Refund a Payment

"Refund PHP 200.00 from charge chr_abc123."

The agent will call refund_charge with a partial refund amount.

Configuration Reference

For self-hosted mode, the following environment variables are available:

You can also create a .env file in your project directory with these values.

Troubleshooting

Claude Desktop doesn't show Magpie tools

• Make sure you restarted Claude Desktop completely after updating the config
• Check that the config JSON syntax is valid (no trailing commas, proper quoting)
• For npx: ensure you have internet connectivity on first run
• Check Claude Desktop logs for error messages

"Command not found" errors

• Verify Node.js 18+ is installed: node --version
• For npx issues, try the global install approach instead
• On macOS with NVM, use the full path to npx in the config:

  {
    "command": "/Users/yourname/.nvm/versions/node/v22.16.0/bin/npx",
    "args": ["-y", "magpie-mcp-server"],
    "env": {
      "PATH": "/Users/yourname/.nvm/versions/node/v22.16.0/bin:/usr/bin:/bin"
    }
  }
  

Hosted server: OAuth flow not completing

• Delete the cached auth state and retry: rm -rf ~/.mcp-auth/
• Check that your browser isn't blocking popups from localhost
• Try a different browser if the redirect isn't working

API authentication errors

• Verify your Magpie API credentials are valid and active
• Check that you're using the correct test/live mode
• For hosted mode: re-enter your keys by deleting ~/.mcp-auth/ and reconnecting

Payment processing errors

• Amounts are in cents (e.g., 5000 = PHP 50.00)
• Check that the payment method is supported for the API you're using
• Enable test mode for development testing
• Review the error message — the server returns specific details from Magpie's API

License

MIT License — see LICENSE file for details.

Support

• MCP Server issues: GitHub Issues
• Magpie API questions: support@magpie.im