MCP use cases and workflows

Start with the investigation question, not a list of tools. A useful result should connect conclusions to report IDs, hashes, observed behavior, and explicit date windows while making uncertainty visible.

Investigation	Typical outcome
Explain a suspicious report	Concise behavior summary, evidence, detections, contacted infrastructure, and gaps.
Analyze a new URL	Authorized browser analysis followed by the same evidence-led report triage.
Research an indicator	Representative reports, related observations, and corroborated infrastructure pivots.
Compare two periods	New, rising, persistent, and declining signals within a defined report population.
Map infrastructure	Candidate relationships based on shared facts and observed interactions, with false-positive context.
Prepare a detection fixture	Canonical report JSON with existing alerts removed and required resources hydrated deliberately.
Prepare a handoff	Reproducible evidence, IOCs, confidence, and unresolved questions.

The assistant handles the individual MCP calls. The sequences below show how evidence is developed and what a defensible answer should preserve.

Triage an existing report

Question: “What happened in this report, what matters, and what remains uncertain?”

Outcome: A compact assessment tied to captured URL behavior, detections, infrastructure, and report evidence.

1. Call get_report with the report ID and the default compact view.
2. Review the final URL, title, status, tags, detection counts, technologies, and host summary.
3. Call get_report_detections to inspect IDS, analyzer, and urlquery signals.
4. Use list_report_http_transactions with a host, status, or alert filter to isolate relevant requests and retain the one-based original index.
5. Use get_report_http_transaction when complete timing, TLS, alert, raw-header, or captured request-data evidence is needed for one transaction.
6. List resources to locate response hashes, or list JavaScript before opting into source content.
7. Retrieve a screenshot or one response resource only when it answers a specific question.

The investigation starts from the report ID:

{"report_id":"<REPORT_ID>"}

Do not treat a clean report as proof of safety. Explain what evidence was present, what was absent, and what the scan could not establish.

Analyze a new URL

Question: “Can you analyze this URL and explain the resulting browser activity?”

Outcome: A completed report and evidence-led triage, with the requested visibility recorded.

Use this workflow only when the user has authorized a new analysis.

1. Confirm that the URL contains no private token, personal data, or confidential internal name.
2. Call submit_url with an explicit access value and sanitize_url choice. Tag it, for example case_1234, so the report can be found again.
3. Save queue_id and report_id from the response. Both are known immediately.
4. Poll submit_status every 5 to 10 seconds until status is done or failed. failed means no report was produced.
5. When it is done, continue with the report-triage workflow using report_id.

submit_url rejects URLs whose host does not resolve or resolves to a private or otherwise non-public address, and tags with characters other than letters, digits, and underscores. Report the error to the user rather than rewriting the URL.

Do not retry submit_url automatically after an ambiguous network failure; that can create duplicate jobs.

Research an indicator

Question: “Where has this indicator appeared, and what related behavior is supported by reports?”

Outcome: A bounded set of representative reports, stable pivots, related observations, and corroborating evidence.

1. Use search_syntax when the query field or operator is uncertain.
2. Call search_reports with explicit dates and a small result limit.
3. Open representative reports with get_report rather than inferring behavior from titles or tags alone.
4. Extract stable indicators such as exact domains, IPs, certificate hashes, or resource hashes.
5. Use pivot_indicator to summarize the indicator across a bounded period.
6. Corroborate related infrastructure with individual report evidence.

{
  "query": "http.response.data.sha256:<SHA256>",
  "start_date": "2026-07-01",
  "end_date": "2026-08-30",
  "limit": 10
}

Prefer exact hashes and structured fields over broad text or leading-wildcard searches.

Compare activity over time

Question: “What changed between these two periods?”

Outcome: New, rising, persistent, and declining observations with exact population and coverage details.

Use report_trends to understand one report population over time. Use compare_report_periods when the question asks what is new, rising, persistent, or declining between two windows.

Always report:

• The exact query and inclusive dates.
• The number of reports analyzed and whether the result was partial.
• Whether a value is a count of reports, a facet frequency, or a normalized change.
• That results describe reports visible to this API key, not global prevalence.

Avoid comparing incomplete periods, such as the current partial week against a complete prior week, without saying so.

Report search covers only the last year, so trend and comparison periods older than that return nothing. Do not present them as complete.

Map related infrastructure

Question: “What infrastructure is observably related to this host, and which connections are distinctive?”

Outcome: Candidate hosts and relationships ranked by evidentiary value, not an unsupported ownership or campaign claim.

1. Call get_host_profile for an exact FQDN or IP.
2. Identify distinctive facts. Certificate hashes and unusual cookie attribute tuples are often stronger than common technologies or shared IPs.
3. Use pivot_host_fact for exact shared facts.
4. Use pivot_host_relations to inspect incoming or outgoing interactions.
5. Use hunt_hosts only when you have a clear date-bounded graph hypothesis.
6. Return to reports to validate candidate hosts with captured behavior.

Relation direction is relative to the profiled host. Incoming means another host interacted with it; outgoing means it interacted with another host.

Discover infrastructure patterns

Question: “Which recently observed hosts share the interaction pattern seen in this investigation?”

Outcome: A date-bounded candidate set for report-level validation.

This hunt finds recently observed hosts whose incoming graph is dominated by active calls:

{
  "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"
}

High ratios or relation totals identify candidates, not malicious infrastructure. Shared services, CDNs, analytics, and common dependencies can produce similar graph shapes.

Prepare a detection fixture

Question: “Can this existing report be cleaned and reused to test a new detection?”

Outcome: Canonical report JSON with prior detections removed and the evidence required by the new rule made explicit.

1. Call get_report_json with remove_alerts=true.
2. Save the returned JSON as the test fixture and verify it unmarshals into the expected report type.
3. Identify content hashes required by the detection. Public report JSON can mark content available without embedding its bytes.
4. Fetch only required content with get_report_resource, following next_offset until has_more=false, and verify each returned hash before injecting it into the fixture.
5. Store JavaScript source in its string data field. Store response and final-DOM bytes as base64 because those report fields are byte slices.
6. Run the focused detection package tests and confirm both positive and negative expectations.

The export is the access-filtered types.Report, not the original browser ClientReport. It does not include client-only metadata, screenshot, or domain graph and is not directly suitable for replay through analyzer endpoints that require those fields.

Prepare a defensible handoff

Question: “Can another analyst reproduce this assessment and understand its limitations?”

Outcome: A concise investigation record with evidence, judgment, confidence, and gaps clearly separated.

Use list_report_indicators with explicit kinds for the intended handoff; include telegram_token only when token evidence belongs in the handoff. Record report IDs, tool arguments, date windows, source indexes, and important hashes. Separate direct observations from analytical judgments and state confidence and gaps. This lets another analyst reproduce the pivots and understand what the evidence does not prove.