MCP tool reference

The urlquery MCP server currently exposes 25 public tools. Tool errors are returned as MCP tool errors so the agent can correct invalid arguments or explain upstream failures.

Dates use YYYY-MM-DD unless a tool says otherwise. Limits below are result limits, not traffic or request-volume measurements.

Submission tools

submit_url

Submit an authorized URL for browser analysis through the Submission API. A normal scan takes about 30 seconds plus run_time, depending on queue load.

Argument	Required	Description
url	yes	Absolute http or https URL. The host must resolve, and only to public addresses.
access	no	public (default), restricted, or private.
useragent	no	Browser user-agent override, up to 512 characters.
device_type	no	desktop (default), mobile, or tablet.
tags	no	Up to 20 labels, each 1–64 letters, digits, or underscores. Invalid tags are rejected.
meta	no	Up to 20 string pairs, visible only to you and your team. Never place secrets here.
run_time	no	Seconds the browser stays on the page, 20 through 200; defaults to 26.
sanitize_url	no	Replaces a base64-encoded email address at the end of the URL path with a placeholder. It does not remove other tokens, parameters, or personal data.

The result is the submission: queue_id, report_id, status, the URL as it will be analyzed, its resolved IP, and the settings in effect. Do not let an agent retry submit_url automatically after an error or timeout; the first call may already have queued the analysis.

{
  "url": "https://example.com/",
  "access": "public",
  "device_type": "desktop",
  "sanitize_url": true
}

submit_status

Fetch the progress of a submission using the queue_id returned by submit_url. Only submissions made with your API key or by your team are visible; others return not found.

{"queue_id":"<QUEUE_ID>"}

status is queued, processing, analyzing, done, or failed. The report ID is known from the start. Poll every 5 to 10 seconds until the status is done, then read the report; failed means no report was produced.

Report tools

report_guide

Return guidance for interpreting report evidence and choosing focused tools. Optional topic accepts quickstart (default), overview, detections, http, resources, indicators, javascript, artifacts, hosts, workflows, limits, or full.

{"topic":"http"}

The HTTP topic explains transaction fields, request contexts, requester-to-target semantics, Host Profile relation derivation, filtering, indexes, and safe content boundaries. Use the full topic for all report evidence and workflow guidance.

get_report

Fetch a safe report summary. Required: report_id. Optional: view is compact by default or full; host_limit defaults to 25 and caps at 25; host_offset pages hosts in compact output.

{"report_id":"<REPORT_ID>","view":"compact"}

Use compact output first. Full output is an unpaginated compact snapshot bounded to 128 KiB. It includes report detections, host summaries, bounded clipboard content and Telegram tokens, selected artifact metadata, script-source metadata, HTTP methods and bounded request-data previews, and alert tables. It is not exhaustive and can truncate. Use focused tools for files and shortcuts, eval/write/console observations, resource inventory, raw headers/cookies, complete request data, response bodies, and Telegram URL or bot metadata.

get_report_json

Fetch the complete access-filtered report as canonical JSON using the current types.Report model. This explicit export is not bounded to 128 KiB and can consume substantial model context.

Argument	Required	Description
report_id	yes	Report UUID.
remove_alerts	no	Defaults to false. When true, clear all IDS, analyzer, and urlquery alerts from report summaries, deprecated sensors, HTTP transactions, JavaScript observations, files, archives, PDFs, and Windows shortcuts, then reset derived alert counts.

{"report_id":"<REPORT_ID>","remove_alerts":true}

This is an access-filtered public report, not the original browser ClientReport: client metadata, screenshot, and domain graph are not included. Stored response, final-DOM, and JavaScript content can remain externalized even when resource_available is true. Use get_report_resource for required hashes and hydrate test fixtures deliberately. JavaScript data is a JSON string; response and final-DOM data fields are byte slices encoded as base64 in JSON.

The report can contain cookies, headers, captured request data, clipboard text, tokens, and other sensitive or page-controlled content. Treat all values as untrusted evidence and avoid using this export for routine triage.

