Alternative Payments MCP Server

An MCP server for the Alternative Payments partner API. It lets an AI agent work with an MSP's billing in Alternative Payments: customers, invoices, standalone payment requests, payment transactions, payouts and webhook subscriptions.

• Transport: MCP Streamable HTTP at POST /mcp, health probe at GET /health

• Stateless and multi-tenant: credentials arrive on every request as HTTP headers and are never stored; the OAuth access token is obtained per request and not cached

• Python 3.12, uv, FastMCP, httpx

• License: Apache-2.0, Copyright 2026 MSPbots.ai

Authentication headers

Where to get them:

• Client id / secret: in the Alternative Payments Partner Dashboard open Team Preferences -> API Keys -> Generate API Key. The server exchanges them for a short-lived bearer token (OAuth 2.0 client credentials) on each request; the secret is only sent to the token endpoint.

• Scopes: pick read scopes for Customers, Invoices, Payments, Payouts and Webhooks for the read tools. Add the matching write scopes only if the agent should create or archive customers/invoices, create payment requests, or manage webhooks.

• Environment: use demo for a sandbox API key.

A request to /mcp without the required headers gets HTTP 401 with the list of required headers; an unknown environment gets HTTP 400.

Related MCP server: Agent Billy MCP Server

Tools

All tools return a JSON string. List tools return {items, count, has_more, next_cursor}; pass next_cursor as after to get the next page. limit defaults to 50 (max 100). Amounts are in US dollars; USD is the only supported currency.

Read tools:

Write tools (change real billing data; descriptions tell the agent to call them only when the user explicitly asks):

Errors come back as a JSON envelope instead of an exception:

{"error": {"code": "unauthorized", "message": "Alternative Payments rejected the client id / secret (token request failed)", "retryable": false}}

code is one of not_configured, unauthorized, not_found, invalid_argument, rate_limited, upstream_error.

Run locally

uv sync
uv run python -m alternative_payments_mcp          # listens on 0.0.0.0:8080

or with Docker:

docker build --platform linux/amd64 -t alternative-payments-mcp:dev .
docker run --rm -p 8080:8080 alternative-payments-mcp:dev

Configuration (environment variables, all optional): MCP_HTTP_HOST (default 0.0.0.0), MCP_HTTP_PORT (default 8080), LOG_LEVEL (default INFO). Credentials are never read from the environment.

Testing example

# list tools
curl -s http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Alternative-Payments-Client-Id: your-client-id" \
  -H "X-Alternative-Payments-Client-Secret: your-client-secret" \
  -H "X-Alternative-Payments-Environment: demo" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# overdue invoices
curl -s http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Alternative-Payments-Client-Id: your-client-id" \
  -H "X-Alternative-Payments-Client-Secret: your-client-secret" \
  -H "X-Alternative-Payments-Environment: demo" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ap_list_invoices","arguments":{"status":"OVERDUE","limit":10}}}'

Unit tests (no network access needed):

uv run pytest

Delivery notes

• Tool count (26). Above the suggested 20 because the tool names are an existing contract used by agents and tenant connections; none were merged or removed. The ap_ prefix is also kept for the same reason.

• Write tools. Nine tools change data. They are annotated (readOnlyHint=false; archive and delete also destructiveHint=true), validate their input before calling the API (USD only, YYYY-MM-DD dates, https URLs), and their descriptions tell the agent to act only on an explicit request.

• Currency. The partner API bills in USD only. ap_create_payment_request keeps its currency argument for compatibility and rejects anything other than USD.

License

Apache License 2.0 - see LICENSE and NOTICE.