URL: /docs/mcp/introduction
---
title: MCP overview
description: The Revised directory as Model Context Protocol tools — one stateless HTTP endpoint, nine tools, OAuth or an API key.
---
The Revised MCP server exposes the directory of expired domains as tools an AI assistant can call: search the directory, read a listing, reveal a name, and hold a candidate while a person decides. It is the same data, the same account and the same limits as the [REST API](/docs/api/introduction) — two shapes of one interface, sharing one rate-limit counter.
## Endpoint
```text
https://getrevised.com/api/mcp
```
| | |
| --- | --- |
| Transport | Streamable HTTP |
| Sessions | None. Stateless: each `POST` carries its own credential and its own request, and is answered completely. |
| Protocol version | `2025-06-18`, with `2025-03-26` also accepted on the wire |
| Methods | `POST` only. `GET` and `DELETE` are `405` — there is no session to stream into or to delete. `OPTIONS` answers the CORS preflight. |
| Server name | `revised`, version `1.0.0` |
| Maximum request body | 256 KiB |
| Authentication | OAuth 2.1 via Clerk, or an `rvd_` API key. See [MCP authentication](/docs/mcp/authentication). |
The path sits outside `/api/v1` deliberately: the version in that path belongs to the REST resource shapes, and MCP versions itself through the protocol handshake instead.
## The nine tools
Full reference on [Tools](/docs/mcp/tools).
| Tool | Costs | What it does |
| --- | --- | --- |
| [`whoami`](/docs/mcp/tools#whoami) | free | Plan, reveals left, rate limit, hold allowance, how this session authenticated |
| [`list_categories`](/docs/mcp/tools#list_categories) | free | Every category code with its label and counts |
| [`search_domains`](/docs/mcp/tools#search_domains) | free | Search and filter the directory, up to 50 rows |
| [`get_domain`](/docs/mcp/tools#get_domain) | free | One listing, every field |
| [`reveal_domain`](/docs/mcp/tools#reveal_domain) | **one reveal** | Uncover a listing's real name |
| [`hold_domain`](/docs/mcp/tools#hold_domain) | free | Reserve a listing inside Revised |
| [`list_holds`](/docs/mcp/tools#list_holds) | free | This account's running and ended holds |
| [`extend_hold`](/docs/mcp/tools#extend_hold) | free | Take the one extension a hold allows |
| [`release_hold`](/docs/mcp/tools#release_hold) | free | End a hold early |
`reveal_domain` is the only tool that can spend. Everything else is free within the rate limit.
## How a session should go
1. **`whoami` first.** It is free and returns the three numbers everything else is bounded by: the plan, the reveals left this month and when they reset, and the per-minute rate limit. `reveals.unlimited: true` means there is no ceiling and nothing in the session will spend one.
`whoami` and the REST [`GET /api/v1/me`](/docs/api/introduction#endpoints) answer the same question in **different shapes** — `whoami` adds `auth`, `holds` and `reveals.unlimited`, and spells the rate limit `per_minute` / `remaining_this_minute` where REST says `limit` / `remaining`. Read the [tool reference](/docs/mcp/tools#whoami) for the MCP shape; do not port a REST parser across.
2. **`list_categories` before the first search.** Category is the strongest filter here and the codes are Revised's own, not a user's words — `marketing` and `software` are not among them. An unknown code is **refused**, not answered with an empty shelf.
3. **Search before revealing.** `search_domains` is free and never spends a reveal; a listing the caller is not entitled to name comes back fully populated with its metrics and a masked `domain`.
4. **Rank on the summary, read the full row on the survivors.** `search_domains` returns lean rows by default; pass `fields: "full"`, or call `get_domain`, for everything.
5. **Prefer a hold over repeated reveals** when shortlisting for someone else to decide on.
## What MCP does not do
**There is no paging.** `search_domains` returns at most 50 listings: `count` is what you were handed, `total` is how many matched, and `truncated` is `count < total`. To get different rows, change the filters or the sort. This is a shortlisting tool whose output goes into a context window, and 250 listings is a page a model reads badly and pays for twice.
**There is no change feed.** For a full pass over the directory or for incremental sync, use [`GET /api/v1/domains`](/docs/api/pagination) with a cursor — which MCP deliberately does not mirror.
## One counter, two interfaces
Rate limits are per key and per plan — Free 20, Pro 60, Business 120 requests a minute — and MCP calls and REST calls come out of the same window. On an OAuth connection the counter is shared with everything else that account has connected. See [Rate limits](/docs/api/rate-limits).
An agent is bound by exactly the same reveal allowance, hold cap and cooldown as a person. The token cannot widen any of them.
## Republication
Read `tier` before publishing any name an agent surfaces.
`open` names are already published on the Revised website, so they may be republished. `regular` and `featured` names are masked everywhere on the site and are disclosed **under the API terms only** — do not republish them. The [API terms](https://getrevised.com/terms) govern.
A listing is evidence about a name, never a recommendation. Expired names carry history worth checking before building on one.
## Connect a client
Any MCP client that speaks Streamable HTTP works. Give it the URL and nothing else: it discovers the authorisation server from the challenge on the first `401`, signs the person in through their browser, and keeps its own token — so there is no key to paste and none sitting in a configuration file. For a script or a container with no browser to sign in from, send an API key instead.