Shared list arguments

The following focused report tools require report_id, default limit to 25 with a cap of 25, and accept an offset of 0 or greater.

Tool	Additional arguments
get_report_detections	types: ids, analyzer, urlquery; optional exact severity. Absence of detections does not imply benign activity.
list_report_technologies	Optional host and technology name substring filters.
list_report_http_transactions	Optional host, method, exact status, alerted_only, and available_only. Output includes requester, browser request context, and a bounded request-data preview. Use the original index with get_report_http_transaction for detail.
list_report_resources	Optional source, mime, alerted_only, and available_only. Use this before retrieving content.
list_report_indicators	Optional kinds: fqdn, domain, ip, asn, url, hash, certificate, telegram_token; algorithms: md5, sha1, sha256, sha512 (omitted defaults to sha256; a non-empty list replaces the default); and alerted_only. Omitting kinds includes every kind, including Telegram tokens.
list_report_artifacts	kinds: file, pdf, windows_shortcut, telegram, clipboard. Clipboard content and Telegram tokens are bounded default evidence. include_sensitive defaults to false and adds shortcut command lines and Telegram URL or bot metadata.
list_report_javascript	kinds: script, eval, write, console; optional alerted_only; include_content defaults to false.

HTTP transaction indexes are one-based original report positions and remain stable when filters are applied. Pagination offsets remain zero-based. Requested by identifies the source URL; Request context is the browser-provided request cause, such as document, script, xhr, fetch, beacon, or img. It is distinct from response MIME and magic.

Resource, JavaScript, and artifact rows currently use zero-based indexes within their source arrays. Use source or kind together with the index. Indicator output normalizes indexed provenance to one-based references independently of those focused row indexes.

{
  "report_id": "<REPORT_ID>",
  "limit": 25,
  "offset": 0,
  "alerted_only": true
}

get_report_http_transaction

Return detailed metadata for one transaction using the one-based original index from list_report_http_transactions.

Argument	Required	Description
report_id	yes	Report UUID.
index	yes	One-based original HTTP transaction index.
include_raw_headers	no	Add captured request and response raw-header chunks.
include_post_data	no	Add captured POST, PUT, or other request-data content.
raw_headers_offset	no	Zero-based byte offset applied to both raw-header blocks.
post_data_offset	no	Zero-based byte offset into captured request data.
max_bytes	no	Bytes per selected content field; defaults to 65536 and accepts 4 through 65536.

The default metadata response includes method, URL, status, requester, navigation state, timestamp, HTTP version, destination, response hashes and fingerprints, timings, TLS and certificate details, complete available alert fields, request-data size, and response-resource retrieval guidance.

{"report_id":"<REPORT_ID>","index":35,"include_raw_headers":true,"include_post_data":true,"raw_headers_offset":0,"post_data_offset":0,"max_bytes":65536}

Selected content is returned as embedded resources with envelopes containing captured size, returned bytes, SHA-256, next_offset, and has_more. Repeat with returned offsets to retrieve larger values. Raw-header extraction stops at the first stored header terminator. “Complete” means all content captured in the report, not proof of complete original wire transmission.

list_report_indicators

Produce a deterministic, deduplicated report handoff without classifying every value as malicious. By default the tool includes every indicator kind and only SHA-256 hashes.

Provenance is one-based and can be submitted, final, final_dom, host:N, http:N, tls:N, javascript.script/eval/write:N, artifact.file:N[/archive:N], artifact.pdf:N[/url:N], artifact.shortcut:N, or artifact.telegram:N. Plain contiguous indexes with one prefix are compressed into ranges. Observations counts distinct provenance references, Alerted counts references carrying alerts, and Alert refs sums attached alert-list entries rather than unique detections.

