Integration recipes

Build a set browser

1. Call GET /catalog/sets.
2. Let the user choose a set using its returned id.
3. URL-encode that ID in GET /catalog/sets/:code/cards.
4. Render each card's name, number, language and variant. Show a fallback when imageUrl is absent.
5. Paginate with page and pageSize; use meta.total for navigation.

An import can change results between pages. Retain card IDs when reconciling results and avoid promising a frozen full export.

Resolve an identity

Search using a card name and printed number. Apply a release zone or set-code filter if known. Ask the user to choose the correct language and printing from the candidates, then fetch the selected id through the card endpoint.

The search API does not return a confidence score or guarantee the first match is correct. It does not identify photographs or return prices.

The same workflow works with search_cards and get_card in MCP.