NUM MCP Server

A remote MCP server for travel places. Search a directory of 2,529,721 places across 77 destinations in 38 countries, and submit businesses or promotions for human review.

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 a free API key:

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: Authorization: Bearer numa_live_…

<details> <summary>Claude Desktop / Claude Code</summary>

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

</details>

<details> <summary>Cursor — <code>.cursor/mcp.json</code></summary>

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

</details>

<details> <summary>VS Code — <code>.vscode/mcp.json</code></summary>

{
  "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 }
  ]
}

</details>

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 MCP tool annotations (readOnlyHint, destructiveHint, openWorldHint), so a client can tell which tools only read and which write.

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

Free for travellers, and there is no traveller booking fee. Businesses list free and pay 10% of a booking NUM completes, out of their side, never added to the traveller's bill. Nothing on walk-ins, nothing on a business's own repeat customers, no monthly minimum. Full detail at itsnum.com/pricing.

Support

• Questions, bugs, partnership: info@5arz.com
• 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.