Agent setup prompt

The instructions a coding agent fetches and follows to connect the Revised MCP server and run its first search.

These are instructions for a coding agent, not a guide for a person. If you are a person, start at Agent setup and press Copy prompt. If you are an agent, the rest of this page is your task.

Task

Connect to Revised — a directory of expired and dropped domain names that still carry backlinks — and be ready to search it on the user’s behalf. Work through the steps in order. Report what you did at the end.

Nothing on this page costs money. Two tools can spend. reveal_domain spends reveal credits on a plan that has a ceiling; step 5 tells you when you may call it. run_deep_check spends paid-check credits: never call it unless the user has agreed to its price.

1. Connect the MCP server

The endpoint is https://getrevised.com/api/mcp. It speaks Streamable HTTP and is stateless — every request carries its own credential.

Pick the line matching the agent you are:

Claude Code: claude mcp add --transport http revised https://getrevised.com/api/mcp, then the user runs /mcp, chooses revised and picks Authenticate
Codex: codex mcp add revised --url https://getrevised.com/api/mcp, then codex mcp login revised
Cursor: add to ~/.cursor/mcp.json under mcpServers as {"url": "https://getrevised.com/api/mcp"}
VS Code: add to .vscode/mcp.json under servers as {"type": "http", "url": "https://getrevised.com/api/mcp"}
opencode: add to opencode.json under mcp as {"type": "remote", "url": "https://getrevised.com/api/mcp"}
Any other MCP client: register an HTTP MCP server named revised at that URL, in whatever config file the client uses.

Authentication is OAuth 2.1 by default and needs no configuration: the server returns 401 with a challenge, your client discovers the authorisation server from it, and the user signs in through their browser. You cannot complete that handshake yourself — it requires a human at a browser. Add the server, then tell the user to complete the sign-in and wait for them. Tell them how, for their client: in Claude Code, run /mcp, choose revised, pick Authenticate and finish in the browser tab; in Codex, run codex mcp login revised; in Cursor, click Needs login under Settings → MCP.

Two things that look like success but are not:

claude mcp get revised (or claude mcp list) can report Connected before anyone has signed in. That only means the endpoint answered; the tools are not available until the sign-in is finished.
If you added the server during this conversation, its tools may not load into the running session. After the sign-in, ask the user to run /mcp (or restart the session) before you call whoami.

If there is no browser available (CI, a container), ask the user for an API key from getrevised.com/account and send it as Authorization: Bearer rvd_.... Do not put a key in a file that is checked into a repository.

Then offer the Revised skill. If your client reads agent skills (Claude Code, Codex, Cursor, opencode and others do), offer to install it: npx skills add getrevised/skills. It covers what this page does not: vetting a candidate against the user’s own site, registering it at Cloudflare, Vercel or Porkbun after the user confirms the name and price, and a redirect map of relevant 301s and 410s. It writes into the project’s skills directory (-g installs it globally), so ask before running it, and skip it if the user declines. Source: https://github.com/getrevised/skills

2. Call `whoami` first

It is free, and it returns the three numbers that bound everything else:

plan — free, starter or business.
reveals — remaining and resets_at. unlimited: true means there is no ceiling and nothing you do will spend one. Read unlimited, not limit: limit: null means no ceiling, which is the opposite of zero.
rate_limit.per_minute — 20 on Free, 60 on Starter, 120 on Business. MCP calls and REST calls share this one counter.

Report the plan and the reveal position to the user before doing anything that spends.

3. Call `list_categories` before your first search

Free and cached. Category is the strongest filter in the directory, and the codes are Revised’s own, not English words. “Marketing” and “software” are not among them. An unknown code is refused outright, not answered with an empty result, so guessing costs a round trip and teaches you nothing.

Map the user’s wording onto a code you have actually read off this list. If nothing fits, filter on something else. A category is inferred from archived pages: it can be the broad other, or missing, and no category filter reaches a row that has none.

4. Search, and rank on the summary

search_domains is free and unlimited inside the rate limit. It never spends a reveal.

Filter structurally — category, TLD, a metric floor, tier — not by free text. query covers the masked hint, tags, category and blurb, and deliberately not the real domain name. Searching for a name the user already has in mind will not find it.
Start with fields: "summary". Budget roughly 60 tokens a summary row against 230 a full one, and you only need the full one for the handful that survive.
There is no paging. count is what you were handed, total is what matched, truncated says count < total. A large total means narrow the filters or change the sort — there is no next page.
Minimum filters drop rows where the metric is unknown rather than ranking them low. min_age_years: 1 means “at least a year old and we know how old it is”. Check metrics_missing on the rows you get back.

Then call get_domain on the few that survive.

5. Reveal only with the user’s say-so

reveal_domain is the only tool that spends a reveal, and the grant is permanent. Before calling it:

Read tier on the listing. open costs nothing — the name is already published on the Revised website. Start there.
On a plan with a ceiling, a regular reveal costs one credit and a featured reveal costs reveals.featured_credits from whoami, refused when that is null. Free has no reveals at all, so masked names stay masked there; Starter and Business have unlimited: true and receive every name already. Ask the user first wherever a reveal would spend, naming the listing and what is left.
It is idempotent: revealing the same listing again is free.

If you are shortlisting for someone else to decide on, prefer hold_domain over revealing more names. A hold reserves the listing inside Revised for the plan’s window and costs no reveal — though it does require that the listing was revealed first.

A hold is not a registration. It does not stop anyone outside Revised registering the name. Say so when you report one.

6. Republication rules

What to report

When you are done, tell the user:

Whether the server is connected, and how it authenticated (auth from whoami).
Their plan, reveals remaining, and rate limit.
What you searched for and how many matched versus how many you were handed.
Anything you revealed, and what it cost.
Whether the Revised skill was installed.

Notes

A listing is evidence about a name, never a recommendation. These are expired domains: the history is the reason to look and also the reason to check.
availability_checked_at is a timestamp, not a guarantee. A name available when Revised last checked can be gone now. Verify at a registrar before the user acts.
Metrics arrive as bands, not points — referring_domains: "100-250", not 173. Do not present a band as a precise figure, and do not average bands.
Full documentation: https://getrevised.com/docs — tool reference at https://getrevised.com/docs/mcp/tools

Edit this page