MCP tools reference¶

Available tools¶

MCP clients interact with the server through tool calls. In a conversational workflow, a prompt like "investigate example.com" or "find domains on this IP address" triggers the right tool automatically. Agents and automated pipelines can also call tools directly with structured parameters.

The server provides specialized tools organized into four categories. Each tool is optimized for specific use cases and returns a different subset of data.

How to read this reference: Each tool description below includes:

Usage examples (in text blocks) — natural language prompts that trigger the tool in conversational clients. Naming a specific tool (like "Use lookup_single to...") is optional but can help direct tool selection.
Input format (in json blocks) — the structured parameters the client sends to the tool. Conversational clients construct these automatically; agents and integrations can build them directly.
Returns — fields included in the tool response.

Tool summary¶

Domain intelligence tools — domain lookups, risk scoring, and pivot searches:

Tool	Input	Returns	Best for
`lookup_single`	Single domain	Full domain profile (risk, WHOIS, DNS, SSL, web, history, tags)	Deep investigation of one domain
`lookup_bulk`	Multiple domains (comma-separated)	Essential fields (risk, dates, tags, popularity)	Quick triage of domain lists
`import_hash`	Iris search hash	Same as `lookup_bulk`	Continuing Iris Investigate web searches
`evaluate`	Pivot parameters	Same as `lookup_bulk`	General connected-domain discovery
`infrastructure`	Pivot parameters	Infrastructure fields (IP, NS, MX, SOA, registrar)	Mapping hosting and DNS infrastructure
`registration`	Pivot parameters	Registration fields (WHOIS contacts, dates, status)	Identifying registrant patterns
`website`	Pivot parameters	Website fields (tracking codes, SSL, redirects, server)	Finding sites with shared web properties

Passive DNS tools — historical DNS lookups and pattern searches:

Tool	Input	Returns	Best for
`pdns_lookup_rrset`	Owner name (domain)	RRsets with rdata, bailiwick, timestamps	Historical DNS records for a domain
`pdns_lookup_rdata_name`	Hostname/domain in rdata	Records pointing to that name	Finding domains sharing DNS infrastructure
`pdns_lookup_rdata_ip`	IP address or CIDR range	Domains that resolved to that IP	IP-based infrastructure mapping
`pdns_flex_search`	Regex or glob pattern	Matching rrnames or rdata values	Large-scale threat hunting with patterns

Domain history tools — tracking changes over time:

Tool	Input	Returns	Best for
`registration_history`	Single domain	Registration change events with before/after states	Ownership and registrar changes
`infrastructure_history`	Single domain	Historical IP, nameserver, and mail server records	Tracking hosting migrations
`website_history`	Single domain	Historical SSL, redirects, server, and tracking codes	Website evolution over time
`registration_history_deep`	Single domain	Full historical WHOIS records	Deep WHOIS history (pre-2022 records)

Understanding pivot tool parameters:

Pivot tools (evaluate, infrastructure, registration, website) accept a search_criteria object containing a primary search (a search_type and value pair) and optional secondary filters like tld, active, or create_date. Conversational clients build this structure automatically from your prompt. Agents and integrations can construct it directly.

For example, asking "find all .com domains hosted on IP 192.0.2.1" produces:

{
  "search_criteria": {
    "primary": {"search_type": "ip", "value": "192.0.2.1"},
    "tld": "com"
  }
}

You can combine multiple filters: "find domains on IP 192.0.2.1 created after January 2026 with a risk score above 70." The client maps these to the appropriate secondary filters.

`lookup_single` - Full domain profile¶

Usage example:

Use lookup_single to investigate suspicious-bank-login.com

Purpose: Retrieve a comprehensive threat intelligence profile for a single domain.

Example use case: Investigating a suspicious domain reported in a phishing incident

Input format:

{
  "domain": "example.com"
}

Returns: Full domain profile including:

Domain risk score and components
Registration data (WHOIS/RDAP)
DNS records (A, MX, NS)
TLS/SSL certificate information
Website metadata and tracking codes
Historical data points
Tags and classifications

Key fields in response:

domain_risk.risk_score: Overall risk assessment (0-100)
active: Whether the domain is currently registered and resolving
create_date: Domain registration date
registrant_contact: Registrant contact details (organization, country, email)
registrant_org: Registrant organization
registrar: Domain registrar name
ip: Current IP addresses with ASN, country, and ISP
name_server: Authoritative nameservers
mx: Mail server records
ssl_info: TLS/SSL certificate details
website_title: Website title tag content
ga4, gtm_codes: Google Analytics 4 and Tag Manager codes
tags: Classification tags
data_updated_timestamp: When the domain data was last refreshed

Note: The server removes fields like ga4, gtm_codes, and tags entirely from the response when no data is available for the queried domain. See Empty and null fields.

`lookup_bulk` - Quick domain assessment¶

Usage example:

Use lookup_bulk to check these domains: suspicious1.com,suspicious2.net,suspicious3.org

Purpose: Rapid risk assessment for multiple domains with essential threat indicators.

Example use case: Checking a batch of domains extracted from email headers

List the domains in any format: "check suspicious1.com, suspicious2.net, and suspicious3.org." The client converts your list into the comma-separated format the tool expects.

Input format:

{
  "domains": "example.com,example.net,example.org"
}

Returns: Essential risk fields for each domain:

domain: Domain name
active: Registration and DNS status
create_date: Registration date
first_seen: First observed by DomainTools
popularity_rank: Relative popularity ranking
domain_risk: Risk score and components
tags: Classification tags (omitted from response when unavailable — see Empty and null fields)

Performance notes:

Optimized for speed with reduced dataset
Accepts up to 100 domains per request
Returns only the most actionable fields

`import_hash` - Resume saved searches¶

Usage example:

Import the domains from this Iris search hash: [paste hash]

Purpose: Import domain lists from searches saved in the Iris Investigate web interface.

Example use case: Continuing an investigation started in the Iris Investigate web interface

How to get a search hash:

Search hashes are generated by the Iris Investigate web interface:

Perform a search in Iris Investigate
Click Search in the top menu
Select Export
Copy the search hash value

Input format:

{
  "search_hash": "U2FsdGVkX1/0ltGMb0qZqYOdhIF..."
}

Returns: Same fields as lookup_bulk (domain, active, create_date, first_seen, popularity_rank, domain_risk, tags)

Note: Only the Iris Investigate web interface generates search hashes. The MCP Server consumes them but doesn't generate them.

Error: An HTTP 400 response with the message "The search_hash parameter appears to be invalid" indicates the hash is malformed or expired. Generate a new hash from the Iris Investigate web interface.

`evaluate` - Find connected domains (general)¶

Usage example:

Use evaluate to find all .com domains hosted on IP 192.0.2.1

Purpose: Discover related domains through shared infrastructure, registration, or web characteristics. For deep investigation of a single domain without pivot parameters, use lookup_single instead.

Example use case: Finding domains on the same IP address

Supported search_type values:

Domain/IP: domains, ip, redirect_domain
DNS: nameserver_host, nameserver_domain, nameserver_ip, mailserver_host, mailserver_domain, mailserver_ip
Registration: registrant, registrant_org, registrar, email, email_domain, email_dns_soa, contact_name, contact_phone, contact_street, iana_id, whois
Historical: historical_email, historical_registrant, historical_free_text
SSL/TLS: ssl_common_name, ssl_issuer_common_name, ssl_org, ssl_subject, ssl_email, ssl_hash, ssl_alt_names, ssl_duration (integer: validity in days)
Web/Tracking: website_title, server_type, adsense, google_analytics, ga4, google_tag_manager, facebook, hotjar, matomo, yandex_metrica, baidu_analytics, statcounter_project, statcounter_security
Tags: tagged_with_any, tagged_with_all
Other: search_hash

Optional secondary filters: tld, active, create_date, expiration_date, first_seen_since, first_seen_within, ip_country_code, risk_score, rank, ssl_not_before, ssl_not_after, not_tagged_with_any, not_tagged_with_all

Input format:

{
  "search_criteria": {
    "primary": {"search_type": "ip", "value": "192.0.2.1"},
    "tld": "com"
  }
}

Returns: Same fields as lookup_bulk (domain, active, create_date, first_seen, popularity_rank, domain_risk, tags)

Additional examples:

Use evaluate to find domains using Google Analytics 4 code G-XXXXXXXXXX

Use evaluate to find domains registered to "Example Corp"

`infrastructure` - Infrastructure-focused pivoting¶

Usage example:

Use infrastructure to find domains using nameserver ns1.suspicious-hosting.com

Purpose: Find domains sharing infrastructure components with detailed DNS and hosting information.

Example use case: Mapping nameserver usage patterns

Supported search_type values and secondary filters: Same as evaluate tool

Input format:

{
  "search_criteria": {
    "primary": {"search_type": "nameserver_domain", "value": "ns.example.com"}
  }
}

Returns: Infrastructure-specific fields:

domain: Domain name
active: Registration and DNS status
first_seen: First observed by DomainTools
ip: Current IP addresses, each with nested asn, country_code, and isp
name_server: Nameserver hostnames
mx: Mail server records
soa_email: DNS SOA email address
registrar: Domain registrar

Difference from evaluate: Returns more detailed infrastructure fields (IP, ASN, ISP, NS, MX records) but omits general metadata like popularity rank and risk scores.

`registration` - Registration-focused pivoting¶

Usage example:

Use registration to find domains registered to email domain example.com

Purpose: Find domains with shared registration characteristics and WHOIS data.

Example use case: Finding domains registered by the same entity

Supported search_type values and secondary filters: Same as evaluate tool

Input format:

{
  "search_criteria": {
    "primary": {"search_type": "registrant_org", "value": "Example Corporation"}
  }
}

Returns: Registration-specific fields:

domain: Domain name
active: Registration and DNS status
first_seen: First observed by DomainTools
create_date: Domain registration date
expiration_date: Domain expiration date
email_domain: Email domain from WHOIS
soa_email: DNS SOA email
additional_whois_email: Other emails in WHOIS
admin_contact: Administrative contact
billing_contact: Billing contact
registrant_org: Registrant organization
technical_contact: Technical contact
registrar: Domain registrar
registrar_status: Domain status codes

Privacy note: WHOIS data respects GDPR and other privacy regulations. Some fields may be redacted based on registry policies.

`website` - Website-focused pivoting¶

Usage example:

Use website to find all domains using Google Analytics 4 code G-XXXXXXXXXX

Purpose: Find domains sharing web technologies, tracking codes, and website characteristics.

Example use case: Finding domains with the same Google Analytics code

Typical workflow: Use lookup_single on a domain to discover its tracking codes, then pivot with this tool using those codes to find related domains.

Additional example:

Use website to find all domains with the same AdSense code as example.com

Supported search_type values and secondary filters: Same as evaluate tool

Input format:

{
  "search_criteria": {
    "primary": {"search_type": "ga4", "value": "G-XXXXXXXXXX"}
  }
}

Returns: Website-specific fields:

domain: Domain name
active: Registration and DNS status
first_seen: First observed by DomainTools
website_response: HTTP response code
redirect: Redirect URL
redirect_domain: Redirect target domain
website_title: Website title tag
server_type: Web server software
ssl_info: SSL certificate details
ssl_email: Email from SSL certificate
adsense: Google AdSense code
google_analytics: Google Analytics (UA) code
ga4: Google Analytics 4 codes
gtm_codes: Google Tag Manager codes
fb_codes: Facebook/Meta tracking codes
hotjar_codes: Hotjar tracking codes
baidu_codes: Baidu Analytics codes
yandex_codes: Yandex Metrica codes
matomo_codes: Matomo tracking codes
statcounter_project_codes: StatCounter project codes
statcounter_security_codes: StatCounter security codes

Tracking code types supported:

Google Analytics (UA and GA4)
Google Tag Manager
Google AdSense
Facebook/Meta Pixel
Hotjar
Baidu Analytics
Yandex Metrica
Matomo
StatCounter

`pdns_lookup_rrset` - Forward DNS lookup¶

Usage example:

Look up all DNS records for example.com using passive DNS

Purpose: Forward lookup of DNS resource record sets (RRsets) by owner name. Returns complete record sets with all rdata values, bailiwick metadata, and observation timestamps.

Example use case: Discovering historical DNS records and subdomains for a domain under investigation

Input format:

{
  "owner_name": "example.com",
  "rrtype": "A"
}

Returns:

rrname: DNS owner name
rrtype: Record type (A, AAAA, CNAME, MX, NS, etc.)
rdata[]: Record data values
bailiwick: DNS bailiwick (zone of authority)
count: Number of times observed
time_first, time_last: First and last observation timestamps
zone_time_first, zone_time_last: Zone file observation timestamps

Optional parameters: rrtype, bailiwick, time_first_before, time_first_after, time_last_before, time_last_after, limit, offset, aggr

Wildcards: Use *.example.com for left-hand wildcards (slower) or www.example.* for right-hand wildcards (faster).

`pdns_lookup_rdata_name` - Inverse name lookup¶

Usage example:

Find all domains whose DNS records point to ns1.example.com

Purpose: Inverse lookup that finds domains whose rdata contains a specific hostname or domain name. Returns individual records rather than full RRsets.

Example use case: Finding domains sharing a nameserver or mail server

Input format:

{
  "name": "ns1.example.com"
}

Returns:

rrname: DNS owner name
rrtype: Record type
rdata: Record data value
count: Number of times observed
time_first, time_last: First and last observation timestamps
zone_time_first, zone_time_last: Zone file observation timestamps (when available)

Wildcards: Use .example.com (dot-prefix) for left-hand wildcards or www.example. (dot-suffix) for right-hand wildcards. Note: this differs from pdns_lookup_rrset, which uses * wildcards.

Optional parameters: rrtype, time_first_before, time_first_after, time_last_before, time_last_after, limit, offset, aggr

`pdns_lookup_rdata_ip` - Inverse IP lookup¶

Usage example:

Find all domains that have ever resolved to IP 192.0.2.1

Purpose: Inverse lookup that finds all domains that have pointed to specific IP addresses or CIDR ranges.

Example use case: Mapping all domains hosted on a suspicious IP address

Input format:

{
  "ip": "192.0.2.1"
}

Returns: Same fields as pdns_lookup_rdata_name

IP formats supported: Single IP (192.0.2.1), CIDR prefix (192.0.2.0/24), or IP range (192.0.2.1-192.0.2.10). Also supports IPv6 addresses.

Optional parameters: time_first_before, time_first_after, time_last_before, time_last_after, limit, offset, aggr

`pdns_flex_search` - Pattern search¶

Usage example:

Search passive DNS for all domains matching the pattern *malware*.com

Purpose: Pattern-based passive DNS search using regex or glob expressions.

Example use case: Large-scale threat hunting for domains matching a suspicious pattern

Input format:

{
  "search_params": {
    "search_type": "rrnames_glob",
    "value": "*malware*.com"
  }
}

Search types: rrnames_regex, rrnames_glob, rdata_regex, rdata_glob

Returns (rrnames search): rrname, rrtype

Returns (rdata search): rdata, rrtype, raw_rdata

Flex search returns minimal metadata for pattern discovery. Use pdns_lookup_rrset or pdns_lookup_rdata_name on individual results to get full temporal data (count, time_first, time_last).

Optional parameters: rrtype, exclude (filter out matches), time_first_before, time_first_after, time_last_before, time_last_after, limit, offset

`registration_history` - Registration changes¶

Usage example:

Show me the registration history for example.com

Purpose: Retrieve a timestamped record of changes to a domain's registration data, including ownership transfers and registrar changes.

Example use case: Tracking when a domain changed hands or switched registrars

Input format:

{
  "domain": "example.com"
}

Returns: The response includes domain, count (total number of changes), and a changes array. Each change event contains:

timestamp: When the change was detected
field: Which field changed
before / after: The field's state before and after the change

Tracked fields: create_date, expiration_date, registrant, registrar, registrar_status, active, admin_contact, billing_contact, registrant_contact, technical_contact.

Data coverage: This tool tracks changes beginning January 1, 2022. For older registration records, use registration_history_deep.

Pagination: Results are paginated with page_size (default 50, max 100) and offset (0-indexed).

`infrastructure_history` - Infrastructure changes¶

Usage example:

Show the historical IP addresses and nameservers for example.com

Purpose: Retrieve a timestamped record of changes to a domain's infrastructure, including IP addresses, nameservers, and mail servers.

Example use case: Tracking hosting migrations and nameserver changes over time

Input format:

{
  "domain": "example.com"
}

Returns: The response includes domain, count (total number of changes), and a changes array. Each change event contains:

timestamp: When the change was detected
field: Which field changed (for example, ip, mx, name_server)
before / after: The field's state before and after the change

Change events use these field values: ip (each entry contains address, asn, country_code, isp), name_server (each entry contains host, ip), mx (each entry contains host, ip, priority).

Data coverage: This tool tracks infrastructure changes from January 1, 2022 onward. Earlier infrastructure data isn't available through the MCP Server.

Pagination: Results are paginated with page_size (default 50, max 100) and offset (0-indexed).

`website_history` - Website changes¶

Usage example:

Show the website history for example.com including past SSL certificates

Purpose: Retrieve a timestamped record of changes to a domain's web presence, including SSL certificates, redirects, server software, and tracking codes.

Example use case: Investigating how a compromised website changed over time

Input format:

{
  "domain": "example.com"
}

Returns: The response includes domain, count (total number of changes), and a changes array. Each change event contains:

timestamp: When the change was detected
field: Which field changed (for example, ssl_info, website_title, server_type)
before / after: The field's state before and after the change

Change events use these field values:

ssl_info: Each entry contains hash, common_name, alt_names, subject, issuer_common_name, not_before, not_after, duration, email
Content: redirect, redirect_domain, screenshot_collected_timestamp, server_type, website_response, website_title
Tracking codes: google_analytics, ga4, google_tag_manager, facebook, hotjar, matomo, yandex_metrica, baidu_analytics, statcounter_project, statcounter_security, adsense

Data coverage: This tool tracks website changes from January 1, 2022 onward. Earlier website data isn't available through the MCP Server.

Pagination: Results are paginated with page_size (default 50, max 100) and offset (0-indexed).

`registration_history_deep` - Deep WHOIS history¶

Usage example:

Show the full WHOIS history for example.com going back to its original registration

Purpose: Retrieve historical WHOIS registration records, including records older than those available from registration_history (which begins at January 2022).

Example use case: Investigating the original registrant of a domain or changes predating 2022

Input format:

{
  "domain": "example.com"
}

Returns: The response includes record_count (total historical records) and a history array. Each record contains:

date: Record timestamp
is_private: Whether WHOIS privacy was active (0 = public, 1 = redacted)
whois: Parsed WHOIS data containing:
- registrant: Registrant name
- registration: Object with created, expires, updated, registrar, statuses
- name_servers: Nameservers at time of record
- record: Raw WHOIS text

Optional parameters:

sort: date_asc or date_desc (default) — controls record ordering
limit: Maximum records per request (1-100, default 100)
offset: Number of records to skip for pagination (0-indexed)
mode: list (default) returns records, count returns only the record count, check_existence returns whether the domain exists in the database
format: Response format — json (default), xml, or html

Example workflows¶

These examples show how to chain tools for multi-step investigations. In a conversational workflow, describe each step and the client selects the tools and carries context forward. Agents can chain these tools programmatically.

Start with a suspicious domain, discover its tracking codes, and pivot to find other domains using the same codes.

Step 1: Use lookup_single to investigate suspicious-domain.com

The response includes tracking codes (ga4, gtm_codes, adsense), SSL certificates, and nameservers. Pivot on a shared identifier:

Step 2: Use website to find all other domains using that same Google Tag Manager code

Step 3: Use lookup_bulk to check the risk scores for those related domains

Tools used: lookup_single → website → lookup_bulk

Map infrastructure from an IP address¶

Identify all domains associated with a suspicious IP address using both domain lookup and passive DNS tools, then triage by risk.

Step 1: Use lookup_single to get the current IP and hosting details for suspicious-domain.com

Step 2: Use pdns_lookup_rdata_ip to find all domains that have ever resolved to that IP address

Step 3: Use infrastructure to find active domains currently hosted on that IP, and show their nameservers and registrar

Step 4: Use lookup_bulk to assess risk scores for the domains you found — focus on any with a risk score above 70

Prioritize high-risk domains. Domains sharing an IP with low risk scores and high popularity ranks are likely co-tenants on shared hosting and can usually be deprioritized.

Tools used: lookup_single → pdns_lookup_rdata_ip + infrastructure → lookup_bulk

Hunt for typosquatting or DGA domains¶

Proactively search for suspicious domains matching a pattern, then triage the results with lookup_bulk.

Step 1: Use pdns_flex_search to find all domains matching the glob pattern *paypa1*.com

Filter the matches for suspicious names, then get full DNS details for the strongest candidates:

Step 2: Use pdns_lookup_rrset to look up the A records for the top suspicious matches

Step 3: Use lookup_bulk to check risk scores and registration dates for those domains

Newly created domains with high risk scores and shared infrastructure are the strongest candidates for typosquatting campaigns.

Tools used: pdns_flex_search → pdns_lookup_rrset → lookup_bulk

Understand results¶

The server returns structured JSON data. In conversational clients, the model interprets these results and presents them in a readable format. This section explains the underlying data structures.

Risk score interpretation¶

See the Domain Risk Score user guide for more information.

Domain risk scores range from 0 (lowest risk) to 100 (highest risk):

Score	Description
100	Blocklisted — known-bad, includes sinkholed domains
90-99	Strong confidence in near-term weaponization
70-89	Default investigation significance threshold
50-69	May require attention depending on security posture
1-49	Very little evidence of malicious intent
0	Zero-listed — no evidence of malicious registration

Risk scores include components that explain the assessment:

proximity: Observed closeness to known-malicious infrastructure
threat_profile_phishing: Phishing-specific ML classifier
threat_profile_malware: Malware-specific ML classifier
threat_profile_spam: Spam-specific ML classifier

Pivot counts in `lookup_single`¶

lookup_single returns fields in {value, count} format, where count indicates how many other domains share that exact value (excludes the queried domain):

{
  "value": "192.0.2.1",
  "count": 42
}

Use pivot counts to guide your next investigation step:

Low count (1-50): Strong signal — a rare, high-confidence connection worth pivoting on
High count (500+): Common value (shared hosting, popular provider) — usually not worth pivoting on
Count of 1: Unique to the queried domain

All other domain intelligence tools (lookup_bulk, import_hash, evaluate, infrastructure, registration, website) return flattened values with pivot counts removed to keep responses compact.

Empty and null fields¶

The server removes fields entirely from a response when they are empty or null at query time. This reduces token usage and keeps responses focused on available data.

If a field documented in this reference doesn't appear in a response, it means no data was available for that field — not that the tool doesn't support it. For example:

A domain without Google Analytics won't include ga4 in the response.
A domain without classification data won't include tags.
Privacy-protected WHOIS may omit registrant contact fields.
Inactive domains may lack current DNS records.

MCP tools reference¶

Available tools¶

Tool summary¶

lookup_single - Full domain profile¶

lookup_bulk - Quick domain assessment¶

import_hash - Resume saved searches¶

evaluate - Find connected domains (general)¶

infrastructure - Infrastructure-focused pivoting¶

registration - Registration-focused pivoting¶

website - Website-focused pivoting¶

pdns_lookup_rrset - Forward DNS lookup¶

pdns_lookup_rdata_name - Inverse name lookup¶

pdns_lookup_rdata_ip - Inverse IP lookup¶

pdns_flex_search - Pattern search¶

registration_history - Registration changes¶

infrastructure_history - Infrastructure changes¶

website_history - Website changes¶

registration_history_deep - Deep WHOIS history¶

Example workflows¶

Investigate a domain and find related infrastructure¶

Map infrastructure from an IP address¶

Hunt for typosquatting or DGA domains¶

Understand results¶

Risk score interpretation¶

Pivot counts in lookup_single¶

Empty and null fields¶

`lookup_single` - Full domain profile¶

`lookup_bulk` - Quick domain assessment¶

`import_hash` - Resume saved searches¶

`evaluate` - Find connected domains (general)¶

`infrastructure` - Infrastructure-focused pivoting¶

`registration` - Registration-focused pivoting¶

`website` - Website-focused pivoting¶

`pdns_lookup_rrset` - Forward DNS lookup¶

`pdns_lookup_rdata_name` - Inverse name lookup¶

`pdns_lookup_rdata_ip` - Inverse IP lookup¶

`pdns_flex_search` - Pattern search¶

`registration_history` - Registration changes¶

`infrastructure_history` - Infrastructure changes¶

`website_history` - Website changes¶

`registration_history_deep` - Deep WHOIS history¶

Pivot counts in `lookup_single`¶