@payretailers/mcp

Official Model Context Protocol (MCP) server for the PayRetailers Payments API.

Turn any MCP-compatible AI assistant into a PayRetailers integration expert. This server exposes the official Guides, tactical Skills, endpoint reference, and integration tools (search, country-specific validation, webhook playbook) as first-class MCP Resources, Tools, and Prompts.

Works with Cursor, Claude Desktop, Claude Code, Windsurf, Antigravity, Zed, VS Code + Copilot, JetBrains IDEs, Continue.dev, Cline, and any other client that speaks MCP over stdio.

---

Why use it

When you install this server, your AI assistant stops guessing about PayRetailers and starts consulting the source of truth on every step.

• Correct code on the first try. The assistant reads the real OpenAPI shape for each endpoint (get_endpoint_spec), so generated code uses the actual field names, types, and required combinations — not something borrowed from another PSP.
• Country-aware from the start. Ask for a PIX payin and the assistant knows PIX is Brazil-only, expects BRL, needs a valid 11-digit CPF, and that the QR expires fast. Ask for SPEI and it knows Mexico wants a CURP or RFC, MXN, and that CLABE is provisioned asynchronously. All powered by get_country_rules.
• Payloads validated before they hit the sandbox. validate_payload runs real checksum validation on CPF, CNPJ, RUT, DNI, RUC, CC, NIT, CURP, RFC, CLABE — plus cross-cutting rules (integer minor units, HTTPS notification URLs, currency/country match, method/country compatibility, idempotency keys, customer required-fields matrix, subscription AmountModel shape, PIX Automático retry contract). You catch bugs in your editor, not in a 400 INVALID_MODEL_SCHEMA response.
• Webhook receivers designed correctly. get_webhook_playbook returns the canonical event vocabulary, retry policies, and signature/replay contract. validate_webhook_handler catches the six most damaging anti-patterns (ack-after-processing, missing eventId de-duplication, business-errors-as-500, disabled signature in production, wall-clock-order assumptions, HTTPS missing) before you write a single line of receiver code.
• Slash-command prompts for the hard flows. Type /integrate-pix-payin, /integrate-subscriptions, /implement-webhook-handler, /integrate-payout-fx, /build-checkout, /debug-401-auth, or /reconcile-with-graphql and get a production-shaped implementation in the stack of your choice.
• Zero-config, zero-network, offline-friendly. Everything ships bundled in the release zip. No account, no API key, no outbound calls just to answer a question about the docs. Credentials are only needed for the (planned) simulate_transaction tool.

Under the hood you have 7 tools, 7 prompts, 158 documentation resources (Guides + Skills + Reference + Recipes + concept docs), all mirrored verbatim from the payretailers-ai-docs repository.

---

What it exposes

Resources

Structured, LLM-friendly access to the PayRetailers documentation.

URI pattern	What it returns
payretailers://guide/{slug}	An end-to-end integration guide with architecture, sequence diagrams, implementation steps, and production checklist.
payretailers://skill/{slug}	A task-focused workflow that combines multiple endpoints (e.g. brazil-pix-payin, payout-fx-quote-flow).
payretailers://reference/{slug}	A single API reference page (parameters, response, error codes).
payretailers://recipe/{slug}	A short code recipe for a common operation.
payretailers://doc/{slug}	A concept/documentation page (subscription-concepts, webhooks-and-notifications, retry-policies, automatic-scheduling, clabe-per-customer, ...).

The full list is announced dynamically at connect time — clients can browse them via their resource picker.

Tools

Actions the LLM can invoke instead of guessing.

Tool	What it does	Phase
search_docs	Full-text search across Guides, Skills, Reference, Recipes and concept Docs with fuzzy matching and boosted title/slug fields.	✅ 0.1
get_country_rules	Return the customer fields, personalId format (CPF, DNI, CURP, CC, RUT, ...), currencies, and payment-method constraints for a country + method.	✅ 0.2
get_test_data	Return sandbox test data (customers, cards, PIX keys, Bre-B keys) for a given country.	✅ 0.2
get_endpoint_spec	Return the full reference page (parameters, response, error codes) for a specific endpoint by slug.	✅ 0.2
validate_payload	Validate a payload against country-specific rules with real checksum validation for CPF, CNPJ, RUT, DNI, RUC, CC, NIT, CURP, RFC, CLABE. Also validates subscription products, subscriptions, and subscription payments (billing cycle, PIX_SPECIFIC retry policy, immutability). Catches non-integer minor units, wrong currency for the country, non-HTTPS webhooks, method/country mismatches, missing idempotency keys, and more.	✅ 0.3 / 0.4
get_webhook_playbook	Canonical PayRetailers webhook contract: envelope schema, complete event vocabulary (transactions, payouts, subscriptions, subscription payments), retry policies, signature/replay guidance, top 6 common mistakes.	✅ 0.4
validate_webhook_handler	Analyse a declarative description of a webhook receiver design and return machine-readable {errors, warnings, info}. Catches ack-after-processing, missing idempotency, business-errors-as-500, wall-clock-order assumptions, disabled signature in production.	✅ 0.4
simulate_transaction	Execute a real request against the PayRetailers sandbox using the developer's env credentials.	🚧 planned