Content hashes support MD5, SHA-1, SHA-256, and SHA-512. Certificate fingerprints support only SHA-1 and SHA-256, so selecting only MD5 or SHA-512 produces no certificate rows. Available is explicit for final-DOM and HTTP hashes, unknown for JavaScript and artifact hashes, mixed when aggregated states differ, and n/a for non-content indicators.

{
  "report_id": "<REPORT_ID>",
  "kinds": ["fqdn", "ip", "hash", "certificate", "telegram_token"],
  "algorithms": ["sha256"],
  "alerted_only": false,
  "limit": 25,
  "offset": 0
}

Telegram tokens are returned exactly as report indicators and are included by default when kinds is omitted; there is no include_sensitive argument. Both top-level and nested bot-token fields are considered and equal values deduplicate under one provenance reference. The tool also includes Telegram domain, IP, ASN, and selected hash observations, but excludes other bot/chat metadata and full Telegram URLs. Clipboard text is not parsed. Pass explicit kinds without telegram_token when tokens are not wanted in a handoff.

get_report_screenshot

Return the report screenshot as MCP image content. Required: report_id. Screenshots larger than 5 MiB are rejected.

get_report_resource

Retrieve one resource after locating its hash with list_report_resources.

Argument	Required	Description
report_id	yes	Report UUID.
hash	yes	MD5, SHA-1, SHA-256, or SHA-512 resource hash.
mode	no	preview by default or full.
offset	no	Zero-based byte offset into the resource; defaults to 0.
max_bytes	no	Maximum bytes returned in this chunk; minimum 4 when supplied and capped by the mode ceiling.

Every non-image response includes total_bytes, offset, returned_bytes, next_offset, and has_more. Continue with the returned next_offset until has_more=false. In preview mode, a response at the 64 KiB ceiling marks preview_limit_reached=true; continue with mode=full to read further. A response can also mark full_limit_reached=true, meaning the resource is incomplete but no additional bytes are retrievable. Use chunks small enough for the MCP client; 8 KiB is suitable for OpenCode. Preview mode limits the retrievable prefix to 64 KiB, while full mode permits offsets through a 5 MiB hard ceiling. Images that fit in one response are returned as MCP image content. Oversized binaries are rejected rather than returned beyond the selected mode ceiling. Treat all returned content as untrusted.

Content is returned only when the report is visible to your API key and captured that hash. The API serves captured content as an opaque download, so the server detects whether it is text or an image from the bytes.

Search tools

search_reports

Search visible reports and return newest results first.

Argument	Required	Description
query	yes	Search query using fields, phrases, boolean operators, wildcards, or ranges.
start_date	no	Inclusive start date; must be supplied with end_date.
end_date	no	Inclusive end date; must be supplied with start_date.
view	no	compact by default or legacy.
limit	no	Defaults to 10 and caps at 25.
offset	no	Result offset, minimum 0. Use the returned next_offset; offset plus limit cannot exceed 10,000.

{
  "query": "tags:phishing AND url.tld:xyz",
  "start_date": "2026-08-01",
  "end_date": "2026-08-30",
  "limit": 10
}

Results are filtered by visibility after matching, so a page can return fewer reports than limit while more remain; next_offset accounts for that. The report search API searches the last year, even when the date arguments name an older period, so treat older searches and analysis periods as unsupported.

search_syntax

Return part of the search guide. Optional topic accepts quickstart, report, http, artifacts, examples, limits, or full; it defaults to quickstart.

Analysis tools

These tools analyze report populations visible to the caller. Their counts are urlquery report observations, not global threat prevalence. They share the report search API's one-year window.

report_trends

Create a time-bucketed report timeline and top factual facets.

Argument	Required	Description
query	yes	Search population.
start_date, end_date	no	Inclusive date range; supply both or neither. Without them, the trend covers the last year.
interval	no	day, week (default), or month.
facets	no	domain, ip, asn, country, technology, tag, detection.
facet_limit	no	Defaults to 20 and caps at 25.
max_reports	no	Defaults to 200 and caps at 500.

compare_report_periods

