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

Related MCP server: discava – Business Directory for AI

Connecting

Transport: Streamable HTTP. Auth: Authorization: Bearer numa_live_…

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

Tools

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:

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

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.