URL: /docs/guides/claude-code --- title: Find domains with Claude Code description: Drive the directory from a Claude Code session over MCP — orient, shortlist, read closely, reveal, hold. --- Claude Code can search the directory directly through the [MCP server](/docs/mcp/introduction), which means you describe what you are looking for in a sentence instead of assembling query strings. This guide is the workflow that works: what to ask for at each step, what Claude does with it, and the four places where a plausible-sounding prompt gets you a worse answer than you think. Everything here is free except one step, and that step says so. ## Prerequisites - Claude Code, with the Revised server connected — [one command](/docs/mcp/install/claude-code). - A Revised account. The free plan is enough to follow all of this. ## 1. Let it orient itself Start every session here. Both calls are free and they prevent most of the ways the rest can go wrong. > Check my Revised account, then list the categories. Claude calls `whoami` and `list_categories`. What you want back is your plan, your reveals remaining, and a list of category codes. That second call matters more than it looks. **Category codes are Revised's own vocabulary, not English words.** There is no `marketing` and no `software`; a request about developer tooling maps onto `saas` or `ai`, and which one is not a guess you want a model making. An unknown code is refused outright rather than answered with an empty result, so a guess costs a round trip and tells you nothing about the directory. Roughly two thirds of the directory carries no category at all. If breadth matters more than precision, say so and filter on something else. ## 2. Ask for a shortlist Describe the shape of what you want, not a name. Claude turns it into `search_domains` arguments. > Find open-tier SaaS domains on .dev with a Revised Score of at least 60 and a low spam band. Two of them, ranked by score. ```json Result { "count": 2, "total": 10, "truncated": true, "fields": "summary", "listings": [ { "id": "N3DjogY3", "domain": "happyvalley.dev", "name_disclosed": true, "tier": "open", "tld": "dev", "revised_score": "70-80", "referring_domains": "50-100", "domain_authority": "0-9", "citability": null, "age_years": 6, "category": "saas", "spam": "low", "availability_checked_at": "2026-09-19T21:04:06.589Z", "metrics_missing": ["agent_citability"] }, { "id": "2wByPW6F", "domain": "tempomat.dev", "name_disclosed": true, "tier": "open", "tld": "dev", "revised_score": "65-75", "referring_domains": "10-50", "domain_authority": "0-9", "citability": null, "age_years": 6, "category": "saas", "spam": "low", "availability_checked_at": "2026-09-19T21:04:06.589Z", "metrics_missing": ["agent_citability"] } ] } ``` Real output, 22 September 2026. Three things in it are worth reading carefully. **`total` is 10 and `count` is 2, so `truncated` is true.** There is no paging on MCP. Asking Claude for "the next page" gets you nothing, because there is no cursor to follow — it has to re-search with different filters or a different sort. If a `total` comes back in the hundreds, the filters are too loose, not the page too short. **`name_disclosed` is true on both**, because `tier` is `open`. Open-tier names are already published on the Revised website: they cost no reveal and you may republish them. That is why it is the right tier to start on. **`citability` is `null` on both**, and `metrics_missing` says so explicitly rather than making you infer it from the null. Which leads to the trap that costs people the most time. **A minimum filter silently removes every row where the metric is unknown.** Had that search asked for a minimum Agent Citability, both of these rows would have vanished — not ranked low, gone. Absence is not zero. The same applies to `min_age_years`: it means "at least this old **and** we know how old it is", and age is unknown on a large share of the directory. If you want old domains without quietly dropping every unaged one, ask Claude to sort on age rather than filter on it, and to treat `null` as unknown rather than young. ## 3. Read the survivors closely > Get the full record for both of those. Claude calls `get_domain` on each id. That returns everything the summary left out: the sites that link in, the archived snapshot count, the estimated value, the hold state, and when availability was last re-checked. Budget roughly 60 tokens for a summary row and 230 for a full one. That gap is the whole reason for the two-step. Ask for `fields: "full"` on a fifty-row search and you get a five-figure token response to read two useful lines out of. When Claude reports back, hold it to the bands: - Metrics are **bands**, not points. `referring_domains` is `"50-100"`, not `73`. A band presented as a number is a fabrication, and averaging bands produces a figure that describes nothing. - `domain_authority: "0-9"` on both rows above is not a defect in the listing. Expired domains frequently carry real referring domains and a low DA — the two measure different things, and [Evaluate a domain](/docs/guides/evaluating-a-domain) covers which to believe when. - `availability_checked_at` is when Revised last looked. It is not a guarantee the name is free now. ## 4. Reveal, if you need to This is the only step that spends. > What would it cost to reveal the top three from that last search? Claude reads `tier` off each row and tells you before calling anything. `open` costs nothing. `regular` and `featured` cost one reveal each from the monthly allowance, and the grant is permanent — revealing the same listing again later is free. Say yes explicitly. The setup prompt tells the agent to ask first, and a reveal cannot be undone. ## 5. Hold instead of revealing more If you are building a shortlist for someone else to approve, holding beats revealing five more names. > Hold that one for me, and show me my active holds. A hold reserves the listing **inside Revised** for your plan's window so no other account can take it. It costs no reveal, though it does require that you revealed the listing first. A hold is not a registration. It does not stop anyone outside Revised registering the name. If you actually want it, register it at a registrar. ## Prompt patterns What changes the answer, in rough order of impact: | Instead of | Ask for | | --- | --- | | "Find me domains about marketing" | "List the categories first, then search the closest one" | | "Find `acmecorp.com` in the directory" | Nothing — search does not match real domain names, [by design](#what-search-does-not-do) | | "Show me the next page" | "Search again with a higher score floor" | | "Domains with at least 20 citability" | "Sort by citability and show me what is missing it" | | "What's the DA?" | "What band is the DA in?" | | "Find good domains" | A structural filter: tier, category, TLD, spam band, a score floor | ### What search does not do `query` covers the masked name hint, keyword tags, category and blurb. It **does not** cover the real domain name — not on any plan, not for any tier. Searching for a name you already have in mind will not find it, and Revised will not confirm whether a masked name is in the directory. If you have a listing id, use `get_domain`. ## What it costs | Step | Cost | | --- | --- | | `whoami`, `list_categories` | Free | | `search_domains`, `get_domain` | Free, unlimited inside the rate limit | | `hold_domain`, `list_holds`, `extend_hold`, `release_hold` | Free | | `reveal_domain` | One reveal — unless the listing is `open`, already revealed, or your plan has no ceiling | The rate limit is per key per minute: 20 on Free, 60 on Pro, 120 on Business. MCP calls and REST calls share one counter, so a script running beside your session draws from the same window. See [Rate limits](/docs/api/rate-limits). ## Before you publish anything it finds Check `tier` on every name before it leaves the session. **`open`** names are published on the Revised website and may be republished. **`regular`** and **`featured`** names are masked everywhere public and are disclosed **under the [API terms](https://getrevised.com/terms) only** — do not put them in a repository, an issue, or anything that will be indexed. Claude has been told this by the server's own instructions, but the obligation is the account holder's. ## When you want a script instead MCP is a shortlisting interface: at most 50 rows, no paging, no change feed, output sized for a context window. For a full pass over the directory, a nightly sync, or anything that needs a cursor, use the REST API instead — [Find domains](/docs/guides/finding-domains) is the same job in `GET /api/v1/domains`, and [Incremental sync](/docs/guides/incremental-sync) covers the change feed. Claude Code is good at writing that script, and the [Python walkthrough](/docs/examples/python-walkthrough) is a working one to hand it as a starting point. ## Next One line that sets any agent up, including the rules above. All nine tools: arguments, return shapes, refusal codes. Read a row properly: bands, missing data, linkers, the availability stamp. The full semantics — cooldowns, caps, extensions, refusals.