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

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:

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

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.