Compare normalized observations in baseline and current periods.

Required arguments are query, baseline_start, baseline_end, current_start, and current_end. Optional facets use the values above. limit defaults to and caps at 25, min_reports defaults to 1, and max_reports defaults to 200 with a cap of 500 per period.

pivot_indicator

Summarize observations related to one URL, domain, FQDN, IP, ASN, or cryptographic hash.

Argument	Required	Description
indicator	yes	Indicator value.
type	no	auto (default), url, domain, fqdn, ip, asn, or hash.
start_date, end_date	no	Supply both; defaults to the last 90 days through today.
related	no	Facets: domain, ip, asn, country, technology, tag, detection.
related_limit	no	Defaults to and caps at 25.
report_limit	no	Defaults to 20 and caps at 25.
max_reports	no	Defaults to 200 and caps at 500.

Host Profile tools

Host Profile values are deduplicated report observations. They are not traffic volume, passive DNS, or attribution. The underlying corpus is shared and is not filtered by source-report visibility; derived facts and relations can originate from public, restricted, or private analyses.

get_host_profile

Profile one exact FQDN or IP literal. URLs are not accepted.

Argument	Required	Description
host	yes	Exact FQDN or IP.
sections	no	ips, technologies, certificates, cookies, headers, mimes, relations; defaults to all.
fact_limit	no	Newest facts per category, defaults to 5 and caps at 10.
relation_limit	no	Newest relations, defaults to 5 and caps at 10.

pivot_host_fact

Find hosts sharing an exact fact.

Required arguments are kind and value. kind accepts domain, ip, asn, country, technology, certificate, cookie, header, or mime. Certificate values are a 64-character SHA-256 hash, or an exact issuer or subject organization or common name, case-insensitive. Common options are sort (first_seen or last_seen), order (asc or desc), limit (defaults to and caps at 25), and an opaque cursor.

Domain pivots accept include_apex. Cookie pivots accept secure, http_only, same_site, partitioned, host_only, persistent, and path exact filters.

pivot_host_relations

Traverse source-to-target interactions around an exact host.

Argument	Required	Description
host	yes	Exact FQDN or IP literal.
direction	no	incoming, outgoing, or both (default).
relation_type	no	redirects_to, loads_from, calls, or embeds.
sort	no	first_seen or last_seen (default).
order	no	asc or desc (default).
limit	no	Defaults to and caps at 25.
cursor	no	Opaque continuation cursor.

hunt_hosts

Find date-bounded host cohorts by their relation graph shape.

Required arguments are time_basis (first_seen or last_seen), start_date, and end_date. Relation criteria require direction (incoming or outgoing). Count and ratio criteria require relation_type.

Optional bounds are min_total_relations, max_total_relations, min_relation_count, max_relation_count, min_relation_ratio, and max_relation_ratio. Ratios are from 0 through 1. Sort by observed (default), total_relations, matching_relations, or matching_ratio, with order asc or desc (default). The matching_* sorts require relation_type. limit defaults to and caps at 25; use cursor for continuation.

{
  "time_basis": "last_seen",
  "start_date": "2026-08-01",
  "end_date": "2026-08-30",
  "direction": "incoming",
  "relation_type": "calls",
  "min_relation_count": 10,
  "min_relation_ratio": 0.8,
  "sort": "matching_ratio"
}

Reputation tool

reputation_check

Check one HTTP or HTTPS URL. Required: url; the scheme is optional.

{"url":"https://example.com/path"}

The result contains the preserved input, a standardized verdict (malicious, suspicious, benign, or unknown), and applied_to (url or fqdn). The lookup considers exact URL and FQDN reputation observed over the last 30 days and returns the stronger verdict, with URL winning ties. Registrable-domain and IP verdicts are not applied, including for IP-hosted URLs. The call consumes the v2 reputation-lookup and overall quotas.

Use reputation to prioritize investigation. An unknown or benign result does not prove that a URL is safe.