Prompts

Ready-to-use templates that the developer can select with / in Cursor / Claude Desktop / etc.

Prompt	What it triggers	Phase
integrate-pix-payin	Generate a complete Brazil PIX payin integration in the language of your choice.	✅ 0.1
integrate-payout-fx	Cross-currency payout with 5-min FX quote TTL handling.	✅ 0.2
build-checkout	Country-aware checkout: frontend picker + backend endpoint + webhook receiver.	✅ 0.2
debug-401-auth	Diagnose HTTP 401/403 (subscription key, Basic Auth, IP whitelist, env mix-up).	✅ 0.2
reconcile-with-graphql	Build a reconciliation pipeline using the Merchant Data GraphQL API.	✅ 0.2
implement-webhook-handler	Generate a production-grade webhook receiver for the requested stack, scope, and queue backend. Enforces the four non-negotiables (200 fast, dedupe by eventId, strict signature, never confirm before terminal status).	✅ 0.4
integrate-subscriptions	Generate a full subscription integration for the given country + channel (product + activation + subscription + charge + retry + cancellation).	✅ 0.4

---

Install

Two supported paths. Pick one:

• Option A — Prebuilt zip from GitHub Releases (recommended today): no npm account, no compilation, works fully offline once downloaded. This is the officially supported distribution while @payretailers/mcp is not yet on npm.
• Option B — Build from source: for contributors and security-conscious deployments that want to audit the code before running it.

Option C — installing from npm as @payretailers/mcp — is planned but not yet available. When the package is published, the npx -y @payretailers/mcp snippets in the Configuration by client section will work out of the box.

Option A — Install from GitHub Releases

Prerequisites: Node.js 20 or later (node --version). Nothing else — the release zip is self-contained.

1. Open the Releases page and download the latest payretailers-mcp-vX.Y.Z.zip from the "Assets" section of the top release.
2. Unzip it anywhere. Common locations:
   • Windows: C:\Tools\payretailers-mcp
   • macOS / Linux: ~/tools/payretailers-mcp
3. Add the server to your MCP client (see Configuration by client below, or the step-by-step guides linked there). Point it at the absolute path of dist/index.js inside the unzipped folder.
4. Reload / restart your MCP client. The server will show up alongside your other tools.

Step-by-step setup guides with screenshots and verification prompts:

• Cursor
• Claude Code CLI
• Claude Desktop
• VS Code + GitHub Copilot

Optional smoke check before or after wiring it in — proves the bundle is healthy end-to-end:

cd /path/to/payretailers-mcp-X.Y.Z
node scripts/smoke-test.mjs

Expected: PASS ✅ at the end, with 7 tools, 158 resources, 7 prompts, 5 resource templates announced.

Option B — Build from source

For contributors, or if your security policy requires you to audit the code before running it. Prerequisites: Node.js 20 or later, git.

git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js (bundle + runtime deps)
npm start              # optional: run over stdio manually (Ctrl+C to stop)

data/ (Guides, Skills, Reference, Recipes, concept docs, curated JSON) is checked in — you do not need npm run sync:docs unless you are mirroring an updated payretailers-ai-docs checkout on the same machine.

Then wire dist/index.js into your MCP client the same way as Option A.

---

Configuration by client

Prefer a full walkthrough with verification prompts and troubleshooting? See the step-by-step guides in docs/setup/ for Cursor, Claude Code, Claude Desktop, and VS Code + Copilot. The snippets below are the minimal JSON needed if you already know your way around your client.

Every client takes the same three pieces of information: a command (node), an args array pointing at the absolute path of dist/index.js, and an optional env block for the future simulate_transaction tool.

