Agent MCP

Connect an AI agent to HiMarket over MCP to search the catalog and market, and to manage your sell listings and buylist.

What it is

HiMarket exposes a Model Context Protocol (MCP) server so an AI agent can use the marketplace as you: search the catalog, read the market, and manage your own sell listings and buylist. The agent acts as the account owner — it never receives staff or admin powers.

Endpoint: https://www.himarket.hk/api/mcp (Streamable HTTP). Works with MCP-capable clients such as Cursor and Claude.

Connecting

Most developer clients authenticate with a Personal Access Token as a bearer token. Create one under API tokens on your Profile page (you must be signed in). The full token is shown once at creation — treat it like a password.

Open Profile and expand API tokens.
Create a token, choosing its scopes and mode (see below).
Configure your MCP client with the endpoint above and the token as a bearer (Authorization: Bearer …).

Clients that support MCP OAuth discovery can connect without pasting a token. After you approve the app, HiMarket issues a token with the scopes and mode you chose. The consent screen defaults to propose mode.

Scopes and modes

Every token has one or more scopes. These are the only scopes:

Scope	Grants
`read`	Catalog, market, your listings and buylist, `whoami`, `get_capacity`, `get_pricing_guidance`
`sellist:write`	Create, price, and cancel sell listings
`buylist:write`	Create, price, and cancel buylist items

Every token also has a mode, chosen when it is created:

Mode	Behavior
`direct`	Write tools apply immediately to the live marketplace.
`propose`	Live write tools are denied. The agent submits drafts with `propose_changes`; you review and approve them on My Listings before anything goes live.

Propose mode is the safe default for third-party agents. Drafts are inert until you approve them. whoami reports the mode as tokenMode, so an agent can tell up front whether its writes go live or must go through propose_changes.

Two games

Magic: The Gathering and Riftbound share one marketplace and one account. Catalog tools default to MTG and take game: "riftbound" to query the Riftbound catalog instead — some card names exist in both games, so the scope matters.

Everything keyed by printing id is already game-agnostic: Riftbound printing ids carry the rb- prefix. search_catalog, get_format_staples, and get_demand_overview are MTG-shaped and stay MTG-only.

Tool overview

Clients introspect the full schemas; this is a compact map of what exists. One line each.

Discovery and read (`read`)

Tool	Purpose
`search_cards`	Name search over HiMarket's catalog (prefix-preferred, with fuzzy fallback).
`search_catalog`	Structured MTG catalog search (type, color, format legality, set, price range, and more).
`get_card_printings`	Every paper printing of a card name, with set, collector number, and reference prices.
`get_reference_prices`	Batch reference prices and a live supply snapshot for up to 25 names.
`get_supply_counts`	Batch copy-accurate live sell counts (and cheapest live sell) for up to 25 names.
`get_for_sale`	Active for-sale rows for one exact card name.
`get_market_overview`	Aggregated lowest-sell / highest-buy per printing.
`get_demand_overview`	Card names ranked by HiMarket page views, joined with supply and staple signals (MTG).
`get_format_staples`	Top tournament staples of one constructed format (MTG).
`get_pricing_guidance`	Preset ratios, price floors, condition factors, and the Riftbound Chinese language factor.
`whoami`	The account this token acts as, plus the token's scopes and `tokenMode`.
`get_capacity`	Active sell/buy counts, account caps, and slots remaining.
`list_my_sellist`	This account's sell listings as compact rows.
`list_my_buylist`	This account's active buylist items, same compact row shape.
`list_my_cards`	The account's entire collection, including cards not for sale.

Live writes — `direct` mode only

These apply immediately. In propose mode they are denied; use propose_changes instead. Each side needs its write scope (sellist:write or buylist:write).

Tool	Purpose
`create_sellist`	Create 1–20 copies of one printing as sell listings.
`bulk_create_sellist`	Create sell listings for many distinct printings (auto-chunked).
`set_sellist_price` / `bulk_set_sellist_price`	Set absolute HK$ sell prices.
`bulk_price_sellist_by_ratio`	Price sell listings at `ratio` × reference.
`cancel_sellist` / `bulk_cancel_sellist`	Cancel (soft-delete) listings entirely.
`bulk_delist`	Remove listings from sale; the cards stay in your collection.
`create_buylist`	Create 1–20 copies of one buy offer, priced immediately.
`bulk_create_buylist`	Create buy offers for many printings (auto-chunked). Optional `maxTotalHKD` budget.
`set_buylist_price` / `bulk_price_buylist_by_ratio`	Price buy offers (absolute HK$ or by `ratio`).
`cancel_buylist` / `bulk_cancel_buylist`	Cancel buy offers.

Proposals

propose_changes needs the write scope of the side being edited. Listing and fetching proposals needs read. Cancelling a still-pending draft needs any write scope.

Tool	Purpose
`propose_changes`	Submit a draft mass edit for the owner to review and approve on My Listings.
`list_my_proposals`	List this account's proposals (id, side, status, plan summary).
`get_proposal`	Fetch one proposal in full — poll to see whether it was approved.
`cancel_proposal`	Withdraw a still-pending draft.

Pricing

All prices are HK$ integers. ratio pricing = ratio × the printing's USD reference (sell side is condition-adjusted; buy side is the seller-credit ratio). Riftbound Chinese (zhs / zht) references are scaled by 0.6 (on the buy side, only when every accepted language is Chinese).

Floors: sell HK$8, buy HK$4.

A buy-side ratio on a reference below roughly US$0.5 / ratio rounds to zero and is rejected. For very cheap cards, pass an absolute price instead (minimum HK$4).

Money guardrails

Budget abort: bulk_create_buylist and propose_changes accept optional maxTotalHKD. If the summed exposure would exceed it, the whole call is aborted and nothing is written.
Real money: buylist fulfilment debits real store credit from the buyer's account.
Fees: the buyer pays a HK$3 + 4% transaction fee on top of the offer when a buylist item is fulfilled; the seller receives the full offer.
Rate limits: per-token rate limits apply to both MCP tools and equivalent API calls.

Safety

Tokens are revocable at any time from Profile → API tokens. Revoking an OAuth-connected token disconnects that app.
Propose-mode drafts are inert until you approve them on My Listings. Approve, reject, and apply are done in your signed-in browser session — not by the agent.