Tools Reference

This comprehensive reference covers all 35 tools available in the WhoisXML API MCP Server.

Overview

The WhoisXML API MCP Server provides 27 single-input API tools and 6 bulk variants (plus 2 polling helpers) for querying various types of domain, IP, and DNS information and the account's own credits (account_balance), plus a built-in tool_search utility for dynamic tool discovery. Each API tool is designed to interact with specific WhoisXMLAPI endpoints and provides structured data responses.

The hosted endpoint (mcp-hosted.whoisxmlapi.com) serves the 35 API tools; tool_search is stdio-only, enabled by the --defer-loading flag.

Tools List

1. whois - Domain WHOIS information
2. categorization - Domain categorization
3. email_verification - Email verification
4. reverse_ip - Reverse IP lookup
5. reverse_mx - Reverse MX lookup
6. reverse_ns - Reverse NS lookup
7. reverse_dns - Reverse DNS lookup
8. reverse_whois - Reverse WHOIS lookup
9. reverse_whois_advanced - Advanced Reverse WHOIS lookup
10. registrant_alert - Registrant-based domain monitoring
11. brand_alert - Brand-term domain detection
12. disposable_email_check - Disposable email detection
13. whois_history - WHOIS history
14. subdomain_lookup - Subdomain lookup
15. domain_and_subdomain_discovery - Domain and subdomain discovery
16. dns_lookup - DNS lookup
17. dns_history - DNS history
18. ipgeolocation - IP geolocation
19. ip_netblocks - IP netblocks
20. ssl_certificates - SSL certificates
21. threat_intelligence - Threat intelligence
22. domain_info - Domain info
23. typosquatting - Typosquatting group detection (Bulk Registration Risk API)
24. domain_reputation - Domain reputation scoring
25. website_screenshot - Website screenshot capture
26. vpn_proxy_detection - VPN, proxy and Tor detection for an IP
27. account_balance - Credits left on each product (spends no credits)
28. tool_search - Dynamic tool discovery (enabled with --defer-loading)

Bulk tools

29. bulk_whois - Bulk WHOIS lookup (up to 10,000 domains)
30. bulk_dns_lookup - Bulk DNS lookup (up to 200 domains)
31. bulk_ip_geolocation - Bulk IP geolocation (up to 200 IPs)
32. bulk_email_verification - Bulk email verification (up to 10,000 emails)
33. bulk_subdomain_lookup - Bulk subdomain lookup (up to 200 domains)
34. bulk_vpn_proxy_detection - Bulk VPN, proxy and Tor detection (up to 100 IPs)
35. bulk_job_status - Poll progress of a native bulk job
36. bulk_job_results - Fetch results of a completed native bulk job

What each tool costs

Each WhoisXML API product has its own credit balance, and a tool spends only the balance of its product; account_balance shows what each balance has left. "Up to" is the most one call can cost. A call estimated at more than the spend cap runs only with confirm: true.

whois

Description: Get WHOIS information for a domain including registration dates, status, nameservers, and contact info.

Arguments

• domain (string, required) - Domain name to query
• query_type (string, optional) - Query type: "auto", "whois", or "rdap". "rdap" is only supported in domain queries but might not be available for all domains. "auto" will always choose correctly Default: "auto" Allowed values: "auto", "whois", "rdap"
• prefer_refresh_even_if_incomplete (boolean, optional) - If true, provides most up-to-date but potentially incomplete data
• force_refresh (boolean, optional) - If true, forces hard refresh. Costs 5 API calls
• include_domain_availability (boolean, optional) - If true, includes domain availability status
• include_ip_for_domain_queried (boolean, optional) - If true, includes hosting IP address for the domain
• get_host_ip_whois_on_no_domain_data (boolean, optional) - If true, returns host IP WHOIS when domain WHOIS is unavailable
• get_registrar_proxy_data (boolean, optional) - If true, includes registrar WHOIS proxy info in "privateWhoisProxy"
• fetch_whois_from_registry_only (boolean, optional) - If true, returns only registry WHOIS data, not registrar data
• remove_raw_text (boolean, optional) - If true, removes raw text from WHOIS output
• parse_registry_raw_text (boolean, optional) - If true, provides parsed format for registry information
• parse_registrar_raw_text (boolean, optional) - If true, provides parsed format for registrar information

categorization

Description: Classify a domain into IAB Content Taxonomy v3.1 content categories (Website Categorization v4).

Arguments

• domain (string, required) - Domain name to categorize (e.g., 'example.com')
• url (string, optional) - Full URL to classify (optional). Defaults upstream to https://{domain}; set it to categorize a specific page rather than the domain root

Response

Returns 1-3 ranked categories plus a primary_category shortcut. Each category carries a string ID (e.g. "IAB-596"), a hierarchical path ("Shopping > Online Marketplace") with tier1..tier4 levels, and a confidence score. Response metadata: taxonomy_version, credits_charged, latency_ms, model, an abstain object (flags parked/dead/thin sites with no real business purpose), a source object (is_historical_fallback marks results served from historical data when the live crawl was blocked), and error.

