Skip to main content
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) 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.
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.

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

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.
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.