Mercantry Registry

Measured conclusion: Deep-tested. L2 outcome: tools_ok.

Agent-native registry: 168k+ real restaurants in LA, Hong Kong & Tokyo. Unranked, honest signals.

Measured statistics

Add to your agent

Copy this into your MCP client config:

{
  "mcpServers": {
    "Mercantry Registry": {
      "url": "https://mercantry.org/mcp",
      "transport": "streamable-http"
    }
  }
}

Measured tools (9)

• search_merchants

  Filter-based search over the restaurant registry (coverage cities + timezones in get_registry_meta). NOT ranked: results come back in deterministic order (merchant_id ASC by default; distance ASC when lat/lng given and order_by="distance"). Returns compact records with pagination. Use get_merchant for the full signal dump on a specific merchant. All filters are optional and combinable.

  Parameters:

  • lat — number — Latitude for geo-radius filter (requires lng and radius_km)
  • lng — number
  • limit — integer
  • offset — integer
  • open_at — string — ISO-8601 datetime; only merchants open at this time. With an explicit offset ('2026-07-18T19:00:00+09:00' or trailing Z) the instant is evaluated in each merchant's own timezone; without one it means each merchant's local wall clock
  • sandbox — boolean — Filter by merchant kind. true = sandbox test merchants only (safe integration targets: they book end-to-end and return a SIMULATED confirmation, never dialing a real venue). false = real merchants only — use this for any booking a human will act on. Omitted = both. Every result carries `sandbox`; never present a sandbox confirmation to a user as a real reservation.
  • order_by — string
  • radius_km — number — Radius in km around lat/lng
  • party_size — integer — Only merchants that can seat this party size
  • cuisine_tags — array — Match ANY of these cuisines, e.g. ['japanese','korean']
  • neighborhood — string — Exact neighborhood name, e.g. 'Mission'
  • bookable_only — boolean — Only merchants the registry can book right now (phone-verified, accepts reservations, not opted out)
  • attribute_tags — array — Match ALL of these attributes, e.g. ['outdoor_seating','vegetarian_friendly']
  • price_band_max — integer
  • price_band_min — integer

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• get_merchant

  Every field the registry holds on one merchant: schema fields, structured hours, raw feedback history, platform-observed operational stats, and per-field provenance with timestamps. Maximal data, zero opinion — the registry never scores or ranks.

  Parameters:

  • merchant_id (required) — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• get_availability

  V1 does NOT hold live table availability — availability is checked on the phone call at booking time. This tool returns the merchant's reservation policy, structured hours, and holiday exceptions so you can pick a plausible time before calling place_booking.

  Parameters:

  • merchant_id (required) — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• place_booking

  Request a table reservation. Returns booking_id with state 'queued' immediately; fulfillment is asynchronous (a call is placed to the merchant). Poll get_booking_status or supply callback_url for webhooks. RETRY SAFETY: pass a unique client_reference_id (recommended: always); if this call times out or errors ambiguously, retry with the SAME client_reference_id and the registry returns the already-created booking instead of double-booking the restaurant. Never re-call place_booking after a timeout without one. If the merchant counter-offers a time within window_minutes and accept_within_window=true, it is auto-accepted (recommended). Otherwise the booking pauses in needs_input for you to resolve via modify_booking. Merchants on the human_call channel are fulfilled by a human operator during the operator window published in get_registry_meta — those bookings queue until worked (up to the channel SLA), so book ahead rather than for the next hour.

  Parameters:

  • merchant_id (required) — string
  • party_size (required) — integer
  • datetime (required) — string — Requested time, ISO-8601. Naive ('2026-07-18T19:00') means the merchant's LOCAL wall time (see the merchant's timezone field); an explicit offset ('2026-07-18T19:00:00+09:00') is also accepted
  • reservation_name (required) — string — Name for the reservation
  • contact — string — Optional phone/email for confirmation relay to the end human
  • callback_url — string — Webhook URL for booking state-change events
  • window_minutes — integer — Acceptable +/- window around datetime
  • sandbox_outcome — string — TEST ONLY, sandbox merchants (sandbox: true): force the simulated call's result so you can exercise a specific branch on demand — confirmed, no_answer (retries then fails), counter_offer (pauses in needs_input), fully_booked, merchant_declined, bad_data. Rejected for real merchants; omit it in production
  • special_requests — string
  • client_reference_id — string — Your unique ID for this booking request (a UUID is ideal). Retrying with the same value returns the existing booking (idempotent_replay: true) instead of creating a duplicate; the same value with different parameters is rejected as client_reference_conflict
  • accept_within_window — boolean — Auto-accept merchant counter-offers inside the window (recommended: true)

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• get_booking_status

  State machine position for a booking: pending → queued → in_progress → confirmed | failed | needs_input (plus cancelled). Includes structured details on confirmation (confirmed_time, confirmation_code, merchant_instructions), structured failure reason (no_answer | fully_booked | closed | policy_mismatch | merchant_declined | bad_data), or needs_input options awaiting your decision. include_events=true returns the full audit log.

  Parameters:

  • booking_id (required) — string
  • include_events — boolean

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• modify_booking

  Amend a booking before or after the call. For a booking in needs_input: pass accept_option_index to take one of the merchant's offered times (confirms immediately), or pass a new datetime/party_size to re-queue an amended request. Modifying an already-confirmed booking cancels it and books the new request (new booking_id returned).

  Parameters:

  • booking_id (required) — string
  • datetime — string — New requested time, ISO-8601; naive means the merchant's local wall time
  • party_size — integer
  • window_minutes — integer
  • accept_option_index — integer — Index into needs_input_options to accept

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• cancel_booking

  Cancel a booking in any non-terminal state, or a confirmed reservation (the registry notifies the merchant). Cancellation is mandatory when the human no longer wants the table — no-shows destroy merchant trust and are tracked per developer key.

  Parameters:

  • booking_id (required) — string
  • reason — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• submit_feedback

  Report how a confirmed reservation actually went. Accepted only against a confirmed booking_id, once per booking, within 14 days of confirmation. Structured fields first; optional free text ≤ 500 chars. This corpus is served raw to all agents via get_merchant — it is never editorialized or turned into a score.

  Parameters:

  • booking_id (required) — string
  • reservation_honored (required) — boolean — Did the merchant honor the reservation?
  • free_text — string
  • would_repeat — boolean
  • seated_on_time — boolean
  • matched_description — boolean — Did the merchant match the registry's description?

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• get_registry_meta

  Evaluate the registry itself: per-city coverage (with each city's IANA timezone), merchant/bookable counts, verification and freshness stats, feedback corpus size, schema version, and the documented deterministic ordering rule. Honest by design — including how stale the data is.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

Publisher website Repository

Measured by MCPYP probing. Untested fields are omitted, never estimated. Listing is always free; MCPYP never proxies calls or stores user tokens.