Alternative Payments MCP Server

A Model Context Protocol (MCP) server that gives AI assistants read + safe-write access to Alternative Payments — customers, invoices, payment requests, transactions, payouts, and webhooks.

Maintained by Wyre Technology.

Capabilities

This server deliberately does not move money. It exposes reads and safe writes (creating customers, invoices, and hosted payment links). It does not implement direct payment creation (POST /payments), which would charge a card or bank account.

The three destructive tools — ap_archive_customer, ap_archive_invoice, ap_delete_webhook — require interactive confirmation before they run.

Plus discovery tools ap_navigate and ap_status.

Authentication

Alternative Payments uses OAuth 2.0 client-credentials. Generate an API key (client_id / client_secret) in the Partner Dashboard.

Copy .env.example. The stdio transport reads these variables and does not use CONDUIT_S2S_SECRET:

• ALTERNATIVE_PAYMENTS_CLIENT_ID
• ALTERNATIVE_PAYMENTS_CLIENT_SECRET
• ALTERNATIVE_PAYMENTS_ENVIRONMENT (production or demo, default production)

The server exchanges these for a bearer token automatically and refreshes it before expiry.

HTTP service-to-service auth

CONDUIT_S2S_SECRET is required when MCP_TRANSPORT=http. If it is empty, or a known placeholder (changeme, your-s2s-secret, secret, placeholder, and the other example values), the process logs an error and exits non-zero. It never prints the secret. Compose will not start when the variable is unset.

Set MCP_ALLOW_INSECURE_DEV=1 only for local development to start without the secret. The process logs a loud warning, does not check X-Gateway-S2S, and binds 127.0.0.1 only. A non-loopback MCP_HTTP_HOST (including 0.0.0.0) is ignored in that mode and the override is logged. A placeholder secret is still refused.

MCP_HTTP_HOST is honored when a real CONDUIT_S2S_SECRET is set. If MCP_HTTP_HOST is unset, the server keeps the historical default and binds 0.0.0.0. The container image and Compose set 0.0.0.0 and AUTH_MODE=gateway. Publish the port on loopback unless a proxy sits in front.

With a real secret, every /mcp request must include:

X-Gateway-S2S: t=<unix seconds>,v1=<hex hmac-sha256>

v1 is the hex HMAC-SHA256 of the ASCII string t=<unix seconds>, keyed with CONDUIT_S2S_SECRET. The timestamp must be within 300 seconds of the server clock. A missing or invalid header returns 401 before vendor credentials are read.

Gateway mode (AUTH_MODE=gateway)

Every /mcp request must also include:

• X-Alternative-Payments-Client-ID
• X-Alternative-Payments-Client-Secret
• X-Alternative-Payments-Environment (optional: production or demo)

A request missing the client id or secret gets 401 and does not fall back to ALTERNATIVE_PAYMENTS_CLIENT_ID / ALTERNATIVE_PAYMENTS_CLIENT_SECRET in the process environment. The checked-in Compose service sets no static vendor credentials.

Single-tenant HTTP (AUTH_MODE=env)

/mcp still requires a valid X-Gateway-S2S header. Vendor credentials come from the ALTERNATIVE_PAYMENTS_* environment variables when the request does not carry the client-id and client-secret headers.

/health always returns 200. It does not require authentication and does not read vendor credentials.

Quick start

Claude Code (CLI):

claude mcp add alternative-payments \
  -e ALTERNATIVE_PAYMENTS_CLIENT_ID=your-client-id \
  -e ALTERNATIVE_PAYMENTS_CLIENT_SECRET=your-client-secret \
  -- npx -y github:WYRE-AI/alternative-payments-mcp

Docker (HTTP transport, gateway mode):

The image listens on 0.0.0.0 inside the container and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass the S2S secret. In gateway mode, Alternative Payments credentials arrive on each request as headers; they are not read from the environment.

docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  ghcr.io/wyre-ai/alternative-payments-mcp:latest

Compose refuses to start when CONDUIT_S2S_SECRET is unset, sets AUTH_MODE=gateway, publishes 127.0.0.1:8080:8080, and does not inject static vendor credentials:

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

The gateway signs each /mcp call:

t=$(date +%s)
sig=$(printf 't=%s' "$t" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS -X POST http://127.0.0.1:8080/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "X-Gateway-S2S: t=${t},v1=${sig}" \
  -H "X-Alternative-Payments-Client-ID: $ALTERNATIVE_PAYMENTS_CLIENT_ID" \
  -H "X-Alternative-Payments-Client-Secret: $ALTERNATIVE_PAYMENTS_CLIENT_SECRET" \
  -H "X-Alternative-Payments-Environment: production" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses ALTERNATIVE_PAYMENTS_CLIENT_ID and ALTERNATIVE_PAYMENTS_CLIENT_SECRET. This is separate from the gateway Compose service:

docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e ALTERNATIVE_PAYMENTS_CLIENT_ID="$ALTERNATIVE_PAYMENTS_CLIENT_ID" \
  -e ALTERNATIVE_PAYMENTS_CLIENT_SECRET="$ALTERNATIVE_PAYMENTS_CLIENT_SECRET" \
  ghcr.io/wyre-ai/alternative-payments-mcp:latest

Local HTTP without a secret is development-only. It binds 127.0.0.1 and logs a warning:

MCP_ALLOW_INSECURE_DEV=1 npm run start:http

Transports

• stdio (default): node dist/index.js. Does not use CONDUIT_S2S_SECRET.
• HTTP (MCP_TRANSPORT=http): streamable HTTP on MCP_HTTP_PORT (default 8080), with /mcp and /health endpoints. Each request gets a fresh stateless server, which is required for the WYRE MCP Gateway. Startup refuses to listen until CONDUIT_S2S_SECRET is a real secret, unless MCP_ALLOW_INSECURE_DEV=1.

Development

npm install
npm run build
npm test
npm run lint

License

Apache-2.0