Skip to content
Have I Been Squatted logo Have I Been Squatted logo Have I Been Squatted Docs

MCP server

The Have I Been Squatted MCP server lets AI assistants analyze domains, hunt lookalikes, search certificate transparency, and work with your organization’s detections, alerts, monitored domains, detection rules and takedowns.

Setting Value
Server URL https://mcp.haveibeensquatted.com/mcp
Transport Streamable HTTP
Authentication OAuth with dynamic client registration; no client ID or API key needed
Interactive views MCP Apps for show_domain and show_domains

Connect a client

Section titled “Connect a client”

On claude.ai, Claude Desktop and Claude mobile, add Have I Been Squatted from the Connectors directory.

To add it by URL instead, add a custom connector with the URL https://mcp.haveibeensquatted.com/mcp.

In Claude Code, install the plugin from the public agent-plugins repository:

Terminal window
claude plugin marketplace add haveibeensquatted/agent-plugins
claude plugin install haveibeensquatted@haveibeensquatted

Or add the server directly, then run /mcp in Claude Code to sign in:

Terminal window
claude mcp add --transport http haveibeensquatted https://mcp.haveibeensquatted.com/mcp

Sign in and choose an organization

Section titled “Sign in and choose an organization”

  1. The first time a tool runs, your client opens the Have I Been Squatted sign-in page.

  2. Sign in with your Have I Been Squatted account.

  3. On the consent screen, check the application name and choose the organization to connect. The connection is bound to that organization: switching organizations in the dashboard later does not change it.

  4. Approve the requested scopes. The client can now call the tools your plan and role allow.

To connect a different organization, remove the connection in your client and connect again.

Tools

Section titled “Tools”

The server lists only the tools your organization’s plan includes. A tool your plan includes but your role or scopes do not allow is still listed; the call is refused with the reason.

Each tool’s title is in bold. The Kind column shows how each tool is annotated for clients:

  • read-only: reads data and changes nothing.
  • job: starts a lookup that runs in the background and uses your organization’s lookup capacity. See Background jobs.
  • write: changes your organization’s data. Needs an organization admin.
  • destructive: overwrites or deletes data, or changes your connected security tools.
  • open world: reaches third-party infrastructure or services.

Clients ask you to confirm calls that are not read-only. Tools that open a takedown, delete a rule, remove a domain or dispatch a response also tell the assistant to confirm with you first.

Account and catalog

Section titled “Account and catalog”

Available on every plan.

Tool What it does Scope Kind
whoami Current User. Shows the signed-in user, the connected organization and its plan, your role and the scopes this connection was granted. user:org:read read-only
describe_catalog Describe Query Catalog. Describes one Upsilon namespace for queries and rules: domain (default), email or canary, with fields, types, operators and examples. user:org:read read-only

Lookups

Section titled “Lookups”

Available on every plan. Lookups share your organization’s lookup limits with the dashboard and API.

Tool What it does Scope Kind
analyze Analyze Domain. Analyzes one domain or hostname live: DNS, registration, hosting, HTTP, classification and a verdict profile. depth is core (cached verdict in seconds), fast (default, under a minute) or slow (renders the page and reports what it asks visitors for, such as passwords, one-time codes, wallet secrets or payment data; one to three minutes). lookups:run job, open world
squat Scan Typosquats. Generates typosquat permutations of a registrable domain and checks which are registered or live (DNS, mail, HTTP, classification), ranked by evidence. Typically 5 to 10 minutes, at most 15. lookups:run job, open world
discover Discover Unregistered Lookalikes. Finds unregistered (NXDOMAIN) lookalikes of a registrable domain that could still be registered defensively. Typically 2 to 5 minutes. lookups:run job, open world
ct_search Search Certificate Transparency. Searches public certificate transparency logs for certificate names matching a regular expression and answers immediately. Takes pattern, limit (1 to 100) and since_days (1 to 365). lookups:run read-only, open world
get_job Get Job. Polls a squat, discover or analyze job and pages through its records, ranked by evidence. lookups:run read-only
show_domain Show Domain. Shows one domain from a completed job as an interactive view: screenshot, hosting location on a world map, and every signal. lookups:run read-only
show_domains Show Domains. Shows a completed job’s domains as an interactive table under a map of their hosting countries, with each row expandable to every signal. Up to 100 domains. lookups:run read-only

ct_search patterns match anywhere in a name unless anchored with ^ or $, and should contain a literal run of three or more characters. A result with timed_out means the pattern was too broad, not that nothing matched.

Clients that support MCP Apps, such as Claude, ChatGPT and Codex, render show_domain and show_domains inline. Other clients show a text summary.

Monitoring data and results

Section titled “Monitoring data and results”

Requires a Pro, Business or Enterprise plan.

Tool What it does Scope Kind
query Query Monitoring Data. Searches your organization’s data with an Upsilon predicate over one namespace per call: domain results under your monitored domains (default), Email Intelligence events or Site Canary events. Looks back days (1 to 30, default 7) and returns up to limit records (1 to 100, default 50), newest first. org:read read-only
annotate_result Annotate Result. Tags one domain result as owned, ignored, false-positive or malicious. The tag also becomes the saved disposition for that lookalike under its monitored domain. results:annotate write, destructive
add_result Add Retroactive Results. Adds 1 to 25 completed analyze jobs to a monitored domain’s results, like the dashboard’s retroactive results. Rules and alerts do not evaluate added results. results:write write

query over the email namespace needs the Email Intelligence add-on, and over canary the Site Canaries add-on. A query reads one namespace; relating email events to domain results takes two calls.

Monitored domains

Section titled “Monitored domains”

Requires a Pro, Business or Enterprise plan.

Tool What it does Scope Kind
list_domains List Monitored Domains. Lists monitored domains with labels, detection settings, the next scheduled lookup and the latest lookup, and how many domains you monitor against your limit. org:read read-only
add_domains Add Monitored Domains. Starts monitoring 1 to 25 domains within your domain limit. The first lookup runs within minutes. domains:write write, open world
update_domain Update Monitored Domain. Replaces a domain’s labels, or sets its business context and certificate transparency terms. domains:write write, destructive
remove_domain Remove Monitored Domain. Stops monitoring one domain. Its saved result dispositions and site canaries are deleted, and its past lookups, results and alerts are no longer reachable. Cannot be undone. domains:write write, destructive

Detection rules

Section titled “Detection rules”

Requires a Pro, Business or Enterprise plan. See the rules engine guide.

Tool What it does Scope Kind
list_rules List Rules. Lists your organization’s rules and the global rules it subscribes to, newest first. org:read read-only
get_rule Get Rule. Shows one rule with its expression, sources, scoring, metadata and bound responses. org:read read-only
list_rule_actions List Rule Actions. Lists the responses rules can bind besides the alert, whether each is available and why not, the add-on it needs, and your configured destinations. Destination URLs show only their scheme and host. org:read read-only
validate_rule Validate Rule. Checks whether an expression compiles, which sources it reads and which source add-ons your organization lacks. org:read read-only
create_rule Create Rule. Creates an enabled rule with optional responses, checked like the rule editor. Every match raises an alert and runs the rule’s responses. rules:write write
update_rule Update Rule. Updates one of your organization’s rules. Global rules cannot be edited. rules:write write, destructive
set_rule_enabled Enable or Disable Rule. Enables or disables a rule, or a subscription to a global rule. rules:write write, destructive
delete_rule Delete Rule. Deletes a rule and its responses, or unsubscribes from a global rule. Existing alerts remain. Cannot be undone. rules:write write, destructive

Alerts

Section titled “Alerts”

Requires a Pro, Business or Enterprise plan.

Tool What it does Scope Kind
list_alerts List Alerts. Lists the alerts your rules raised in the last 1 to 365 days (default 30), filtered by status, rule, level or domain, with response deliveries by state. org:read read-only
get_alert Get Alert. Shows one alert: the rule as it fired, the evidence it cites, and each response’s delivery state, provider reference, HTTP status and error code. org:read read-only
set_alert_status Set Alert Status. Sets 1 to 100 alerts to active, resolved, ignored or false-positive for everyone in the organization. alerts:write write, destructive

Alerts that cite email or canary events stay hidden unless your organization has the matching add-on, as in the dashboard.

Responses

Section titled “Responses”

Requires a Pro, Business or Enterprise plan, and the add-on of the response you send. See Connectors.

Tool What it does Scope Kind
dispatch_action Dispatch Response. Sends one response for one domain result now, outside any rule: a notification to Slack, a webhook or a SIEM; a block in Microsoft Defender for Endpoint, Cloudflare Zero Trust or Microsoft 365 Exchange; or a detection in CrowdStrike Falcon or Microsoft Sentinel. Delivery runs in the background. actions:write write, destructive, open world
list_dispatches List Dispatched Responses. Lists responses dispatched by hand in the last 1 to 90 days (default 30), with each one’s delivery state. org:read read-only

A monitored domain and its subdomains are never blocked. Your organization can dispatch at most 20 responses an hour, and repeating the same dispatch within ten minutes returns the first one.

Takedowns

Section titled “Takedowns”

Requires the Takedowns add-on.

Tool What it does Scope Kind
list_takedowns List Takedowns. Lists takedown cases opened in the last 1 to 365 days (default 90), filtered by status, reason or domain. org:read read-only
get_takedown Get Takedown. Shows one case: its timeline, linked alerts and takedowns, artifact metadata, evidence and the current evidence report. org:read read-only
create_takedown Create Takedown. Opens a managed takedown case for one domain result with landing-page captures as evidence. If the domain already has an open case, the result joins it. takedowns:write write
add_takedown_update Add Takedown Update. Adds a note to a case’s timeline and sets its status to review, progress, completed or closed. takedowns:write write, destructive
link_takedown Link to Takedown. Links up to 50 alerts and 50 related cases to a case. Links cannot be removed. takedowns:write write

create_takedown does not contact anyone automatically. The Have I Been Squatted operations team reviews each case and, when it is warranted, reports the domain to its registrar and host.

Background jobs

Section titled “Background jobs”

squat, discover and analyze take longer than clients keep a request open, so each call becomes a job.

  • The call returns at once with a job ID, an expected duration and poll_after_seconds. The assistant tells you the job is running, then polls get_job. analyze at core depth usually finishes within the call.
  • Each call starts a new lookup. An organization runs at most 3 jobs at a time, so poll a running job rather than starting another.
  • A completed job keeps up to 100 records ranked by evidence. Page through them with get_job.
  • Jobs and their results are deleted 24 hours after they are created.
  • Clients that support the MCP tasks extension receive the job as a task instead and poll it with tasks/get.

Limits

Section titled “Limits”
Limit Value
Jobs running at once 3 per organization
Job retention 24 hours
query window 1 to 30 days, default 7
query records 1 to 100 per call, default 50
show_domains 100 domains
add_domains, add_result 25 per call
set_alert_status 100 alerts per call
dispatch_action 20 per organization per hour
Monitored domains Your plan’s domain limit

Requests are also rate limited per client address and per organization.

OAuth scopes

Section titled “OAuth scopes”

Each tool needs one scope. The server’s protected resource metadata (/.well-known/oauth-protected-resource/mcp) lists the scopes it accepts. Clients usually request all of them; a client that lacks a scope for a tool is asked to request it.

Scope Grants Tools
user:org:read Your identity, organization, role and the query catalog whoami, describe_catalog
org:read Read your organization’s monitoring data, domains, rules, alerts, dispatches and takedowns query, list_domains, list_rules, get_rule, list_rule_actions, validate_rule, list_alerts, get_alert, list_dispatches, list_takedowns, get_takedown
lookups:run Run lookups and read their jobs analyze, squat, discover, ct_search, get_job, show_domain, show_domains
results:annotate Tag domain results annotate_result
results:write Add retroactive results add_result
domains:write Add, update and remove monitored domains add_domains, update_domain, remove_domain
rules:write Create, update, enable, disable and delete rules create_rule, update_rule, set_rule_enabled, delete_rule
alerts:write Set alert status set_alert_status
takedowns:write Open, update and link takedown cases create_takedown, add_takedown_update, link_takedown
actions:write Dispatch responses to connected tools dispatch_action

A scope does not replace a role: every tool that writes also needs an organization admin.

Example prompts

Section titled “Example prompts”
  • “Analyze login.example.com and tell me whether it looks like phishing.”
  • “Run a typosquat scan of example.com and show me the live lookalikes on a map.”
  • “Which unregistered lookalikes of example.com should we register defensively?”
  • “Search certificate transparency for new certificates imitating example.com in the last 30 days.”
  • “What new lookalikes of our monitored domains appeared this week?”
  • “Show me active critical alerts and explain why the last one did not reach Splunk.”
  • “Draft a rule that alerts on lookalikes within one edit of example.com, and validate it before creating it.”
  • “Mark the results we own as owned and resolve their alerts.”
  • “Open a takedown for the phishing page on examp1e.com.”

Security

Section titled “Security”
  • Bound to one organization. Tokens are issued for this server only and are bound to the organization chosen at consent. Tool arguments cannot select another organization.
  • Checked on every request. Your membership, role, plan and add-ons are re-checked on every call. If you leave the organization or lose admin, the connection loses that access at once.
  • Changes need an admin and a scope. Tools that change data need an organization admin and their own scope, and clients ask you to confirm them. Review each confirmation, especially for takedowns, deletions and dispatched responses.
  • Untrusted content is data. Domain results, page content, certificate names and email or canary events can be controlled by attackers. The server tells assistants to treat them as data, never as instructions. Views render every value as text and load screenshots only from Have I Been Squatted.
  • Links stay private. Results link to the matching dashboard page, which opens under your own sign-in. Nothing is shared publicly.
  • Audited. Every tool call is recorded with the user, the organization, the connected application and the arguments.

Revoke access

Section titled “Revoke access”

Remove the Have I Been Squatted connector or MCP server in your client to stop it making requests. To revoke a connection on the Have I Been Squatted side, or to turn off changes through MCP for your whole organization, contact support@haveibeensquatted.com.

Your assistant’s provider processes your prompts and responses under its own privacy policy. Have I Been Squatted receives only the tool requests the assistant sends. See the privacy policy.