Compared to the legacy v3 backend, the response no longer includes ASN data (as), createdDate, or websiteResponded — use ip_netblocks / whois for infrastructure and registration facts.

email_verification

Description: Verify if an email address is legitimate. Checks syntax, SMTP, DNS, free/disposable status, and catch-all configuration.

Arguments

• email (string, required) - Email address to verify
• validate_using_dns (boolean, optional) - Validate using DNS records Default: true
• validate_using_smtp (boolean, optional) - Validate using SMTP Default: true
• check_if_email_is_catch_all (boolean, optional) - Check if email is catch-all Default: true
• check_if_email_is_free (boolean, optional) - Check if email is free Default: true
• check_if_email_is_disposable (boolean, optional) - Check if email is disposable Default: true

reverse_ip

Description: Find all domains sharing the same IP address and connection dates.

Arguments

• ipv4_address (string, required) - IPv4 address to search
• from_needle (string, optional) - Pagination needle from previous response. Max 300 records per page
• include_additional_checks (boolean, optional) - If true, performs additional DNS checks (wildcard, domain activeness). Slower but more detailed
• preview (boolean, optional) - If true, returns just the domain names without additional information Default: false

reverse_mx

Description: Find all services sharing the same MX server and connection dates.

Arguments

• mx_hostname (string, required) - MX hostname to search
• from_needle (string, optional) - Pagination needle from previous response. Max 300 records per page
• include_additional_checks (boolean, optional) - If true, performs wildcard and domain activeness checks. Extra cost
• preview (boolean, optional) - If true, returns just the domain names without additional information Default: false

reverse_ns

Description: Find all services sharing the same NS nameserver and connection dates.

Arguments

• ns_hostname (string, required) - NS nameserver hostname to search
• from_needle (string, optional) - Pagination needle from previous response. Max 300 records per page
• include_additional_checks (boolean, optional) - If true, performs wildcard and domain activeness checks. Extra cost
• preview (boolean, optional) - If true, returns just the domain names without additional information Default: false

reverse_dns

Description: Find DNS records matching search criteria. Returns domains and DNS record values. Must use wildcards in the "term" field for partial matches otherwise the search will be exact.

Arguments

• record_type (string, required) - DNS record type: "soa", "txt", or "cname" Allowed values: "soa", "txt", "cname", "SOA", "TXT", "CNAME"
• terms (array of objects, required) - Search terms array defining what to search for in DNS records (combined with AND logic). Must use wildcards for partial matches otherwise the search will be exact
  • field (string, required) - Field to search: "domain" or "value" Allowed values: "domain", "value"
  • term (string, required) - Search keyword. Supports wildcards
  • exclude (boolean, optional) - If true, excludes matching records from results Default: false
• limit (number, optional) - Maximum records to return. Recommended to start with 10 and increase if needed. Max: 1000 Default: 10 Range: 1-1000
• include_additional_checks (boolean, optional) - If true, performs wildcard and domain activeness checks. Extra cost Default: false
• preview (boolean, optional) - If true, returns just the domain names without additional information Default: false

reverse_whois

Description: Find domains containing specific search terms in their whois records.

Arguments

• included_search_terms (string, required) - Comma-separated search terms to include (combined with AND logic). Max 4 items. Case insensitive
• excluded_search_terms (string, optional) - Comma-separated search terms to exclude. Max 4 items. Case insensitive
• search_type (string, optional) - Search type: "current" or "historic". "current" searches current records, "historic" searches all records
• count_only (boolean, optional) - If true, returns only count (no credit usage). If false, returns domain list Default: true
• punycode (boolean, optional) - If true, encodes domain names to Punycode
• include_audit_dates (boolean, optional) - If true, includes domain list and last audit date Default: false
• created_date_from (string, optional) - Search domains created after this date. Format: YYYY-MM-DD
• created_date_to (string, optional) - Search domains created before this date. Format: YYYY-MM-DD
• updated_date_from (string, optional) - Search domains updated after this date. Format: YYYY-MM-DD
• updated_date_to (string, optional) - Search domains updated before this date. Format: YYYY-MM-DD
• search_after (string, optional) - Pagination needle from previous page's "nextPageSearchAfter" value

reverse_whois_advanced

Description: Find domains using advanced field-specific search on WHOIS records. Each search term targets a specific WHOIS field with optional exact match and exclude flags. Up to 4 search terms combined with AND logic.

Arguments

