URL: /docs/agent-setup/prompt --- title: "Agent setup prompt" sidebarTitle: "Setup prompt" description: "The instructions a coding agent fetches and follows to connect the Revised MCP server and run its first search." mode: "center" aiContext: "Machine-facing setup instructions. A human should start at /agent-setup instead." --- These are instructions for a coding agent, not a guide for a person. If you are a person, start at [Agent setup](/docs/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](https://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 Read `tier` before you publish, commit, or paste any name into anything the user did not ask for. - **`open`** — already published on the Revised website. Free to republish. - **`regular` and `featured`** — masked everywhere public, and disclosed **under the API terms only**. Do not republish them, do not write them into a public repository, and do not include them in anything that will be indexed. The [API terms](https://getrevised.com/terms) govern. ## 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