The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the NUM listing page.
Real places for your agent. A remote MCP server for travel: search a directory of more than 2.5 million places — restaurants, bars, hotels, spas, tours and shops, deepest in Thailand and the UK — and submit businesses or promotions for human review.
Claude and ChatGPT: add https://itsnum.com/mcp as a custom connector, sign in to NUM, approve. No key.
Operated by 5arz Inc. · Endpoint: https://itsnum.com/mcp ·
Listed on the official MCP Registry
as com.itsnum/num.
This repository holds the documentation, connection configs and client examples. The server itself is hosted — there is nothing to install or run.
Tool discovery is open. You can see what the server offers with no credentials at all:
Calling a tool needs you to be signed in. There are two ways, and they share one quota.
1. Sign in (OAuth 2.1) — Claude, ChatGPT, Cursor, VS Code and any client that supports MCP
authorization. Give the client the URL and nothing else. The first tool call opens a NUM
sign-in window; approve num.read (search) and num.write (submit). PKCE and dynamic client
registration are supported; metadata is at
https://itsnum.com/.well-known/oauth-protected-resource. Access lasts an hour and renews on
its own. Disconnect from the client at any time.
2. A free API key — scripts, servers and clients without OAuth:
The key is returned once and is not recoverable. Save it immediately.
Rotate at POST /api/agent/me/rotate; check your usage at GET /api/agent/me.
Runnable versions of all of the above are in examples/.
Transport: Streamable HTTP. Auth: OAuth 2.1, or Authorization: Bearer numa_live_….
With OAuth, drop the headers block from any config below.
.cursor/mcp.json.vscode/mcp.json| Tool | What it does | Metered |
|---|---|---|
num_search_places | Search by free text, city, country or category. At least one required. | Yes — read |
num_get_place | Full record for one place by place_id. | Yes — read |
num_submit_business | Submit a business. Reviewed by a person before anyone sees it. | No |
num_submit_promo | Post a promotion, special, event or ad against a business you submitted. | No |
num_list_submissions | Everything you submitted and what a reviewer decided. | No |
All five carry a title and MCP tool annotations. The three read tools are readOnlyHint;
the two submit tools are destructiveHint, because re-sending the same external_ref or
promo_ref overwrites your pending submission — so a well-behaved client asks the person first.
Quotas — reads per day: free 100 · bundle 2,000 · pro 20,000 · full 200,000. Writes are unlimited on every tier, including free. We would rather have your data than your money.
Submissions are not published automatically. Everything sent through
num_submit_business or num_submit_promo is stored but stays invisible to travellers
until a human at 5arz approves it. This is deliberate and it is not a queue you can jump.
Do not tell a user their listing is live because the tool returned success — poll
num_list_submissions for the reviewer's decision.
"Verified" has a specific meaning here, and it is not a review score. On NUM, verified describes a person or a claimed listing — never a place:
If you surface NUM data to end users, please do not render "verified" as a quality, rating or endorsement signal. It says this is a real person or this owner is real — nothing about whether the food is good.
num_submit_business asks for your relationship to the business, and the value matters:
| Value | Means |
|---|---|
owner | You or your operator own the business |
authorized_agent | The business engaged you to act for it |
third_party | You are adding a place you know of, with no relationship |
Guessing owner to look more credible is the fastest way to get an agent key revoked.
Never invent contact details — an unreachable phone number is worse than a blank field.
429 means you hit a limit. Back off; do not retry in a tight loop.| What | Where |
|---|---|
| MCP manifest | https://itsnum.com/.well-known/mcp.json |
| MCP server card | https://itsnum.com/.well-known/mcp/server-card.json |
| OAuth metadata | https://itsnum.com/.well-known/oauth-protected-resource |
| OpenAPI (REST equivalent) | https://itsnum.com/openapi.json |
| Plain-language summary | https://itsnum.com/llms.txt |
| Full text corpus | https://itsnum.com/llms-full.txt |
| Machine-readable business data | https://itsnum.com/for-ai/ |
| Agent platform docs | https://itsnum.com/agents/ |
The API and the MCP server are free: 100 reads a day, unlimited submissions. Higher read quotas are on the same plans as the business dashboard, from $9.99 a month.
Free for travellers, and there is no traveller booking fee. Businesses list free and pay only on a booking NUM completes: 10% on a table, 15% on a room, 20% on an activity, out of their side, never added to the traveller's bill. No-shows and declined bookings cost nothing. Full detail at itsnum.com/pricing.
Documentation and examples in this repository: MIT. The NUM service, its data and the directory itself are proprietary to 5arz Inc. and are not licensed by this repository.