• search_terms (array of objects, required) - Field-specific WHOIS search term objects (max 4), combined with AND. Each object has "field" (required) and "term" (required), plus optional "exclude" and "exact_match" booleans. A JSON-encoded string of the same array is also accepted for backward compatibility
  • field (string, required) - WHOIS field to search, e.g. DomainName, RegistrarName, NameServers, Email, RegistrantContact.Organization Allowed values: "DomainName", "RegistrarName", "NameServers", "Email", "WhoisServer", "Status", "RegistrantContact.City", "RegistrantContact.Country", "RegistrantContact.Email", "RegistrantContact.Fax", "RegistrantContact.FaxExtension", "RegistrantContact.Name", "RegistrantContact.Organization", "RegistrantContact.PostalCode", "RegistrantContact.State", "RegistrantContact.StreetAddress", "RegistrantContact.Telephone", "RegistrantContact.TelephoneExtension", "AdminContact.City", "AdminContact.Country", "AdminContact.Email", "AdminContact.Fax", "AdminContact.FaxExtension", "AdminContact.Name", "AdminContact.Organization", "AdminContact.PostalCode", "AdminContact.State", "AdminContact.StreetAddress", "AdminContact.Telephone", "AdminContact.TelephoneExtension", "BillingContact.City", "BillingContact.Country", "BillingContact.Email", "BillingContact.Fax", "BillingContact.FaxExtension", "BillingContact.Name", "BillingContact.Organization", "BillingContact.PostalCode", "BillingContact.State", "BillingContact.StreetAddress", "BillingContact.Telephone", "BillingContact.TelephoneExtension", "TechContact.City", "TechContact.Country", "TechContact.Email", "TechContact.Fax", "TechContact.FaxExtension", "TechContact.Name", "TechContact.Organization", "TechContact.PostalCode", "TechContact.State", "TechContact.StreetAddress", "TechContact.Telephone", "TechContact.TelephoneExtension"
  • term (string, required) - Search string. Case insensitive, supports wildcards
  • exact_match (boolean, optional) - If true, exact field match instead of substring Default: false
  • exclude (boolean, optional) - If true, exclude matching records from results Default: false
• search_type (string, optional) - Search type: "current" or "historic". "current" searches current records, "historic" searches all records
• count_only (boolean, optional) - If true, returns only count (no credit usage). If false, returns domain list Default: true
• punycode (boolean, optional) - If true, encodes domain names to Punycode
• include_audit_dates (boolean, optional) - If true, includes domain list and last audit date Default: false
• created_date_from (string, optional) - Search domains created after this date. Format: YYYY-MM-DD
• created_date_to (string, optional) - Search domains created before this date. Format: YYYY-MM-DD
• updated_date_from (string, optional) - Search domains updated after this date. Format: YYYY-MM-DD
• updated_date_to (string, optional) - Search domains updated before this date. Format: YYYY-MM-DD
• search_after (string, optional) - Pagination needle from previous page's "nextPageSearchAfter" value
• expired_date_from (string, optional) - Search domains that expired after this date. Format: YYYY-MM-DD
• expired_date_to (string, optional) - Search domains that expired before this date. Format: YYYY-MM-DD

Example

Search for domains registered by "Airbnb, Inc." outside the United States:

{
  "search_terms": "[{\"field\":\"RegistrantContact.Organization\",\"term\":\"Airbnb, Inc.\",\"exact_match\":true},{\"field\":\"RegistrantContact.Country\",\"term\":\"UNITED STATES\",\"exclude\":true}]"
}

registrant_alert

Description: Find newly added, dropped, or updated domains whose WHOIS records match search terms in registrant contact fields (email, name, organisation, etc.). Use this for brand-impersonation monitoring and threat-actor infrastructure tracking. Do NOT use this for general WHOIS-text matching (use reverse_whois) or for domain-name string matching.

Arguments

• included_search_terms (string, required) - Comma-separated terms to include (AND logic). Max 4 items. Case insensitive. Wildcards * supported
• excluded_search_terms (string, optional) - Comma-separated terms to exclude. Max 4 items
• date (string, optional) - Date to query in YYYY-MM-DD format. When omitted, the upstream API uses its own default (typically yesterday)
• mode (string, required) - 'preview' returns count only (no credits used). 'purchase' returns the full domain list Allowed values: "preview", "purchase"
• punycode (boolean, optional) - If true, encodes domain names to Punycode
• with_typos (boolean, optional) - If true, includes typo variations of search terms

brand_alert

Description: Find newly added, dropped, or updated domains whose names contain specified brand terms. Use this for typosquat detection, lookalike-domain detection, and brand-protection workflows. Do NOT use this for matching against WHOIS contact fields (use registrant_alert) or for general WHOIS-text matching (use reverse_whois). Set with_typos=true to automatically expand brand terms with common typo variants.

Arguments

• included_search_terms (string, required) - Comma-separated brand terms to include (AND logic). Max 4 items. Case insensitive. Wildcards * supported
• excluded_search_terms (string, optional) - Comma-separated terms to exclude. Max 4 items
• date (string, optional) - Date to query in YYYY-MM-DD format. When omitted, the upstream API uses its own default (typically yesterday)
• mode (string, required) - 'preview' returns count only (no credits used). 'purchase' returns the full domain list Allowed values: "preview", "purchase"
• punycode (boolean, optional) - If true, encodes domain names to Punycode
• with_typos (boolean, optional) - If true, includes typo variations of brand terms (transposed letters, homoglyphs, missing chars, etc.)
• confirm (boolean, optional) - Pass true to run a call estimated at over 100 credits, once the user has agreed to that cost

disposable_email_check

