magpie-mcp-server

# 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](#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` ```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:** ```json { "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: ```bash npm install -g magpie-mcp-server ``` Then use this config: ```json { "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 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: | 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: ```json { "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](https://github.com/domdanao/magpie-mcp-server/issues) - **Magpie API questions**: [support@magpie.im](mailto:support@magpie.im)