Mercantry Registry

org.mercantryPublished by mercantry.orgOfficial publisherv0.1.0Updated Nov 2, 2026

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

VerifiedStreamable HTTPWeb executableDatabasesLocation & LifestyleBusiness & Commerce

Overview

AI-generated overview

Agent-facing restaurant registry for Los Angeles, Hong Kong and Tokyo, with unranked merchant search, full merchant records, and an asynchronous table-booking…

What you can do
  • Search and read merchants: filter-based, unranked search over the restaurant registry plus full per-merchant records with hours, provenance and raw feedback history.
  • Inspect availability and registry metadata: reservation policy, holiday exceptions, and coverage, freshness and schema stats for the registry itself.
  • Manage bookings: place an asynchronous reservation request, poll its status, modify or cancel it, and optionally supply a callback URL for webhooks.
  • Report outcomes: submit structured feedback once against a confirmed booking.
When to use it
Useful when an assistant needs structured restaurant data for these three cities, or needs to drive a reservation request and track it to confirmation. Worth adding only if you accept that real merchants are currently discovery-only and the booking loop is testable mainly against sandbox records.
Requirements
Remote Streamable HTTP endpoint; no packages or environment variables declared. Reads are free and unauthenticated; developer keys are optional for abuse control. A callback URL is optional for booking webhooks.
Before you install
The service is pre-launch: bookings against real merchants return a structured rejection, and only sandbox merchants complete the loop. Booking, modifying and cancelling act on real-world reservations and notify merchants; no-shows are tracked per developer key, so cancel when plans change. Feedback is served raw to all agents. Reservation name and contact are stored for the booking.

Installation

In SourceWeft

  1. Open Mercantry Registry in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/org.mercantry%2Fregistry/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "mercantry-registry": {
      "type": "http",
      "url": "https://mercantry.org/mcp"
    }
  }
}

README

Mercantry

Mercantry is an open commerce registry for AI agents — structured merchant data, honest signals, and real-world booking fulfillment.

Current status — read this first. Mercantry is pre-launch. What is real and what is not, precisely:

  • The merchant data is real: 168,000+ restaurants across Los Angeles, Hong Kong, and Tokyo, built exclusively from openly licensed sources (Overture Maps CDLA-P-2.0 + official government registers), conflated with per-field provenance and QA-gated versioned releases. Live counts: get_registry_meta.
  • Real merchants are discovery-only for now: place_booking against a real merchant returns the structured rejection fulfillment_not_live. A booking guard makes it structurally impossible for our booking simulator to dial a real restaurant.
  • The booking loop is testable end-to-end against sandbox: true merchants — fictional records with deterministic outcomes ("test cards for bookings"). Do not call sandbox phone numbers; they are not real businesses.
  • Fulfillment, when it launches, is human-operated phone booking on a phone-verified merchant tranche (voice automation is deferred). Outbound-calling sections of the spec operate only after legal review — publication of the spec is not operation.
  • Mercantry is built and operated by a team of AI agents with human oversight, stated here as a fact rather than a gimmick.

Connect your agent

The live endpoint serves MCP over Streamable HTTP:

bash
claude mcp add --transport http mercantry https://agentic-commerce-registry.fly.dev/mcp
  • REST mirror: /v1 — self-describing via /v1/openapi.json
  • Discovery manifest: /.well-known/mcp.json · agent card: /.well-known/agent-card.json · health: /healthz · PII-free ops stats: /v1/stats · privacy policy: /privacy · demo & reviewer guide: /demo
  • Keys are optional (abuse control, not gating): POST /v1/keys with developer_name + contact. All reads are free and unauthenticated.
  • Bulk export encouraged: GET /v1/export/merchants.ndjson — caching, embedding, and training on the data are permitted under the open license.

Copy-paste integrations — curl, Claude Code/Desktop, raw MCP JSON-RPC, OpenAI Agents SDK, LangChain, webhook receiver: examples/. Agent-first tool documentation with example transcripts: docs/mcp-tools.md. If you are an agent working in this repo, read AGENTS.md.

MCP tools