Replace C:/Tools/payretailers-mcp/dist/index.js below with the absolute path where you unzipped the release. On Windows use forward slashes in JSON — backslashes need to be escaped and cause confusing errors.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"],
      "env": {
        "PAYRETAILERS_ENV": "sandbox",
        "PAYRETAILERS_SHOP_ID": "your_sandbox_shop_id",
        "PAYRETAILERS_SECRET_KEY": "your_sandbox_secret_key",
        "PAYRETAILERS_SUBSCRIPTION_KEY": "your_sandbox_subscription_key"
      }
    }
  }
}

The env block is optional — Resources, search_docs, and all validators work without any credentials.

Claude Desktop

Add to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

VS Code + Copilot

Add to .vscode/mcp.json (workspace) or open the user-scoped file with Command Palette → MCP: Open User Configuration:

{
  "servers": {
    "payretailers": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

Note: VS Code is the odd one out — the root key is "servers" (not "mcpServers"). MCP tools only run in Copilot Chat's Agent mode.

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "payretailers": {
      "command": {
        "path": "node",
        "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
      }
    }
  }
}

Continue.dev

Add to ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "payretailers",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  ]
}

JetBrains AI Assistant

Open Settings → AI Assistant → MCP Servers → Add and enter:

• Name: payretailers
• Command: node
• Arguments: C:/Tools/payretailers-mcp/dist/index.js (absolute path)

Other clients

Any client that speaks MCP over stdio can consume this server. Point it at node <absolute-path-to>/dist/index.js and you are done.

Once npm is available

When @payretailers/mcp is published to npm, the same configs work with the shorter form:

{ "command": "npx", "args": ["-y", "@payretailers/mcp"] }

No changes to env, no need to keep an unzipped folder around.

---

Verify it works

After reloading your MCP client you should see, on the server's status entry, something like:

7 tools · 158 resources · 7 prompts · 5 resource templates

• Cursor: Ctrl+Shift+P → Customize → MCPs tab. Look for payretailers with a green dot and expand it.
• Claude Desktop: check the tools drawer in a new chat; the PayRetailers tools should appear alongside your other MCPs.
• VS Code / Zed / Continue.dev / Windsurf: consult each client's docs for its MCP status panel.

If your assistant does not appear to call the tools, force it once by prefixing a prompt with "Use the PayRetailers MCP to...". Once it has invoked a tool once in a conversation, it tends to keep doing so.

---

Troubleshooting

The server fails to start. Run the bundle manually from a terminal:

node /path/to/payretailers-mcp/dist/index.js

If it stays silent waiting for input, the bundle is fine — the issue is on the client side (path typo in the config, forward-slashes vs backslashes on Windows, wrong process being restarted). If it prints an error, the most common causes are Node < 20 (upgrade Node) or a truncated download (re-download the zip).

The client shows old counts (e.g. 5 tools, 89 resources). Some clients cache the MCP tool/resource enumeration. Toggle the server OFF → ON in the client's MCP panel, or add an unused env entry to the config (e.g. "MCP_VERSION": "0.4.1") to force a re-spawn.

The model does not seem to call any MCP tool. Make sure the chat is in Agent mode (not Ask / read-only mode). Some lightweight models are less eager to call tools — switch to a top-tier model for the first invocations, and the assistant will remember the tools are available for the rest of the conversation.

Where are the logs? Every MCP client has an MCP logs panel that captures the JSON-RPC handshake, parse errors, and server stderr. In Cursor: Ctrl+Shift+U → dropdown → MCP Logs.

---

Environment variables

Optional — required only for the future simulate_transaction tool (Phase 4). Everything else (Resources, search_docs, Prompts) works without any credentials.

Variable	Description	Default
PAYRETAILERS_ENV	sandbox or production.	sandbox
PAYRETAILERS_SHOP_ID	Your Shop ID from the merchant portal.	(unset)
PAYRETAILERS_SECRET_KEY	Your Secret Key for HTTP Basic Auth.	(unset)
PAYRETAILERS_SUBSCRIPTION_KEY	Value of the Ocp-Apim-Subscription-Key header.	(unset)

Security: the server never logs credentials and never persists them. They live in-memory for the duration of the session and are only sent to api-sandbox.payretailers.com or api.payretailers.com when you invoke simulate_transaction.

---

Example usage

Once configured, ask your AI assistant in plain language:

"Create my first PIX payin in the sandbox for R$50 in Brazil. Use Node.js."

Under the hood, the assistant will:

1. Call search_docs({ query: "pix payin brazil" }) → find the brazil-pix-payin skill.
2. Read payretailers://skill/brazil-pix-payin for the exact steps.
3. Generate runnable code with the right endpoint, headers, minor units, and CPF format.

Or use the /integrate-pix-payin prompt directly for a fully-scaffolded answer.

