# Timbré MCP connector documentation

The Timbré MCP server lets an AI assistant create, collect payment for and send a real printed postcard. It exposes 4 tools, with no authentication: card payment is the only step asked of the user.

## Connection

| Item | Value |
| --- | --- |
| URL | `https://rqqazttexbqpsmjnvowj.supabase.co/functions/v1/mcp` |
| Transport | Streamable HTTP (POST, JSON responses), JSON-RPC 2.0 |
| Protocol versions | 2025-06-18, 2025-03-26, 2024-11-05 |
| Authentication | None |
| Capabilities | `tools` |
| Price | €3.99 incl. VAT per card, printing and postage included |

## Order flow

1. `preview_postcard` creates the order and returns the preview (front + back). Status: `pending_payment`.
2. The assistant shows both images to the user and waits for approval.
3. `create_payment_link` returns a secure payment link to give to the user.
4. After payment, `check_and_send` verifies the payment server-side, then sends the card to print. Status: `sent`.
5. `order_status` gives progress: preparation, printing, hand-over to the postal service.

Possible statuses: `pending_payment` → `paid` → `sent` or `failed`; `pending_payment` → `expired` after 7 days without payment.

Guarantees:
- No card is sent without a payment confirmed by the server (paid session, same order, correct amount).
- An order can only produce one card, even if `check_and_send` is called several times.
- A paid order whose sending was never requested is sent automatically (hourly check).

## Tools

### preview_postcard — Preview a postcard

Creates the order and generates the preview. Annotations: `readOnlyHint: false`, `destructiveHint: false`, `openWorldHint: true`.

| Parameter | Type | Required | Rule |
| --- | --- | --- | --- |
| `message` | string | yes | 1 to 2,000 characters, Latin alphabet; emojis removed |
| `photo_url` | string | yes | Public https URL of an image, 25 MB max, no redirect |
| `firstname` | string | yes | 1 to 70 characters |
| `lastname` | string | yes | 1 to 70 characters |
| `address` | string | yes | 1 to 90 characters |
| `postal_code` | string | yes | 1 to 12 characters |
| `city` | string | yes | 1 to 70 characters |
| `country` | string | no | Country name in French (e.g. BELGIQUE, ROYAUME-UNI, ETATS-UNIS); default FRANCE |
| `language` | string | no | Sender's ISO 639-1 code, for the QR code caption (fr, en, es, it, de, pt, nl); default en |

Response: `order_id`, `apercu_recto_url`, `apercu_verso_url`, `orientation`, `destinataire`, `prix`, `prochaine_etape`; `caracteres_retires` and `avertissement` if emojis were removed.

### create_payment_link — Create the payment link

Call after the preview is approved. Returns the same link while it is valid. Annotations: `readOnlyHint: false`, `destructiveHint: false`, `openWorldHint: true`.

| Parameter | Type | Required | Rule |
| --- | --- | --- | --- |
| `order_id` | string | yes | 12 hexadecimal characters |

Response: `order_id`, `lien_paiement`, `mode`, `prochaine_etape`.

### check_and_send — Check payment and send

Checks the payment; if confirmed, sends the card to print. Irreversible action. Annotations: `readOnlyHint: false`, `destructiveHint: true`, `openWorldHint: true`.

| Parameter | Type | Required | Rule |
| --- | --- | --- | --- |
| `order_id` | string | yes | 12 hexadecimal characters |

Response: `statut`, `paye`, `reference_envoi`, `info`; if unpaid: `paye: false` and nothing is sent.

### order_status — Order status

Gives the order status and, if the card has left, its progress. Annotations: `readOnlyHint: true`, `openWorldHint: true`.

| Parameter | Type | Required | Rule |
| --- | --- | --- | --- |
| `order_id` | string | yes | 12 hexadecimal characters |

Response for a sent card: `etape` (card in preparation, awaiting printing, printing, printed, handed to the postal service), `envoyee_le`, `remise_service_postal`, `delai_indicatif`.

## Limits

| Limit | Value |
| --- | --- |
| Previews per minute (all users) | 20 |
| Previews per day (all users) | 500 |
| Photo size | 25 MB |
| Message length | 2,000 characters, text size reduced automatically |
| Countries | 218, names in French |
| Tracking | Up to hand-over to the postal service (no delivery tracking) |

## Errors

Tool errors are returned with `isError: true` and a French text intended for the user: missing or too long field, unrecognised country, invalid photo URL, inaccessible or too heavy photo, message too long for the card, non-Latin characters, too many requests, invalid `order_id`. Protocol errors follow JSON-RPC (-32700, -32601, -32603).

## Example

    curl -X POST https://rqqazttexbqpsmjnvowj.supabase.co/functions/v1/mcp \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

## Links

- [Connector overview](https://timbre.at/en/mcp)
- [Connector privacy](https://timbre.at/en/mcp/privacy)
- Support: [hello@timbre.at](mailto:hello@timbre.at)