# MCP server

Connect PayLynks to Claude, Cursor, Claude Code or any MCP client so the assistant can create payment links and invoices, look up payments and fetch integration code for you.

**Server URL:** `https://paylynks.io/api/mcp` (Streamable HTTP)

## Connect

**OAuth (recommended).** Add the URL as a remote MCP server. Your client opens PayLynks in the browser; sign in, pick the business, choose permissions and a per-call limit, and approve. Works with clients that support MCP authorization (Claude, Claude Code, Cursor).

```bash
claude mcp add --transport http paylynks https://paylynks.io/api/mcp
```

**Agent key.** For tools that only take a header, create an agent key in the dashboard (**Developers → Agent keys**) and send it as `Authorization: Bearer ak_test_…`.

```json
{ "mcpServers": { "paylynks": { "url": "https://paylynks.io/api/mcp", "headers": { "Authorization": "Bearer ak_test_..." } } } }
```

## Permissions

| Permission | Tools |
| --- | --- |
| read (always) | get_account, list_payments, get_payment, list_customers, list_payment_links, list_invoices, list_subscriptions, list_donation_pages, get_snippet, search_docs, get_doc |
| write | create_customer, create_payment_link, create_invoice, create_payment_intent, send_payment_request, create_subscription, create_donation_page, create_portal_link |
| refunds | refund (test mode only) |

Calls that would move more than the connection's per-call limit are refused. Agents never receive secret API keys. Each call is logged as an `agent.tool_called` event with the client's name.

## Tools

- **get_account** — business name, test/live mode, card pricing disclosure, test cards. Call first.
- **list_payments**, **get_payment** — recent payments; one payment with refunds so far.
- **list_customers** — optional `query` on name or email.
- **list_payment_links**, **list_invoices**, **list_subscriptions**, **list_donation_pages** (with money raised)
- **get_snippet** — working code: `nextjs`, `react`, `supabase`, `html`, `node`, `webhook`.
- **search_docs**, **get_doc** — these docs.
- **create_customer** — `name`, optional `email`, `phone` (E.164).
- **create_payment_link** — `title`, `amount` in cents (or `min_amount`/`max_amount`). Returns the URL and QR code.
- **create_donation_page** — `title`, `suggested_amounts` (cents), optional `goal_amount`, `allow_monthly`, `cover_fees`. Returns the giving page URL.
- **create_portal_link** — `customer`. A one-time link (30 minutes) into that customer's portal. Give it only to that customer.
- **create_invoice** — `customer`, `items` (`description`, `quantity`, `unit_amount`), optional installments, late fee, early-pay discount; `send: true` emails it.
- **create_payment_intent** — `amount`, `description`; returns `client_secret` for a custom checkout.
- **send_payment_request** — email/text a pay link; texting needs `sms_consent: true`.
- **create_subscription** — recurring billing or a payment plan; the customer gets a signup link to agree and add a card.
- **refund** — `payment_intent`, optional `amount`.

## Protocol details

Stateless JSON-RPC over HTTP POST (`initialize`, `tools/list`, `tools/call`, `ping`); protocol versions 2025-06-18, 2025-03-26 and 2024-11-05. Unauthenticated requests get `401` with `WWW-Authenticate: Bearer resource_metadata="https://paylynks.io/.well-known/oauth-protected-resource"`. OAuth 2.1 with PKCE (S256) and dynamic client registration; metadata at `/.well-known/oauth-authorization-server`.