Description: Check whether an email address belongs to a disposable or temporary provider (e.g., mailinator, 10minutemail, guerrillamail). Returns a boolean verdict and the domain extracted from the address. Use this for lead-gen hygiene, signup-fraud filtering, or free-trial abuse detection when you only need the disposable verdict. Do NOT use this for full deliverability or mailbox-reachability checks — use email_verification instead.

Arguments

• email (string, required) - Email address to check (e.g., user@mailinator.com)

Response

Returns a slim verdict object: email, isDisposable (boolean), domain (extracted from the address), and checkedAt (RFC 3339 UTC timestamp).

whois_history

Description: Get historical WHOIS records for a domain including past nameservers, contacts, and registrar info. By default it returns only the number of records, for 1 credit instead of 50; set preview_mode to false to get the records. Supports pagination for large result sets.

Arguments

• domain_name (string, required) - Domain name to search
• limit (number, optional) - Number of records to return (1-100, default 100) Default: 100
• next_page_token (string, optional) - IMPORTANT: To fetch the next page, copy the "next_page_token" value from the previous response and pass it here. Do not use "search_after" or any other parameter name - only "next_page_token" is accepted
• preview_mode (boolean, optional) - If true (the default), returns only the number of records, for 1 credit instead of 50. Set to false to return the records Default: true
• skip_live_whois_records (boolean, optional) - If true, excludes most recent WHOIS record. Set to true for faster responses; leave false to include it Default: false
• since_date (string, optional) - Return results from this date onwards. Format: YYYY-MM-DD
• created_date_from (string, optional) - Search domains created after this date. Format: YYYY-MM-DD
• created_date_to (string, optional) - Search domains created before this date. Format: YYYY-MM-DD
• updated_date_from (string, optional) - Search domains updated after this date. Format: YYYY-MM-DD
• updated_date_to (string, optional) - Search domains updated before this date. Format: YYYY-MM-DD
• expired_date_from (string, optional) - Search domains expired after this date. Format: YYYY-MM-DD
• expired_date_to (string, optional) - Search domains expired before this date. Format: YYYY-MM-DD

Pagination

Responses include a pagination object with:

• total_count - Total number of records available
• page_number - Current page number (1-indexed)
• limit - Number of records in current page
• has_more - Whether more pages are available
• next_page_token - Token to use for the next page (only present if has_more is true). Pass this value as the next_page_token parameter to fetch the next page

A preview (the default) returns total_count with no records, so it never has a next page. Only the records (preview_mode: false) come with a next_page_token, and a call that passes one gets the next page of records whether or not it repeats preview_mode: false.

subdomain_lookup

Description: Find all subdomains for a domain with first and last seen timestamps. Supports pagination for large result sets.

Arguments

• domain_name (string, required) - Domain name to lookup subdomains for
• limit (number, optional) - Number of results to return (1-500, default 500). Ignored when "next_page_token" is supplied: a continuation keeps the page size the walk started with, so change it only on the first call Default: 500
• next_page_token (string, optional) - IMPORTANT: To fetch the next page, copy the "next_page_token" value from the previous response and pass it here. Do not use "search_after" or any other parameter name - only "next_page_token" is accepted

Pagination

Responses include a pagination object with:

• total_count - Number of subdomains fetched so far, not the size of the whole result set. The upstream API deliberately offers no total (computing one costs roughly 3x per request), so the only way to learn the size of a result set is to page to the end
• page_number - Current page number (1-indexed), counting up across upstream page boundaries
• limit - Number of subdomains in current page
• has_more - Whether more pages are available. True whenever a next_page_token is present, including when the next page comes from a further upstream request rather than from rows already fetched
• next_page_token - Token to use for the next page (only present if has_more is true). Pass this value as the next_page_token parameter to fetch the next page

The response also carries:

• truncated_at_upstream_cap - Whether the result set may continue beyond what this response contains. Derived from the upstream API's own continuation cursor, so it is exact rather than inferred from a row count: a complete answer of exactly 10000 records is not flagged. It is also set when the response did not let the server prove completeness at all (no cursor, or no readable record list) — in that case no next_page_token is offered, so narrow the query rather than repeating the call

Following next_page_token walks the entire result set, including past the upstream API's cap of 10000 records per request. Each call makes at most one upstream request, so paging deeper is an explicit choice: a Subdomains Lookup request costs 10 Domain Research Suite credits.

domain_and_subdomain_discovery

Description: Find domains and subdomains matching search terms. Must use wildcards for partial matches otherwise the search will be exact.

Arguments

• domain_search_terms (string, optional) - Comma-separated domain search terms (combined with AND logic). Max 4 items. Case insensitive. Must use wildcards for partial matches otherwise the search will be exact
• domain_search_terms_exclude (string, optional) - Comma-separated domain search terms to exclude. Max 4 items. Case insensitive
• subdomains_search_terms (string, optional) - Comma-separated subdomain search terms (combined with AND logic). Max 4 items. Case insensitive
• subdomains_search_terms_exclude (string, optional) - Comma-separated subdomain search terms to exclude. Max 4 items. Case insensitive
• since (string, optional) - Search domains/subdomains discovered since this date. Format: YYYY-MM-DD
• next_page_token (string, optional) - IMPORTANT: To fetch the next page, copy the "next_page_token" value from the previous response and pass it here, with every other parameter unchanged. Do not use "search_after" or any other parameter name - only "next_page_token" is accepted

