> ## Documentation Index
> Fetch the complete documentation index at: https://catchbackcards.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect an AI assistant to Partner API v2 and run it in plain language, with no code.

The CatchBack MCP server gives an AI assistant the Partner API as a set of tools. Connect an assistant such as Claude Code or Cursor, and you can ask it things like "show me the Pokémon packs and their odds" or "order a Bronze pack for this wallet", and it makes the right API calls with your key.

MCP (the [Model Context Protocol](https://modelcontextprotocol.io)) is the open standard most AI assistants use to connect to outside tools. Every tool here calls the same v2 endpoint documented in these pages, with your key, so scopes, idempotency, limits and errors work exactly as they do for code.

## What an assistant can and can't do

* **It can** browse packs and odds, create orders, follow them until the item is delivered, check what a wallet holds, get sell-back quotes, estimate and create shipments, manage your webhook, read your revenue statement, and drive the sandbox.
* **It can't move money or tokens.** Your customer pays for each order and shipment, and the person holding a token signs the transaction that sells it back or ships it. Nothing is ever charged to your key.
* **It can't rotate or revoke keys.** Do that through the API, so an assistant can never lock itself out.

## Connect

* **URL:** `https://catchbackcards.com/api/mcp`
* **Auth:** your key, as `Authorization: Bearer cb_live_...`. It needs the `nft:orders` scope. A key without it sees only `whoami`, which tells you what's missing and what to do next.
* **Transport:** Streamable HTTP, stateless, JSON responses.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http catchback https://catchbackcards.com/api/mcp \
>   --header "Authorization: Bearer cb_live_..."
> ```

> [tab] JSON config
>
> For Cursor and other clients that read an `mcpServers` config:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "catchback": {
>       "type": "http",
>       "url": "https://catchbackcards.com/api/mcp",
>       "headers": { "Authorization": "Bearer cb_live_..." }
>     }
>   }
> }
> ```

> [!TIP]
>
> Start with your **sandbox** key and the sandbox base URL in place of `https://catchbackcards.com`. Nothing there costs real money, and the `sandbox_` tools let the assistant play the customer's payment. See [Sandbox](https://catchbackcards.mintlify.site/partner-api/v2/quickstart.md).

## Try it

Once connected, ask your assistant to:

1. "Run `whoami`." This confirms the key and shows your program.
2. "List the Pokémon packs, then show me the odds for the Bronze pack."
3. "Create a Bronze pack order for wallet `0x…`."
4. In the sandbox: "Pay that order, tick until it's minted, and tell me what was pulled."
5. "Get a sell-back quote for that token."

## Tools

| Tool | What it does | Endpoint |
| - | - | - |
| `whoami` | Your key and its program | [Read the key](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/get-key.md) |
| `list_packs` | Packs you can sell, with prices | [List packs](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/list-packs.md) |
| `get_pack_pool` | One pack's odds and items | [Get a pack's odds and pool](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/get-pack-pool.md) |
| `create_order` | Buy 1-10 packs for a customer's wallet | [Create an order](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/create-order.md) |
| `list_orders` | Your orders, newest first | [List orders](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/list-orders.md) |
| `get_order` | One order and its status | [Get an order](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/get-order.md) |
| `get_order_verification` | The provably fair proof of a pull | [Verify an order's pull](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/get-order-verification.md) |
| `list_wallet_tokens` | What a wallet holds, with today's sell-back | [Wallet tokens](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/list-wallet-tokens.md) |
| `get_token` | One token and its sell-back schedule | [Get a token](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/get-token.md) |
| `create_sellback_quote` | A sell-back price, fixed for 10 minutes | [Create a sell-back quote](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/create-sellback-quote.md) |
| `list_quotes` | Your sell-back quotes | [List quotes](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/list-quotes.md) |
| `get_quote` | One quote and its payout | [Get a quote](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/get-quote.md) |
| `estimate_shipment` | Rates to ship 1-25 tokens in one box | [Estimate a shipment](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/estimate-shipment.md) |
| `create_shipment` | Create a shipment of 1-25 tokens | [Create a shipment](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/create-shipment.md) |
| `estimate_token_shipment` | Rates to ship one token | [Estimate a one-token shipment](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/estimate-token-shipment.md) |
| `create_token_shipment` | Create a one-token shipment | [Create a one-token shipment](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/create-token-shipment.md) |
| `list_shipments` | Your shipments | [List shipments](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/list-shipments.md) |
| `get_shipment` | One shipment: burns, then tracking | [Get a shipment](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/get-shipment.md) |
| `renew_shipment` | A new burn window for a paid shipment | [Renew a shipment](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/renew-shipment.md) |
| `register_webhook` | Set or change your webhook URL | [Register a webhook](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/register-webhook.md) |
| `list_webhooks` | Your webhook | [List webhooks](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/list-webhooks.md) |
| `delete_webhook` | Remove your webhook | [Delete a webhook](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/delete-webhook.md) |
| `test_webhook` | Send a signed test event now | [Test a webhook](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/test-webhook.md) |
| `get_revenue` | Your monthly revenue statement | [Get your revenue statement](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/get-revenue.md) |
| `sandbox_pay` | Sandbox only: pay a payment | [Sandbox: pay](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/sandbox-pay.md) |
| `sandbox_tick` | Sandbox only: run the background work now | [Sandbox: tick](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/sandbox-tick.md) |
| `sandbox_ship` | Sandbox only: mark a shipment shipped or delivered | [Sandbox: ship](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/sandbox-ship.md) |

The `sandbox_` tools return `404` outside the sandbox.

## Arguments

* **`order_id`:** `create_order`, `create_shipment` and `create_token_shipment` take an `order_id`, which is sent as the `Idempotency-Key`. Have the assistant make a new one for each order and reuse it when retrying that order: a retry with the same `order_id` returns the same order, while a new `order_id` creates a second one. `get_order` and `get_order_verification` also take `order_id`, your id or ours.
* **Ids in the path:** `token_id` (token, quote and one-token shipment tools), `quote_id` (`get_quote`), `shipment_id` (`get_shipment`, `renew_shipment`, `sandbox_ship`), `wallet` (`list_wallet_tokens`), `webhook_id` (`delete_webhook`, `test_webhook`) and `intent_id` (`sandbox_pay`).
* **Everything else** is the endpoint's query parameter or body field of the same name.
* **Errors** come back as a tool result with `isError: true`, the HTTP status and the error body, including its `code`, so the assistant can read it and react.

> [!WARNING]
>
> `register_webhook` returns your webhook's signing secret once, to the assistant. Store it where your webhook receiver can read it, and don't paste it anywhere else.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.