Validating a payload before submission

Once the assistant has drafted a payload it can validate it before hitting the API:

// tools/call → validate_payload
{
  "operation": "create-transaction",
  "country": "BR",
  "method": "PIX",
  "payload": {
    "trackingId": "abc-12345678",
    "amount": 100.50,              // will be flagged: use 10050 (minor units)
    "currency": "USD",             // will be flagged: BR expects BRL
    "notificationUrl": "http://example.com/wh", // will be flagged: must be HTTPS
    "customer": {
      "firstName": "Ana",
      "lastName": "Santos",
      "email": "ana@example.com",
      "personalId": "12345678900"  // will be flagged: invalid CPF checksum
    }
  }
}

The response lists every issue with a code, severity, path, message, and often a hint and suggestion — the LLM can fix the payload before wasting a network round-trip.

---

Development

git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js
npm test               # 93 unit tests
node scripts/smoke-test.mjs   # end-to-end stdio handshake + tool calls
npm start              # optional: run the server manually on stdio

data/ (Guides, Skills, Reference, Recipes, concept docs, curated JSON) is checked into the repository. Run npm run sync:docs only if you have ../payretailers-ai-docs checked out and want to refresh the mirror.

The server can be inspected with the official MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

---

Releasing (maintainers)

Releases are automated via GitHub Actions on tag push (v*.*.*). The workflow:

1. Runs lint, typecheck, unit tests, build, and smoke test.
2. Runs npm run pack:release to produce release/payretailers-mcp-vX.Y.Z.zip (bundled dist/index.js + data/ mirror + README + LICENSE + CHANGELOG + smoke test).
3. Creates a GitHub Release and attaches the zip.
4. Publishes to npm as @payretailers/mcp only if the NPM_TOKEN repository secret is configured — otherwise the release is GitHub-only.

To cut a release locally, then push the tag:

# 1. Bump version in package.json, config.ts, CHANGELOG.md
# 2. Verify locally
npm run clean && npm ci && npm test && npm run build
node scripts/smoke-test.mjs
npm run pack:release        # writes release/payretailers-mcp-vX.Y.Z.zip

# 3. Commit + tag + push
git add -A
git commit -m "chore: release vX.Y.Z"
git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z      # this triggers .github/workflows/release.yml

Semver is enforced strictly: patch releases fix bugs, minor releases add tools/prompts/resources without breaking existing ones, major releases only for renames/removals.

---

Roadmap

• 0.1 ✅ Resources (Guides, Skills), search_docs, integrate-pix-payin prompt.
• 0.2 ✅ Resources (Reference, Recipes), get_country_rules, get_test_data, get_endpoint_spec, prompts integrate-payout-fx, build-checkout, debug-401-auth, reconcile-with-graphql.
• 0.3 ✅ validate_payload with real checksum validation for CPF, CNPJ, RUT, DNI, RUC, CC, NIT, CURP, RFC, CLABE + cross-cutting rules (minor units, currency/country, HTTPS webhooks, method/country, idempotency).
• 0.4 ✅ Concept docs resource category, get_webhook_playbook, validate_webhook_handler, expanded validate_payload for subscription operations, prompts implement-webhook-handler, integrate-subscriptions.
• 0.4.1 ✅ Subscriptions schema alignment (AmountModel, frequency enum, authorizationType) — CHANGELOG.md.
• 0.5 — simulate_transaction (dry-run against sandbox), get_error_code, expanded country coverage.
• 1.0 — Stable public release + listing in the official MCP Registry + npm publish.

See CHANGELOG.md for details.

---

Related

• Step-by-step setup guides for Cursor, Claude Code, Claude Desktop and VS Code + Copilot: docs/setup/.
• Companion documentation repository: payretailers-dev/payretailers-ai-docs — the source of Guides, Skills, and the docs mirror.
• Official documentation: www.payretailers.dev.
• Develop with LLMs guide: www.payretailers.dev/docs/develop-with-llms.
• Model Context Protocol: modelcontextprotocol.io.

---

License

Source code: MIT. See LICENSE.

Documentation content bundled in data/ (Guides, Skills, Reference, Recipes) is licensed under CC BY-ND 4.0, inherited from the payretailers-ai-docs repository. The curated data files (data/country-rules.json, data/test-data.json) are also released under CC BY-ND 4.0.

---

Contributing

Bug reports and feature requests are welcome via GitHub Issues. Pull requests from the community are reviewed but merged at the discretion of the PayRetailers team — see CONTRIBUTING.md when available.