search_merchants (filter-based, never ranked, deterministic documented order) · get_merchant (full signal dump: every field, raw feedback history, operational stats, per-field provenance) · get_availability (honest: performed_at_booking) · place_booking (async) · get_booking_status · modify_booking · cancel_booking (mandatory when plans change — no-shows are tracked per developer key) · submit_feedback (confirmed bookings only, once, within 14 days) · get_registry_meta (evaluate the registry itself, staleness included)

Run it yourself

bash
npm installnpm run dev        # seeds a sandbox corpus on first boot; everything in one process
SurfaceWhere
MCP (Streamable HTTP)http://localhost:4100/mcp
REST mirror + OpenAPIhttp://localhost:4100/v1
Landing page (public fact page)http://localhost:4100/
Ops Console (gate with OPS_TOKEN)http://localhost:4100/ops/
Booking status pageshttp://localhost:4100/status/:booking_id
bash
npm test           # full suitenpm run typecheck

Deployment (Docker/Fly.io), agent onboarding, and the security checklist: docs/deployment.md.

Architecture

┌─────────────┐     ┌──────────────┐     ┌────────────────────┐│  Agent      │────▶│  MCP Server   │────▶│ Fulfillment        ││  (customer) │◀────│ src/mcp       │◀────│ Orchestrator       │└─────────────┘     └──────┬───────┘     │ src/orchestrator   │                           │             │  └─ human operator │                    ┌──────▼───────┐     └─────────┬──────────┘                    │  Registry DB  │◀──────────────┘                    │  src/db       │     ┌────────────────────┐                    └──────▲───────┘     │  Ops Console       │                           │             │  src/ops + src/api │                    ┌──────┴───────┐     └────────────────────┘                    │  Ingestion    │ src/ingest — LA · HK · Tokyo,                    │  & QA gate    │ openly licensed sources only                    └──────────────┘

The customer is the agent, not the human. One uniform interface with swappable fulfillment backends: agents integrate once; behind the interface, fulfillment can graduate from human phone calls to native merchant integrations without the agent changing a line.

Hard rules encoded in this codebase

  • No ranking, ever. No score fields exist in the schema; search order is deterministic and documented. The registry returns signals, never ordered opinions.
  • No scraped review text. The only feedback served is transaction-verified, submitted by agents against confirmed bookings.
  • Openly licensed data only. Overture Maps (CDLA-P-2.0) + official government registers; per-field provenance with timestamps; QA-gated releases with published drop counts.
  • Opt-out is immediate and permanent. A merchant requesting removal is hard-excluded from discovery and booking the same day.
  • Every booking is auditable. Full event log: tool calls, transcripts, timestamped state transitions.
  • PII is minimal. Reservation name/contact stored only for the booking, never exposed via read tools.
  • Honesty over polish. get_availability says performed_at_booking instead of pretending; get_registry_meta exposes our own staleness; sandbox vs. real is labeled per merchant.

Spec

The full product spec lives at docs/requirements.md. Sections describing outbound calling are published for openness but nothing in them operates until legal review is complete — see the banner at the top of that document.

License

Apache-2.0. The registry spec, code, and data schema are open — openness is the strategy, not a concession.

Source: README.md at commit 0d7da88

Tools

9

search_merchants

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.

Parameterslatlnglimitoffsetopen_atsandboxorder_byradius_kmparty_sizecuisine_tagsneighborhoodbookable_only+3 more

get_merchant

Get merchant (full signal dump)

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.

Parametersmerchant_idrequired

get_availability

Get availability (honest v1 behavior)

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.

Parametersmerchant_idrequired

place_booking

Place a booking (async)

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.

Parameterscontactdatetimerequiredparty_sizerequiredmerchant_idrequiredcallback_urlwindow_minutessandbox_outcomereservation_namerequiredspecial_requestsclient_reference_idaccept_within_window

get_booking_status

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.

Parametersbooking_idrequiredinclude_events

modify_booking

Modify a booking / resolve needs_input

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

Parametersdatetimebooking_idrequiredparty_sizewindow_minutesaccept_option_index

cancel_booking

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

Parametersreasonbooking_idrequired

submit_feedback

Submit post-visit 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.

Parametersfree_textbooking_idrequiredwould_repeatseated_on_timematched_descriptionreservation_honoredrequired

get_registry_meta

Get registry metadata

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.

Takes no parameters.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts