MCP Server - PagAmerican

The PagAmerican MCP Server exposes the Data API (purchases, orders, refunds, checkouts, products and offers) as read-only tools for any AI agent that speaks the Model Context Protocol. Ask “how many orders did I get last week?” or “show refund 19119” straight from a conversation. It runs locally and authenticates with a single API key (pag_...): no login, no OAuth. Each tool calls the API on your behalf, and you only ever see the data that belongs to your account (scope is enforced server-side by the key).

Prerequisites

A PagAmerican API key (pag_...), provided by the PagAmerican team. Keep it secret.
For the manual setups (Claude Code, Cursor, VS Code): Node.js 18+. The package runs on demand with npx, so there is nothing to clone or build.

Install

Claude Desktop (1-click)
Claude Code
Cursor
VS Code

The simplest path: no terminal, no JSON.

Download the PagAmerican Data extension (.mcpb).
Double-click the file (or drag it into Claude Desktop, or go to Settings → Extensions → Advanced settings → Install Extension).
On the install screen, paste your API key (pag_...) in the form field and click Install.

claude mcp add pagamerican-data \
  --env PAGAMERICAN_API_KEY=pag_your_key \
  -- npx -y @pagamericantech/data-mcp

~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "pagamerican-data": {
      "command": "npx",
      "args": ["-y", "@pagamericantech/data-mcp"],
      "env": { "PAGAMERICAN_API_KEY": "pag_your_key" }
    }
  }
}

.vscode/mcp.json:

{
  "servers": {
    "pagamerican-data": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@pagamericantech/data-mcp"],
      "env": { "PAGAMERICAN_API_KEY": "pag_your_key" }
    }
  }
}

Available tools

All read-only. Dates are YYYY-MM-DD (UTC), to is exclusive, max window 90 days.

Category	Tools
Purchases	`purchases_list`, `purchase_get`
Orders (vendor keys only)	`orders_list`, `order_get`
Products (vendor only)	`products_list`
Offers (vendor only)	`offers_list`
Checkouts (vendor only)	`checkouts_list`, `checkout_get`
Abandoned carts (vendor only)	`abandoned_carts_list`
Refunds	`refunds_list` (optional `type`), `refund_get`

Example prompts:

“List my purchases between Sept 1 and Sept 8.”
“Show me refund 19119.”
“How many orders did I get last week?”

Configuration

Variable	Required	Default	Notes
`PAGAMERICAN_API_KEY`	Yes	n/a	Your `pag_...` key, sent as `Authorization: Bearer`.
`ANALYTICS_API_BASE_URL`	No	Production	Set to the staging URL only for testing.

Troubleshooting

Auth error / 401

The key is missing, invalid or revoked. Check the API key field (Claude Desktop) or PAGAMERICAN_API_KEY (manual setups).

Permission denied / 403

The resource is vendor-only and your key doesn’t have vendor access (e.g. orders_*, products_list, checkouts_*).

Date window too large / 422

The range is over 90 days. Split it into smaller windows.

Server won't start (manual setup)

Make sure Node.js 18+ is installed and npx can reach the npm registry. The first run downloads @pagamericantech/data-mcp from npm, so it can take a few seconds. To pin a version, use @pagamericantech/data-mcp@1.0.4.

​Prerequisites

​Install

​Available tools

​Configuration

​Troubleshooting

Prerequisites

Install

Available tools

Configuration

Troubleshooting