Pagination

A response returns one page of at most 10000 names and carries:

• domainsCount - The size of this page, not a total. The upstream API offers no total count
• truncated_at_upstream_cap - Whether the result set continues beyond this page. Derived from the upstream's own continuation cursor, so a complete answer of exactly 10000 names is not flagged
• next_page_token - Present only when the walk can continue. Pass it back, with every other argument unchanged, to fetch the next page

Keep calling while truncated_at_upstream_cap is true and a next_page_token is present. If the flag is true but no token is present, the result set may be incomplete and cannot be continued — narrow the search terms or slice by since instead of repeating the call. Each call makes at most one upstream request, costing 1 Domain Research Suite credit for a domains-only search, 10 for subdomains, 11 for both.

dns_lookup

Description: Perform DNS queries for a domain (A, NS, SOA, MX, etc.).

Arguments

• domain_name (string, required) - Domain name to query
• query_type (string, optional) - Comma-separated DNS query types (A, MX, NS, SOA, etc.) or "all" Default: "A"

dns_history

Description: Get historical DNS records for a domain (forward) or find domains associated with an IP (reverse).

Arguments

• search_type (string, required) - Search type: "forward" or "reverse" Allowed values: "forward", "reverse"
• record_type (string, required) - DNS record type: "a" or "aaaa". Case insensitive Allowed values: "a", "A", "aaaa", "AAAA"
• domain_name (string, optional) - Required if "forward" search type. Domain name to search
• ip_address (string, optional) - Required if "reverse" search type. IP address to search. IPv4 returns A records, IPv6 returns AAAA records
• limit (number, required) - Maximum records to return. Range: 1-1000. Recommended: 50

ipgeolocation

Description: Get location data for IP addresses, domains, or email addresses. Uses caller's IP if no address provided.

Arguments

• ip_address (string, optional) - IPv4 or IPv6 address. Cannot be used with domain_name or email_address
• domain_name (string, optional) - Domain address. Cannot be used with ip_address or email_address
• email_address (string, optional) - Email address. Cannot be used with ip_address or domain_name
• reverse_ip (boolean, optional) - If true, returns 5 domains associated with the IP address

Note: Only one of ip_address, domain_name, or email_address can be provided. If none are provided, the caller's IP address will be used.

ip_netblocks

Description: Get IP netblock information including IP ranges, ASN, and organization data.

Arguments

• ip_address (string, optional) - IPv4 or IPv6 address to search
• organizations (string, optional) - Comma-separated organization search terms
• asn (string, optional) - ASN number to search
• netmask_value (number, optional) - Netmask value: 0-32 for IPv4, 0-128 for IPv6
• limit (number, optional) - Maximum records per page. Max: 1000 Default: 100
• from_needle (string, optional) - Pagination needle from previous page's "inetnum" response

Note: At least one of ip_address, organizations, or asn must be provided.

ssl_certificates

Description: Check TLS certificate chain for a domain to analyze certificate validity, expiration, and chain structure

Arguments

• domain (string, required) - The domain name to check TLS certificate for (e.g., example.com)
• include_chain (boolean, optional) - Whether to include the full certificate chain in the response; defaults to false Default: false
• use_fresh_data (boolean, optional) - Whether to get fresh data instead of cached results; defaults to false Default: false

threat_intelligence

Description: Check if IoCs (domains, URLs, IPs, CIDRs, hashes) are associated with malicious activity.

Arguments

• search_term (string, required) - IoC to check: domain, URL, IP, CIDR, or hash. Supports wildcards for domains, URLs, IPs
• limit (number, optional) - Maximum records per page. Max: 10,000. Every 100 records = 1 credit

domain_info

Description: Get comprehensive domain information including registration details, DNS records, and domain availability.

Arguments

• domain_name (string, required) - Domain name to query (e.g., example.com)

typosquatting

Description: Check whether a domain is part of a known typosquatting group, or expand all domains across all groups the queried domain belongs to. It calls WhoisXML API's Bulk Registration Risk API, formerly the Typosquatting API, and checks one domain per call. Use mode="probe" for a fast triage check (returns inGroup boolean + groupId). Use mode="group" for the heavy follow-up that returns every domain across all groups containing this domain — useful for understanding the full lookalike infrastructure.

Arguments

• domain (string, required) - Domain to check (e.g. "gogle.com")
• mode (string, optional) - Response shape: "probe" for boolean + groupId only (fast); "group" for full list of domains across all groups (heavier, more credits) Default: "probe" Allowed values: "probe", "group"

Note: a "probe" call costs 1 credit and a "group" call costs 5.

Example invocation

{
  "tool": "typosquatting",
  "arguments": {
    "domain": "paypal.com",
    "mode": "probe"
  }
}

Example response (probe mode)

{
  "whoisxmlapi_response": {
    "domain": "paypal.com",
    "inGroup": true,
    "groupId": "group-12345"
  }
}

