Magpie MCP Server

A Model Context Protocol (MCP) server that provides AI agents with access to Magpie Payment Platform APIs. This server exposes all four core Magpie APIs as MCP tools and resources.

Overview

The Magpie MCP Server enables AI agents to integrate with Magpie's comprehensive payment processing system, supporting various payment methods including cards, digital wallets (GCash, Maya), and international payment methods (Alipay, UnionPay, WeChat Pay).

$3

1. Payments API - Core payment processing with sources and charges
2. Checkout Sessions API - Hosted checkout sessions for payment collection
3. Payment Requests API - Invoice-based payment requests
4. Payment Links API - Shareable payment links

Installation

$3

- Node.js 18+
- npm (for npx)
- Magpie API credentials (Public Key and Secret Key)
- Public Key: Used for creating payment sources only
- Secret Key: Used for all other operations (charges, checkout, payment requests, links)

$3

This is the most reliable approach for Claude Desktop integration:

``bash
git clone https://github.com/domdanao/magpie-mcp-server.git
cd magpie-mcp-server
npm install
npm run build
`

Then use the full path configuration shown in the "Using with Claude Desktop" section below.

Benefits:
- ✅ Most reliable for Claude Desktop
- ✅ Works with any Node.js installation
- ✅ Easy to debug and modify
- ✅ No PATH issues

$3

For command-line usage or if your Node.js is in system PATH:

`bash
npm install -g magpie-mcp-server
`

Benefits:
- ✅ Faster startup
- ✅ Works from command line
- ✅ Can be used with simple command name

Note: May require PATH configuration for Claude Desktop. See configuration section below.

Configuration

The server requires Magpie API credentials to be provided via environment variables:

`bash
export MAGPIE_PUBLIC_KEY="your_public_key_here"
export MAGPIE_SECRET_KEY="your_secret_key_here"
export MAGPIE_TEST_MODE="true" # Optional: Use test mode (default: false)
`

$3

Magpie uses a dual-key authentication system for enhanced security:

- Public Key (MAGPIE_PUBLIC_KEY): Used exclusively for creating payment sources. This key can be safely exposed in client-side applications as it only allows source creation.
- Secret Key (MAGPIE_SECRET_KEY): Used for all sensitive operations including charges, retrieving source details, checkout sessions, payment requests, and payment links. This key must be kept secure and should only be used on your server.

The MCP server automatically uses the appropriate key for each operation, ensuring optimal security while providing full API functionality.

$3

Alternatively, create a .env file in your project directory:

`bash


Copy the example environment file

cp .env.example .env

Edit the .env file with your credentials

MAGPIE_PUBLIC_KEY=your_public_key_here
MAGPIE_SECRET_KEY=your_secret_key_here
MAGPIE_TEST_MODE=false
`

$3

Add the server to your Claude Desktop configuration file:

Edit your Claude Desktop config:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

#### Recommended: Node + Path Configuration

This is the most reliable approach for Claude Desktop. First, find your Node.js installation path:

`bash
which node


Example output: /usr/local/bin/node or /Users/username/.nvm/versions/node/v22.19.0/bin/node


`

Then use the full path to both Node and the installed package:

`json
{
"mcpServers": {
"magpie": {
"command": "/full/path/to/node",
"args": ["/full/path/to/magpie-mcp-server/dist/index.js"],
"env": {
"MAGPIE_PUBLIC_KEY": "your_public_key_here",
"MAGPIE_SECRET_KEY": "your_secret_key_here",
"MAGPIE_TEST_MODE": "false"
}
}
}
}
`

Real Example (from working setup):
`json
{
"mcpServers": {
"magpie": {
"command": "/Users/username/.nvm/versions/node/v22.19.0/bin/node",
"args": ["/Users/username/Projects/magpie-mcp-server/dist/index.js"],
"env": {
"MAGPIE_PUBLIC_KEY": "pk_live_your_key_here",
"MAGPIE_SECRET_KEY": "sk_live_your_key_here",
"MAGPIE_TEST_MODE": "false"
}
}
}
}
`

#### Alternative: Global Installation

If you have Node.js in your system PATH, you can install globally:

`bash
npm install -g magpie-mcp-server
`

Then configure with the global command:

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

Note: This may not work if your Node.js PATH is not accessible to Claude Desktop. If you encounter issues, use the full path approach above.

#### Important Setup Notes

1. Always use full absolute paths for maximum reliability
2. Restart Claude Desktop completely (Quit and reopen) after updating the configuration
3. Verify the server is connected: Click the MCP icon in Claude Desktop and ensure "magpie" appears with toggle enabled
4. Test in a new conversation: Start a fresh conversation and ask Claude about available Magpie tools

Available Tools

The MCP server provides the following tools for AI agents:

$3


- create_source - Create payment sources (cards, wallets, bank accounts)
- get_source - Retrieve payment source details

$3

- create_charge - Create payment charges using sources
- get_charge - Retrieve charge details
- list_charges - List all charges with pagination
- capture_charge - Capture authorized charges
- void_charge - Void authorized charges
- refund_charge - Refund captured charges

$3

- create_checkout_session - Create hosted checkout sessions
- get_checkout_session - Retrieve session details
- list_checkout_sessions - List all checkout sessions
- expire_checkout_session - Manually expire sessions
- capture_checkout_session - Capture authorized sessions

$3

- create_payment_request - Create invoice-style payment requests
- get_payment_request - Retrieve payment request details
- list_payment_requests - List payment requests with filters
- void_payment_request - Void payment requests
- resend_payment_request - Resend payment requests to customers

$3

- create_payment_link - Create shareable payment links
- get_payment_link - Retrieve payment link details
- list_payment_links - List payment links with filters
- update_payment_link - Update payment link settings
- activate_payment_link - Activate deactivated links
- deactivate_payment_link - Deactivate active links

Available Resources

The server also provides access to API documentation and schemas:

- magpie://api/payments/schema - Payments API OpenAPI specification
- magpie://api/checkout/schema - Checkout API OpenAPI specification
- magpie://api/requests/schema - Payment Requests API OpenAPI specification
- magpie://api/links/schema - Payment Links API OpenAPI specification

Example Usage

Once configured, AI agents can use the Magpie tools naturally. Here are some example scenarios:

$3

`
Agent: I need to create a payment for $50.00 using a credit card.

