Agent setup prompt

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. One tool, reveal_domain, spends from a monthly allowance; step 5 tells you when you may call it.

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

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.

2. Call whoami first

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

• plan — free, pro 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 Pro, 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 — roughly two thirds of the directory carries no category at all, and no category filter reaches those rows.

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, 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.
• For regular and featured, each reveal costs one from the monthly allowance. Ask the user first, 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:

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

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