MCP overview

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 — two shapes of one interface, sharing one rate-limit counter.

Endpoint

https://getrevised.com/api/mcp

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.

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

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

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.