MCP for agents

Coding agents can operate Plurel Pay through a remote MCP server on the same Cloudflare Worker as the merchant API. Sign in in the browser, or send a merchant API key from a script. Signing secrets stay out of tool output.

Merchant sign-in

Point the client at https://plurelpay.com/mcp and leave the token blank. The browser opens merchant sign-in. A static plurel_sk_ or plurel_pk_ key still works for scripts. Live keys cannot run mutating tools unless the agent passes confirm_live: true. Never put signing secrets (plurel_sign_…) or webhook secrets in MCP config.

Endpoint

Item	Value
URL	https://plurelpay.com/mcp
Transport	Streamable HTTP (MCP)
Auth	Merchant sign-in, or Authorization: Bearer with a merchant API key
Programmatic key	plurel_sk_test_* (payments:write + webhooks)

Install — Cursor

Add a remote MCP server (Cursor Settings → MCP, or project .cursor/mcp.json). Do not set an Authorization header. Cursor opens Plurel Pay sign-in (/merchants/sign-in) and connects with that login. Example configs also live in the repo under docs/mcp/connectors/.

cursor mcp.json

{
  "mcpServers": {
    "plurel-pay": {
      "url": "https://plurelpay.com/mcp"
    }
  }
}

Restart Cursor after saving, then choose Connect on plurel-pay. Sign in with the merchant account that owns the store. On the consent page, choose View (read docs, check the connection, look up a session) or Act (also create and cancel sessions and manage webhooks). View is the default. A static API key is still accepted for other clients, but Cursor does not need one. docs/mcp/connectors/cursor-mcp.sandbox.example.json is that static-key form. Do not copy it into the Cursor plugin.

Install — Claude Code and other clients

Claude Code and any other client that speaks MCP OAuth use the same URL. Leave the token blank, then sign in in the browser when the client asks.

Claude Code .mcp.json

{
  "mcpServers": {
    "plurel-pay": {
      "type": "http",
      "url": "https://plurelpay.com/mcp"
    }
  }
}

Install — Claude Desktop

Claude Desktop talks stdio locally; use mcp-remote to reach the Worker. Do not pass an Authorization header.

claude_desktop_config.json

{
  "mcpServers": {
    "plurel-pay": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://plurelpay.com/mcp"
      ]
    }
  }
}

Tools (MVP)

Tool	Purpose
docs.search / docs.get	Curated integration docs
credentials.verify	Probe key kind/environment/prefix — never raw secrets
sessions.create / get / cancel	Sandbox session lifecycle
webhooks.list / register	Webhook admin (MCP never returns secrets — supply PLUREL_WEBHOOK_SECRET from env; environment follows the API key)
cart.sign_guidance	How to HMAC via @plurel/sdk — MCP does not sign

Typical dry-run

credentials.verify — confirm sandbox secret + merchant name
Sign a cart on your server (cart signing), or use headless if enabled
sessions.create with cart (+ signature if required)
sessions.get with the returned session_id

Sandbox vs live

Sandbox — default for agents; keys contain _test_
Live — read tools warn; mutations require confirm_live: true

Rate limits

MCP applies ~60 tool calls / minute / key (plus ~120 / minute / IP), on top of the same Postgres-backed auth and session limits as REST v1.

Security notes

Do not paste signing secrets into chat; store webhook secrets in server env only
webhooks.register requires secret from env and never returns it. Generate a one-shot secret in the dashboard or REST if you do not have one. Webhook environment follows the API key, not the portal view.
sessions.create returns a non-privileged session_url + opaque session_id only — never group_access_token or access= query params
Live secret keys are rejected when a browser Origin is present; sandbox Inspector is limited to localhost / 127.0.0.1. CORS never uses * with Authorization.
Full threat model: see in-repo docs/mcp/spec.md (same Worker and Postgres as the merchant API)