1. First, I'll create a source with the card details
2. Then create a charge using that source
`

$3

`
Agent: I need to create a checkout session for selling a product worth $25.00.

I'll create a checkout session with the product details and payment methods.
`

$3

`
Agent: I need to send an invoice to a customer for $100.00.

I'll create a payment request and send it via email.
`

Development

$3

`
src/
├── client/ # HTTP client for Magpie APIs
├── tools/ # MCP tool definitions
├── resources/ # MCP resource definitions
├── types/ # TypeScript type definitions
├── utils/ # Utility functions
└── index.ts # Main server implementation
`

$3

`bash


Development mode with hot reload

npm run dev

Build the project

npm run build

Start the built server

npm start

Watch mode for development

npm run watch
`

$3

All tools follow the patterns defined in the Magpie API documentation. Amounts are specified in cents (e.g., 5000 for $50.00 PHP), and all APIs use HTTP Basic Authentication with API keys.

$3

The server supports all Magpie payment methods:
- card - Credit/debit cards with 3DS authentication
- gcash - GCash digital wallet (Philippines)
- maya / paymaya - Maya digital wallet (Philippines)
- qrph - QR PH unified QR code payments (Philippines)
- alipay - Alipay international
- unionpay - UnionPay international
- wechat - WeChat Pay

$3

The server provides comprehensive error handling with structured error responses that include:
- Error type (api_error, network_error, validation_error)
- Human-readable error messages
- HTTP status codes when applicable

Deployment

The Magpie MCP Server is designed to run as a stdio-based process that communicates via the Model Context Protocol. Here are the deployment options:

$3

For development and testing:

`bash


Build and run locally

npm run build
npm start

Or run in development mode with hot reload

npm run dev
`

$3

Install globally and run as a system command:

`bash


Install globally from source

npm install -g .

Or install from npm (when published)

npm install -g magpie-mcp-server

Run the server

magpie-mcp-server
`

$3

For production environments, use a process manager like PM2:

`bash


Install PM2

npm install -g pm2

Create PM2 ecosystem file

cat > ecosystem.config.js << EOF
module.exports = {
apps: [{
name: 'magpie-mcp-server',
script: 'dist/index.js',
env: {
MAGPIE_PUBLIC_KEY: 'your_public_key_here',
MAGPIE_SECRET_KEY: 'your_secret_key_here',
MAGPIE_TEST_MODE: 'false'
},
restart_delay: 1000,
max_restarts: 10
}]
};
EOF

Start with PM2

pm2 start ecosystem.config.js
`

$3

Run the server in a Docker container:

`bash


Build Docker image

docker build -t magpie-mcp-server .

Run container

docker run -e MAGPIE_PUBLIC_KEY=your_public_key \
-e MAGPIE_SECRET_KEY=your_secret_key \
-e MAGPIE_TEST_MODE=false \
magpie-mcp-server
`

Testing

$3

You can test the MCP server manually using stdio:

`bash


Build the server first

npm run build

Test tools listing

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | node dist/index.js

Test resources listing

echo '{"jsonrpc": "2.0", "id": 2, "method": "resources/list", "params": {}}' | node dist/index.js
`

$3

1. Configure Claude Desktop with the server (see Configuration section)
2. Restart Claude Desktop
3. Start a new conversation and try payment-related queries
4. Check that the Magpie tools are available and functioning

$3

`bash


Validate OpenAPI specifications

npm install -g @apidevtools/swagger-cli
swagger-cli validate api-reference/payments.yaml
swagger-cli validate api-reference/checkout.yaml
swagger-cli validate api-reference/requests.yaml
swagger-cli validate api-reference/links.yaml

Lint YAML files

pip install yamllint
yamllint api-reference/
`

$3

Server not starting:
- Check that all required environment variables are set
- Verify Node.js version is 18 or higher
- Ensure the project has been built with npm run build

Claude Desktop integration issues:
- Verify the configuration file path and JSON syntax
- Most Important: Restart Claude Desktop completely (Quit and reopen) after configuration changes
- Recommended: Use the full path approach (Node + dist/index.js) for maximum reliability
- Verify Node.js path with which node command
- Check that dist/index.js exists after building with npm run build`
- Click the MCP icon in Claude Desktop to verify "magpie" appears with toggle enabled
- Test in a new conversation - ask Claude to list available Magpie tools
- If using global installation and getting "command not found", the Node.js PATH is not accessible to Claude Desktop - use full paths instead

API authentication errors:
- Verify your Magpie API credentials are valid
- Check that you're using the correct test/live mode settings
- Ensure credentials have the necessary permissions

Payment processing errors:
- Review the error responses for specific details
- Check that payment method details are valid for your region
- Verify currency and amount formatting (amounts in cents)
- Ensure test mode is enabled for development testing

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues with the MCP server, please file a GitHub issue. For Magpie API questions, contact Magpie support at support@magpie.im.