Example response (group mode)

{
  "whoisxmlapi_response": {
    "domain": "paypal.com",
    "inGroup": true,
    "groupId": "group-12345",
    "groups": [
      {
        "id": "group-12345",
        "domains": [
          { "domain": "paypal.com" },
          { "domain": "paypai.com" },
          { "domain": "paypa1.com" }
        ]
      }
    ]
  }
}

Upstream API docs: https://bulk-registration-risk.whoisxmlapi.com/api/documentation/making-requests

domain_reputation

Description: Score a single domain's trustworthiness on a 0–100 scale by running live infrastructure and configuration checks (certificate validity, mail and name-server setup, malware-database and blackhole lookups, domain age, and more) and return the contributing test results with human-readable warnings. Use this to triage whether a flagged or unfamiliar domain is actually dangerous — for example after typosquatting or brand_alert surfaces a lookalike. Do NOT use it to look up a known-bad verdict from curated threat feeds (use threat_intelligence), to learn what a site claims to be (use categorization), or to fetch raw registration or zone records (those have their own dedicated lookup tools).

Arguments

• domain_name (string, required) - Domain name to score (e.g., example.com). An IPv4 address is also accepted upstream
• mode (string, optional) - Depth of analysis. "fast" runs a select subset of checks (registration status, malware-database check, certificate validity) — cheaper, 1 credit. "full" runs every check (adds mail/name-server/SOA configuration, blackhole, certificate-vulnerability checks, and more) for a more complete score — heavier, 3 credits. Note the score is mode-dependent: "full" surfaces more warnings and so typically returns a LOWER score than "fast" for the same domain Default: "fast" Allowed values: "fast", "full"

website_screenshot

Description: Capture a screenshot of a web page for a URL and return it as a native image content block, plus a small JSON summary with its MIME type, decoded byte size and chosen type. Choose the output format with the type parameter: "png" (default) or "jpg" for raster images, or "pdf" to render the page as a PDF. Optionally set the viewport width and height in pixels, and enable full-page capture to grab the entire scrollable page instead of just the visible viewport. The image data is in the image block only, so a consumer can embed or save it without a second request. Use this to obtain visual evidence of how a site actually looks — for example to document a suspicious, phishing, or typosquatting page surfaced by another tool. Do NOT use it to read a page's text, fetch DNS or WHOIS records, or classify the site, since those have their own tools.

Arguments

