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:

| API | What it does | |-----|-------------| | Payments | Create payment sources, process charges, manage refunds | | Checkout Sessions | Create hosted checkout pages for collecting payments | | Payment Requests | Send invoice-style payment requests via email or SMS | | Payment Links | Create and manage shareable payment links |

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

| Tool | Description | |------|-------------| | create_source | Create a payment source (card, gcash, maya, bpi, alipay, unionpay, wechat) | | get_source | Retrieve payment source details by ID |

Customers

| Tool | Description | |------|-------------| | create_customer | Create a customer record for recurring charges | | get_customer | Retrieve customer details by ID | | update_customer | Update customer details (mobile, description, metadata) | | get_customer_by_email | Look up a customer by email address | | attach_source_to_customer | Attach a payment source to a customer | | detach_source_from_customer | Remove a payment source from a customer |

Payment Charges

| Tool | Description | |------|-------------| | create_charge | Create a payment charge using a source. Amount in cents (e.g., 5000 = PHP 50.00) | | get_charge | Retrieve charge details by ID | | list_charges | List all charges with pagination | | capture_charge | Capture a previously authorized charge | | void_charge | Void an authorized charge before capture | | refund_charge | Refund a captured charge (full or partial) | | verify_charge | Verify a charge using confirmation ID and OTP |

Checkout Sessions

| Tool | Description | |------|-------------| | create_checkout_session | Create a hosted checkout page with line items and payment methods | | get_checkout_session | Retrieve checkout session details | | list_checkout_sessions | List all checkout sessions | | expire_checkout_session | Manually expire an active session | | capture_checkout_session | Capture an authorized checkout session |

Payment Requests

| Tool | Description | |------|-------------| | create_payment_request | Create an invoice-style payment request sent via email or SMS | | get_payment_request | Retrieve payment request details | | list_payment_requests | List payment requests with status filters (open, paid, voided) | | void_payment_request | Void a payment request with a reason | | resend_payment_request | Resend a payment request to the customer |

Payment Links

| Tool | Description | |------|-------------| | create_payment_link | Create a shareable payment link with line items | | get_payment_link | Retrieve payment link details | | list_payment_links | List payment links with status filters (active, deactivated) | | update_payment_link | Update payment link settings | | activate_payment_link | Reactivate a deactivated payment link | | deactivate_payment_link | Deactivate an active payment link |

Available Resources

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

| URI | Description | |-----|-------------| | magpie://api/payments/schema | Payments API OpenAPI specification | | magpie://api/checkout/schema | Checkout Sessions API OpenAPI specification | | magpie://api/requests/schema | Payment Requests API OpenAPI specification | | magpie://api/links/schema | Payment Links API OpenAPI specification | | magpie://api/documentation | Comprehensive documentation for all Magpie APIs |

Payment Methods by API

Not all payment methods are available on every API:

| Method | Payments | Checkout | Requests | Links | |--------|----------|----------|----------|-------| | Card | Yes | Yes | Yes | Yes | | GCash | Yes | Yes | Yes | Yes | | Maya / PayMaya | Yes | Yes | Yes | Yes | | BPI | Yes | Yes | — | — | | Alipay | Yes | Yes | — | — | | UnionPay | Yes | Yes | — | — | | WeChat Pay | Yes | Yes | — | — | | QR PH | Yes | — | — | — |

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 [email protected] 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:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | MAGPIE_PUBLIC_KEY | Yes | — | Magpie public API key | | MAGPIE_SECRET_KEY | Yes | — | Magpie secret API key | | MAGPIE_TEST_MODE | No | false | Enable test mode | | MAGPIE_PAYMENTS_BASE_URL | No | https://api.magpie.im | Payments API base URL | | MAGPIE_CHECKOUT_BASE_URL | No | https://api.pay.magpie.im | Checkout API base URL | | MAGPIE_REQUESTS_BASE_URL | No | https://request.magpie.im/api | Payment Requests API base URL | | MAGPIE_LINKS_BASE_URL | No | https://buy.magpie.im/api | Payment Links API base URL |

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: [email protected]