> For the machine-readable index of this documentation, see [llms.txt](https://mcp.unshortlink.com/llms.txt).

# SlickPay MCP server

Give AI agents access to your SlickPay account so they can read data, quote fees and create
payments — in plain language, without writing API calls.

The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard for connecting
AI assistants to external systems. This server exposes **37 tools** covering every endpoint
of the SlickPay API, to any MCP client.

## Endpoints

| Environment | Endpoint | Talks to | Money |
| --- | --- | --- | --- |
| Sandbox | https://mcp.sandbox.unshortlink.com/mcp | devapi.slick-pay.com | Not real |
| Live | https://mcp.unshortlink.com/mcp | prodapi.slick-pay.com | Real |

Keys are issued per environment and are **not interchangeable** — a sandbox key returns 401
against the live endpoint, and vice versa.

## How it works

Your MCP client decides which tool to call. The MCP server validates the request, checks scope
and limits, and calls the SlickPay API with your credential. The API returns a record and a SATIM
payment link, which the customer pays by CIB card.

**Creating something does not move money.** Invoices, transfers and split payments all work the
same way: creating one returns a SATIM payment link and leaves the record pending. Funds move
only when that link is paid, and an unpaid record can be deleted. Card details never reach this
server or the SlickPay API.

## Before you begin

1. Create a SlickPay account at https://slick-pay.com
2. From your dashboard, switch to sandbox and copy the `PUBLIC_KEY`
3. Pick an MCP client. To run the server locally you also need Node 20.18 or newer.

## Install

### Claude Code

```bash
claude mcp add --transport http slickpay https://mcp.sandbox.unshortlink.com/mcp
```

### Claude Desktop

Desktop's Connectors screen requires OAuth, which this server does not yet offer. Use the
`mcp-remote` proxy. Note there is no space after `Authorization:` — the token lives in `env`.

```json
{
  "mcpServers": {
    "slickpay": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.sandbox.unshortlink.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer your-key"
      }
    }
  }
}
```

### Cursor

```json
{
  "mcpServers": {
    "slickpay": {
      "url": "https://mcp.sandbox.unshortlink.com/mcp"
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "slickpay": {
      "type": "http",
      "url": "https://mcp.sandbox.unshortlink.com/mcp"
    }
  }
}
```

### Locally over stdio

```json
{
  "mcpServers": {
    "slickpay": {
      "command": "npx",
      "args": [
        "-y",
        "@slick-pay/mcp"
      ],
      "env": {
        "SLICKPAY_API_KEY": "your-key",
        "SLICKPAY_ENVIRONMENT": "sandbox",
        "SLICKPAY_TOOLS": "read"
      }
    }
  }
}
```

## Authentication

Pass your SlickPay key as a bearer token, or mint a scoped token — recommended, because your key
is sealed inside it and never reaches the client, and the token can be revoked by id.

```bash
curl -X POST https://mcp.sandbox.unshortlink.com/tokens \
  -H "Authorization: Bearer your-slickpay-key" \
  -H "Content-Type: application/json" \
  -d '{"tools":"read"}'
```

List tokens with `GET /tokens` and revoke one with `DELETE /tokens/{id}`. The token is shown
once and cannot be retrieved again.

## Permissions

| Selector | Tools | Grants |
| --- | --- | --- |
| (none) | 19 | Reading, fee quotes, documentation search |
| `?tools=read,write` | 29 | … plus creating and updating invoices, contacts, accounts and split payments |
| `?tools=all` | 37 | … plus transfers and deletion |
| `?tools=invoices.write` | varies | A single resource, for a narrowly scoped agent |

**Enabling writes never enables money movement.** Transfers and deletion require `?tools=all`
and are never implied by `read,write`. The selector can only narrow what a credential already
permits — it cannot widen it.

## Example prompts

### "Which of my customers still owe me money?"

`list_invoices → get_payment_status`

Pages through your invoices and reports which are unpaid and what they total. Read-only — no configuration beyond connecting.

### "Invoice Ahmed 12,000 DZD for the March retainer and give me the link to send him."

`list_contacts → calculate_invoice_commission → create_invoice`

Resolves the contact, quotes the fee so you see the cost before committing, then returns a SATIM payment link to pass to the customer. Needs `?tools=read,write`.

### "What would it cost me to pay out 50,000 DZD, and how does that compare to invoicing it?"

`calculate_transfer_commission + calculate_invoice_commission`

Quotes both sides without creating anything. The commission endpoints are pure calculations, so this is safe on production.

### "Split 90,000 DZD across my three sellers — 50/30/20 — and give me one payment link."

`list_contacts → calculate_aggregation_commission → create_aggregation`

Previews each seller's share and fee, then creates the split and returns a single link the payer settles once. Needs `?tools=read,write`.

### "Add Sarah as a payee: RIB 00300200100400578945, sarah@example.com, Algiers."

`create_contact`

Validates the RIB is 20 digits and unique before the call leaves your machine. Needs `?tools=read,write`.

### "How do SlickPay webhooks work?"

`search_docs`

Answers from a bundled documentation index rather than guessing — including details the published docs get wrong, like pagination.

## Tool reference

| Tool | Description | Tier | Scope |
| --- | --- | --- | --- |
| `slickpay_calculate_aggregation_commission` | Quote how a split payment divides across contacts, with the commission for each share, without creating anything. | read | aggregations:read |
| `slickpay_calculate_invoice_commission` | Quote the SlickPay commission for an invoice of a given amount, without creating anything. | read | invoices:read |
| `slickpay_calculate_transfer_commission` | Quote the SlickPay commission for a transfer of a given amount, without moving any money. | read | transfers:read |
| `slickpay_get_account` | Retrieve a single account by its uuid. | read | accounts:read |
| `slickpay_get_aggregation` | Retrieve a single aggregation by its id. | read | aggregations:read |
| `slickpay_get_contact` | Retrieve a single contact by its uuid. | read | contacts:read |
| `slickpay_get_invoice` | Retrieve a single invoice by its id. | read | invoices:read |
| `slickpay_get_merchant_invoice` | Retrieve a single merchant invoice by its id. | read | merchant_invoices:read |
| `slickpay_get_payment_status` | Check whether an invoice, transfer, or aggregation has been paid. | read | invoices:read, transfers:read, aggregations:read |
| `slickpay_get_profile` | Return the authenticated SlickPay merchant. | read | — |
| `slickpay_get_transfer` | Retrieve a single transfer by its id. | read | transfers:read |
| `slickpay_list_accounts` | List the merchant's own bank accounts, which receive collected funds. | read | accounts:read |
| `slickpay_list_aggregations` | List split payments, where one total is divided across several contacts. | read | aggregations:read |
| `slickpay_list_contacts` | List payees — the counterparties for transfers and the parties billed on invoices. | read | contacts:read |
| `slickpay_list_invoices` | List invoices, each of which carries a SATIM payment link. | read | invoices:read |
| `slickpay_list_merchant_invoices` | List invoices issued on the merchant endpoint rather than the user endpoint. | read | merchant_invoices:read |
| `slickpay_list_transfers` | List outgoing transfers to payees. | read | transfers:read |
| `slickpay_report_feedback` | Report a missing capability, a bug, or general feedback about these tools to SlickPay. | read | — |
| `slickpay_search_docs` | Search the bundled SlickPay API documentation. | read | — |
| `slickpay_create_account` | Register one of the merchant's own bank accounts to receive collected funds. | write | accounts:write |
| `slickpay_create_aggregation` | Create a split payment dividing one total across several contacts, returning a SATIM payment link. | write | aggregations:write |
| `slickpay_create_contact` | Create a payee — the counterparty for transfers and the party billed on invoices. | write | contacts:write |
| `slickpay_create_invoice` | Create an invoice and get back a SATIM payment link to give the customer. | write | invoices:write |
| `slickpay_create_merchant_invoice` | Create an invoice on the merchant endpoint rather than the user endpoint. | write | merchant_invoices:write |
| `slickpay_update_account` | Update one of the merchant's own bank accounts. | write | accounts:write |
| `slickpay_update_aggregation` | Update an unpaid split payment's type or total. | write | aggregations:write |
| `slickpay_update_contact` | Update an existing payee. | write | contacts:write |
| `slickpay_update_invoice` | Update an unpaid invoice. | write | invoices:write |
| `slickpay_update_merchant_invoice` | Update an unpaid merchant invoice. | write | merchant_invoices:write |
| `slickpay_create_transfer` | Create an outgoing transfer to a payee and get back a SATIM payment link. | money | transfers:execute |
| `slickpay_delete_account` | Permanently delete a account. | money | accounts:delete |
| `slickpay_delete_aggregation` | Permanently delete a aggregation. | money | aggregations:delete |
| `slickpay_delete_contact` | Permanently delete a contact. | money | contacts:delete |
| `slickpay_delete_invoice` | Permanently delete a invoice. | money | invoices:delete |
| `slickpay_delete_merchant_invoice` | Permanently delete a merchant invoice. | money | merchant_invoices:delete |
| `slickpay_delete_transfer` | Permanently delete a transfer. | money | transfers:delete |
| `slickpay_update_transfer` | Change a pending transfer's amount, destination account, or return URL. | money | transfers:execute |

## Safety

- **Hard ceilings** — above a configured amount a call is refused outright, before it reaches SlickPay.
- **No duplicate charges** — an identical create inside a short window returns the original result.
- **Audit trail** — every change recorded; RIBs masked to the last four digits everywhere.
- **Rate limits** — per-credential limits sit below the API's own budget.
- **No card data** — payments settle through SATIM; card numbers never reach this server.
- **Revocable access** — scoped tokens revoked by id without rotating your SlickPay key.

**Amounts are in DZD major units.** `amount: 1000` means 1,000 DZD — the opposite of the
minor-unit convention most payment APIs use. Never multiply by 100. Commission is added on top of
the amount.

## Troubleshooting

### 401 Unauthorized, but my key is valid

Keys are issued per environment and are not interchangeable. A sandbox key returns 401 against the live host and vice versa. Check which endpoint you configured — `slickpay_get_profile` names the environment it is talking to.

### The agent says there is no tool to create anything

You are on the default read-only tier. Add `?tools=read,write` to the endpoint URL for creates and updates, or `?tools=all` to include transfers and deletes. Restart the client fully afterwards — tool lists are cached at launch.

### Claude Desktop's Connectors screen fails to register

Connectors requires OAuth, which this server does not yet offer. Use the `mcp-remote` proxy shown above, or Claude Code, both of which accept a bearer token.

### Amounts look a hundred times too large or too small

Amounts are DZD major units. `amount: 1000` means 1,000 DZD, not 10.00. This is the opposite of the minor-unit convention used by most payment APIs.

### A transfer or invoice was refused with no upstream call

It exceeded the configured ceiling. The limit cannot be raised from the client — it is a server configuration change. Splitting the amount across smaller calls is also refused by design.

### The same invoice appears to have been created twice

It has not. An identical create inside a 60-second window returns the original result with `deduplicated: true` rather than creating a second record.

## See also

- [SlickPay API documentation](https://developers.slick-pay.com)
- [Model Context Protocol](https://modelcontextprotocol.io)