NUM MCP Server

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 Code
claude mcp add --transport http num https://itsnum.com/mcp

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.

---

Quick start

Tool discovery is open. You can see what the server offers with no credentials at all:

curl -sS -X POST https://itsnum.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

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:

curl -sS -X POST https://itsnum.com/api/agent/signup \
  -H 'content-type: application/json' \
  -d '{
        "agent_name": "Acme Listings Bot",
        "operator_name": "Acme Ltd",
        "operator_email": "ops@acme.example",
        "purpose": "Suggest restaurants and bars to travellers in Thailand."
      }'

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

Connecting

Transport: Streamable HTTP. Auth: OAuth 2.1, or Authorization: Bearer numa_live_…. With OAuth, drop the headers block from any config below.

{
  "mcpServers": {
    "num": {
      "type": "http",
      "url": "https://itsnum.com/mcp",
      "headers": { "Authorization": "Bearer numa_live_YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "num": {
      "url": "https://itsnum.com/mcp",
      "headers": { "Authorization": "Bearer numa_live_YOUR_KEY" }
    }
  }
}

{
  "servers": {
    "num": {
      "type": "http",
      "url": "https://itsnum.com/mcp",
      "headers": { "Authorization": "Bearer ${input:num_key}" }
    }
  },
  "inputs": [
    { "id": "num_key", "type": "promptString", "description": "NUM API key", "password": true }
  ]
}

Things to ask once it is connected

• Find three Thai restaurants in Patong, Phuket, with a phone number I can call.
• Which spas are listed in Edinburgh? Show me the full record for the first one.
• What rooftop bars in Bangkok are in NUM's directory, and which have been claimed by their owner?
• I own a café in Kata, Phuket. Submit it to NUM as the owner. Here are the details: …
• Show me everything I have submitted to NUM and what the reviewer decided.

Tools

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.

Two things worth understanding before you build

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:

• A verified guest is a traveller 5arz confirmed is a unique real human.
• A verified listing is one whose owner proved control of the contact details already published on it.
• Unclaimed listings are mapped, not verified.

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.

Declare relationships honestly

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.

Rate limits and etiquette

• Reads are metered per day by tier; writes are not metered.
• Signup is capped at 5 keys per address per day. One key per agent is plenty — reuse it.
• 429 means you hit a limit. Back off; do not retry in a tight loop.

Discovery surfaces

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/

Pricing

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.

Support

• Questions, bugs, partnership: info@itsnum.com
• Privacy policy · Terms
• Security: see SECURITY.md
• Issues on this repo are welcome for docs and client-example problems.

Licence

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.