• url (string, required) - The fully-qualified URL of the page to capture (e.g., https://example.com)
• type (string, optional) - Output format of the screenshot: "png" (default) or "jpg" for raster images, or "pdf" for a PDF rendering Default: "png" Allowed values: "png", "jpg", "pdf"
• width (number, optional) - Viewport width in pixels. Optional; the API uses a default when omitted
• height (number, optional) - Viewport height in pixels. Optional; the API uses a default when omitted
• full_page (boolean, optional) - If true, capture the full scrollable page rather than just the viewport

Note: The server refuses to capture URLs that resolve to internal or private address space (loopback, private ranges, link-local, CGNAT) as an SSRF guard.

vpn_proxy_detection

Description: Check whether one IP address belongs to a known VPN, proxy (including residential and open proxies), Tor exit, relay, hosting or CDN network, using the WhoisXML VPN & Proxy Detection API. Every plan returns classification (for example vpn, proxy, tor, hosting, cdn or unknown), risk_score (0-100), boolean is_* flags, the ASN and its abuse score, and reasons codes explaining the verdict. Other fields depend on the plan and read null on lower plans: provider and the registered netblock owner need Starter or higher; confidence, first_seen / last_seen and residential-proxy network names need Pro or higher. A residential-proxy network is named only where the exit has been attributed to it. Each successful lookup consumes 1 VPN & Proxy Detection API credit.

Arguments

• ip_address (string, required) - IP address to classify (e.g., 185.220.101.1). IPv4 recommended; see the tool description for IPv6

Notes:

• Detection data is IPv4-first. IPv6 addresses are accepted, but most currently return classification: "unknown".
• Private and other reserved addresses (RFC 1918, loopback, multicast, link-local, TEST-NET) are rejected with an invalid_ip_reserved error and are not charged. Carrier-grade NAT space (CGNAT, RFC 6598, 100.64.0.0/10) is not rejected: it is looked up and charged like any other address.
• Some response fields depend on your VPN & Proxy Detection plan. Those keys stay present but read null or false below the plan that unlocks them, so check your plan rather than field presence.

account_balance

Description: Show how many credits the account has left on each WhoisXML API product, and which of these tools spend each product's credits. The call itself spends no credits. Use it before a large or bulk job, or after a call fails for lack of credits.

Arguments

This tool takes no arguments.

Response

Returns products, one entry per product on the account, sorted by product_id:

• product_id - WhoisXML's product ID
• product - Product name, for example WHOIS API
• credits - Credits left; absent when the product has no credit limit
• unlimited - true when the product has no credit limit
• tools - The tools that spend the product's credits, when there are any. A server started with --disabled-tools may not serve all of them

The response lists credits only: no prices, plans or billing details.

tool_search

Description: Search for available tools by keyword. Uses BM25 ranking to find the most relevant tools based on their names, descriptions, and parameters. This tool is automatically enabled when the server is started with --defer-loading and does not consume API credits.

Arguments

• query (string, required) - Search query to match against tool names, titles, and descriptions
• max_results (number, optional) - Maximum number of results to return. Defaults to 5

Response

Returns a JSON object with:

• query - The original search query
• results - Array of matching tools, each containing:
  • name - Tool name
  • description - Tool description
  • parameters - Array of parameter definitions with name, description, type, and required status
• total_available_tools - Total number of tools registered on the server

Deferred Loading

When the server is started with --defer-loading, all API tools are marked with defer_loading: true. Compatible MCP clients will only load tool_search into context initially, and use it to discover other tools on demand. See Configuration for details.

Bulk Tools

The server exposes 6 bulk variants and 2 polling helpers. All bulk tools return a uniform envelope:

{
  "whoisxmlapi_response": {
    "status": "completed" | "running" | "error",
    "job_id": "<opaque>",
    "total": N,
    "succeeded": N,
    "failed": N,
    "results": [
      { "input": "...", "ok": true, "data": { /* upstream record */ } },
      { "input": "...", "ok": false, "error": { "code": "...", "message": "..." } }
    ]
  }
}

Sync vs async: the server waits up to 20 seconds before returning. If a native bulk job is still in progress, it returns status: "running" and an opaque job_id. Use bulk_job_status to check progress and bulk_job_results to fetch the final results.

Emulated bulk (DNS, subdomain, IP geo) is sync-only; these tools fan out single-input calls concurrently and are capped at 200 inputs per call. Exceeding the cap returns code: "EMULATED_BULK_CAP_EXCEEDED" rather than silently truncating.

Cost transparency: bulk variants do NOT save credits. 100 single calls and 1 bulk-of-100 cost the same. Bulk's value is latency, atomicity, and rate-limit consolidation.

bulk_whois

Description: Run WHOIS lookups for up to 10,000 domains in a single call. Uses WhoisXML's native Bulk WHOIS API. Each domain consumes 1 credit. Returns inline if the job completes within 20 seconds; otherwise returns status: "running" with a job_id for polling via bulk_job_status / bulk_job_results.

Arguments

• domains (array of strings, required) - Domain names to look up (1 credit per domain, max 10000 per call)
• confirm (boolean, optional) - Pass true to run a call estimated at over 100 credits, once the user has agreed to that cost

Response

Returns the uniform bulk envelope with per-domain WHOIS records in results[].data.

bulk_dns_lookup

Description: Run DNS lookups for up to 200 domains in a single call. Emulated bulk — the server fans out single DNS lookups concurrently. Each input consumes 1 credit. Always returns synchronously (no async job).

Arguments

• domain_names (array of strings, required) - Domain names to look up (1 credit per domain, max 200 per call)
• query_type (string, optional) - Comma-separated DNS query types (A, MX, NS, SOA, etc.) or "all". Applied uniformly to all inputs Default: "A"
• confirm (boolean, optional) - Pass true to run a call estimated at over 100 credits, once the user has agreed to that cost

Response

Returns the uniform bulk envelope with per-domain DNS records in results[].data.

bulk_ip_geolocation

Description: Run IP geolocation lookups for up to 200 IPs in a single call. Emulated bulk: the server fans out single-IP lookups concurrently. Each input consumes 1 credit. For larger jobs, WhoisXML's Bulk IP Geolocation API (not a tool on this server) runs asynchronous JSON jobs of up to 100,000 IPs.

Arguments

• ip_addresses (array of strings, required) - IP addresses to look up (1 credit per IP, max 200 per call)
• confirm (boolean, optional) - Pass true to run a call estimated at over 100 credits, once the user has agreed to that cost

Response

Returns the uniform bulk envelope with per-IP geolocation records in results[].data.

bulk_email_verification

Description: Verify up to 10,000 email addresses in a single call. Uses WhoisXML's native Bulk Email Verification API. Each email consumes 1 credit. Returns inline if the job completes within 20 seconds; otherwise returns status: "running" with a job_id. Per-row classification: ok / invalid (INVALID_EMAIL) / unknown (UNKNOWN) / failed (VERIFICATION_FAILED).

Arguments

• emails (array of strings, required) - Email addresses to verify (1 credit per email, max 10000 per call)
• confirm (boolean, optional) - Pass true to run a call estimated at over 100 credits, once the user has agreed to that cost

Response

Returns the uniform bulk envelope with per-email verification records in results[].data.

bulk_subdomain_lookup

Description: Run subdomain lookups for up to 200 domains in a single call. Emulated bulk — the server fans out single subdomain lookups concurrently, reusing the in-memory cache of subdomain_lookup so recently-fetched domains are free to re-query.

Arguments

• domain_names (array of strings, required) - Domain names to look up (10 Domain Research Suite credits per uncached domain, max 200 per call)
• confirm (boolean, optional) - Pass true to run a call estimated at over 100 credits, once the user has agreed to that cost

Response

Returns the uniform bulk envelope with per-domain subdomain lists in results[].data.

bulk_vpn_proxy_detection

Description: Check up to 100 IP addresses in one call for VPN, proxy, Tor exit, relay, hosting or CDN membership. Uses the VPN & Proxy Detection API's native batch endpoint, so it always returns synchronously (no async job). Duplicate inputs are looked up once. Each IP successfully looked up consumes 1 VPN & Proxy Detection API credit; rejected rows are not charged. Batch lookup requires a Starter or higher VPN & Proxy Detection plan, and each row follows the same plan rules as vpn_proxy_detection: confidence, first_seen / last_seen and residential-proxy network names need Pro or higher and read null on lower plans.

Arguments

• ip_addresses (array of strings, required) - IP addresses to classify (max 100 per call; 1 credit per IP successfully looked up)

Response

Returns the uniform bulk envelope. Each successful row's results[].data carries the same fields as vpn_proxy_detection. A row the API rejects comes back with ok: false and an error code such as INVALID_IP_RESERVED or INVALID_IP_FORMAT. The IPv4-first note on vpn_proxy_detection applies here too.

bulk_job_status

Description: Check the progress of an in-flight native bulk job (created by bulk_whois or bulk_email_verification). Returns status: "running" with progress counters while the job is in progress, or status: "completed" when done. Tenant-safe: rejects probes for jobs belonging to a different API token (code: "TENANT_MISMATCH").

Arguments

• job_id (string, required) - Opaque job identifier returned by a bulk_* tool when status=running

Response

Returns the uniform bulk envelope with status, total, succeeded, and failed counters. results is empty while the job is still running.

bulk_job_results

Description: Fetch the full per-input results for a completed native bulk job. If the job is still in progress, returns status: "running" — the caller should retry after a short delay. Tenant-safe: rejects cross-tenant probes (code: "TENANT_MISMATCH").

Arguments

• job_id (string, required) - Opaque job identifier returned by a bulk_* tool when status=running

Response

Returns the uniform bulk envelope with the full results array populated once the job is complete.

Authentication

All API tools require proper authentication via the WhoisXMLAPI. The tool_search tool (when enabled via --defer-loading) does not require authentication as it only searches tool definitions. The server must be configured with valid API credentials for the WhoisXMLAPI service.

Response Format

All tools return responses in JSON format. The structure of the response depends on the specific tool and the data returned by the WhoisXMLAPI.

Rate Limits and Credits

• A tool call can consume API credits based on WhoisXMLAPI pricing; What each tool costs gives each tool's cost
• Rate limits are enforced by the WhoisXMLAPI service
• Failed requests typically don't consume credits

Spend Cap

The server does not run a call it estimates will spend more than 100 credits unless the call passes confirm: true. It answers with an error result, with _meta.errorCause set to bad_arguments, that gives the estimate (for example "It could spend up to 5000 credits (1 for each of the 5000 entries in domains)") and asks the model to check with the user. Nothing is sent to WhoisXML API. Once the user agrees, the model repeats the same call with confirm: true added.

• Only the tools that can go over the cap take confirm: bulk_whois and bulk_email_verification (up to 10,000 credits a call), bulk_subdomain_lookup (up to 2,000), brand_alert (300 for a purchase with with_typos: true), and bulk_dns_lookup and bulk_ip_geolocation (up to 200). bulk_vpn_proxy_detection takes at most 100 distinct IPs at 1 credit each, so it never goes over the cap.
• A list longer than its tool accepts gets the tool's own error, not the cap's, since the tool rejects it before any upstream request.
• Single-input tools, except for a brand_alert purchase with typos, and any call estimated at 100 credits or fewer, run as before.
• The estimate counts every input at the rate its tool's arguments give above, so it can be higher than the final charge: a domain still in the bulk_subdomain_lookup cache costs nothing.
• The cap applies in stdio and hosted mode alike.

Best Practices

1. Start broad: Use basic tools like whois and dns_lookup first
2. Follow leads: Use results to inform subsequent queries
3. Combine tools: Use multiple tools for comprehensive analysis
4. Check history: Use historical tools to understand changes over time
5. Verify results: Cross-reference data from multiple tools

Error Handling

Common error scenarios:

• Invalid input: Malformed domains or IP addresses
• Rate limiting: Too many requests in a short timeframe
• Insufficient credits: Account lacks sufficient API credits
• Network issues: Temporary connectivity problems

The server handles these gracefully and provides clear error messages to help diagnose issues.

Disabling Tools

If you don't need all 35 tools, you can disable specific ones to reduce functionality or improve startup performance. This is useful for:

• Reducing API surface: Limit available tools for security
• Performance optimization: Faster startup with fewer tools
• Specialized use cases: Only enable tools relevant to your workflow

You can disable tools using environment variables or command-line flags:

# Disable security-related tools
export WHOISXMLAPI_DISABLED_TOOLS="threat_intelligence,reverse_whois"

# Disable historical analysis tools
export WHOISXMLAPI_DISABLED_TOOLS="whois_history,dns_history"

See Configuration for complete documentation and examples.