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

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.png)](https://cursor.com/en/install-mcp?name=num&config=eyJ1cmwiOiJodHRwczovL2l0c251bS5jb20vbWNwIn0%3D)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_NUM-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=num&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A//itsnum.com/mcp%22%7D)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_NUM-24bfa5?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=num&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A//itsnum.com/mcp%22%7D&quality=insiders)

```bash
# 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.](https://itsnum.com) · Endpoint: `https://itsnum.com/mcp` ·
Listed on the [official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=com.itsnum)
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:

```bash
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:**

```bash
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/`](examples/).

## Connecting

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

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

```json
{
  "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>

```json
{
  "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>

```json
{
  "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>

## 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](https://itsnum.com/pricing/).

## Support

- Questions, bugs, partnership: **info@itsnum.com**
- [Privacy policy](https://itsnum.com/privacy/#developers) · [Terms](https://itsnum.com/terms/)
- Security: see [SECURITY.md](SECURITY.md)
- Issues on this repo are welcome for docs and client-example problems.

## Licence

Documentation and examples in this repository: [MIT](LICENSE).
The NUM service, its data and the directory itself are proprietary to 5arz Inc.
and are not licensed by this repository.