Investigations MCP
Query SpyCloud Investigations data from your AI assistant in plain language to build cases faster.
What it is
SpyCloud Investigations MCP connects AI tools, including Claude Code, Cursor, Claude Desktop, and ChatGPT, to SpyCloud Investigations data. As with any generative AI tool, you ask a question in plain language, and your assistant selects the right SpyCloud tools, runs them, and summarizes its findings based on the returned SpyCloud data.
The MCP uses the same underlying data as the SpyCloud Investigations API: recaptured breach records, phished records, infostealer log detail, domain exposure analytics, and the IDLink identity graph. This capability extends the API. It does not replace it.
| Use the MCP to | Use the Investigations API to |
|---|---|
| Explore a case using your preferred LLM for analytical capability | Run the same query repeatedly and at volume |
| Have an LLM automatically perform pivots across selectors and datasets without writing code | Directly integrate SpyCloud data into your workflow, OSINT tools, or an automation environment |
| Draft findings, timelines, and summaries | Produce deterministic, auditable records for the case file |
Who it's for
Investigations API customers whose analysts run multi-step investigations across many selectors: threat intelligence, incident response, SOC, fraud, and insider threat teams, along with the detection and automation engineers building agentic workflows on SpyCloud data.
As with any MCP, this interface requires an AI toolset (such as Claude Code, Cursor, or ChatGPT) that is installed and can be configured to support the SpyCloud MCP.
Available tools
Early Access includes 110+ tools across four datasets. Your assistant selects tools automatically based on your request. You never need to name a tool, but you can.
Breach data (5 tools)
| Tool | What it does | Use it when |
|---|---|---|
breach_stats | Returns a fast exposure summary for a domain or email: record count, number of related breach sources, and days since last discovery, across all severities. | You want a first read before pulling full records. |
breach_data | Searches SpyCloud's recaptured breach, malware, and phishing records by asset. Supports 19 selector types, including email, username, phone, IP address, password, log ID, infected machine ID, SSN, national ID, and passport. Filters by severity and publish date (since and until). Returns summary, standard, or full detail in JSON or CSV. Returns 25 results per page by default, up to 1,000, with cursor pagination. | You need field-level records for a specific asset. This is the starting point for most investigations. |
breach_data_domains | Searches all breach and infostealer records associated with a domain, including employee accounts and stolen credentials. Supports filters for domain relationship, severity, and date. | Investigate domain-wide exposure and see every record tied to the domain. Use the type filter (corporate, infected, email_domain, or target_domain) to narrow results, along with date and severity filters. |
breach_data_doc_ids | Retrieves full records by document ID, up to 100 per call. | A prior search returned document_id values and you want the complete records. |
breach_catalog_get | Returns source metadata by source ID: title, description, category, publish and acquisition dates, and record count. Up to 100 IDs per call. | You need to cite a breach source by name and description instead of a bare ID. |
Infostealer logs (3 tools)
| Tool | What it does | Use it when |
|---|---|---|
infostealer_logs_by_machine | Lists every log tied to an infected machine ID, metadata only: log ID, malware variant, and timestamps. Returns 10 logs by default, up to 50. | You want to see repeat infections, multiple malware families on one device, or the same device's data redistributed across sources. |
infostealer_log_metadata | Returns system information for one log (machine ID, malware variant, country, time zone, hardware, bot ID, and log name) plus item counts for each collection. Does not return collection contents. | Before you pull collections, to see what the log holds and how large each collection is. |
infostealer_log_collections | Retrieves named collections from a log: autofills, bookmarks, clipboard, cookies, credentials, credit_cards, downloads, exfiltrated_files, files, history, keychain, processes, and software. An optional cookie_limit caps cookies per file for large cookie stores. Returns JSON or CSV. | You need the contents of the log itself. |
Infostealer coverageInfostealer log detail is available for logs SpyCloud published starting in November 2024. Older log IDs return "not found" in these tools, even when they remain valid in
breach_data.
Domain and exposure analytics (3 tools)
| Tool | What it does | Use it when |
|---|---|---|
domain_stats | Summarizes breach, phished, and malware exposure by data type for a domain, keyed on the domain of the exposed email address (workforce exposure). Includes total records, top 10 passwords, password reuse rate, and infected employees versus infected customers. Window: all time (default), 12 weeks, or 24 weeks. | You need a workforce exposure summary for a domain. |
domain_timeseries | Breaks domain exposure into daily, weekly, or per-source buckets. | You need to show whether exposure is rising, falling, or flat. |
botnet_customers | Reports infostealer malware exposure for people who signed in to the domain's website, keyed on the login target domain. Covers customer and consumer accounts over a rolling 12 months. View summary for totals and password reuse, or history for a monthly timeline. | You need customer-side infostealer impact, not workforce exposure. |
These three tools measure different populationsLarge gaps between their numbers are expected. In
domain_stats,infected_employeescounts only staff who signed in to a first-party site at their own domain, so a zero there does not mean no employee exposure. Usetotal_botnet_recordsfor that.
Identity graph: IDLink (1 tool)
| Tool | What it does | Use it when |
|---|---|---|
idlink_query | Pivots from one selector to related records across the SpyCloud identity graph. Accepts 13 selector types: email, IP address, phone, username, plaintext password, infected machine ID, log ID, bank number, driver's license, national ID, Social Security number, passport number, and social handle. Returns 50 records per page by default, up to 100. | You want to find the other identities, accounts, and devices connected to a subject. |
Understanding Domain searches
Use the type filter to control which domain relationships are included in your query.
| Type | Records returned |
|---|---|
| Omitted | All records associated with the domain, whether it appears as an account domain or a target domain. |
corporate | Breach records associated with the organization's own accounts, including matching account domains, email domains, or target subdomains. Excludes severity 25 (infected-machine) records. |
infected | Infostealer exposure, including severity 25 records associated with the domain and stolen credentials for the domain's websites belonging to external users. |
email_domain | Records associated with email addresses or account domains matching the specified domain, regardless of severity. Excludes matches based only on target domains. |
target_domain | Records where the domain or its subdomains are the target of stolen credentials, regardless of the account holder's domain or record severity. |
Pagination and rate limits
Domain searches return 1,000 records per page by default. Use limit to request fewer records, up to a maximum of 1,000.
If additional records are available, the response includes a cursor. Use the same domain and returned cursor to retrieve the next page. Cursors expire after 2 minutes, and domain searches are limited to one request per second per user. Do not run requests in parallel.
For large domains, use since and until date filters (YYYY-MM-DD), type, or severity to narrow your results rather than paging through every record.
Access and query consumption
- Who can use it. Investigations API customers whose users have been onboarded by SpyCloud Product Success.
- What a call costs. Each tool call draws one query from the Investigations API key assigned to your user. The query rates and API limits in your Investigations subscription apply to MCP calls.
- What you can reach. During Early Access, onboarded users can use all 12 tools.
- What may change. Pricing and packaging may change at general availability. Your SpyCloud account team will give you advance notice.
An agent working a multi-step case often makes several tool calls to answer a single question. Ask your assistant to list its tool calls when you want to see what a question cost.
Early AccessSpyCloud Investigations MCP is in Early Access. Tools, limits, and behavior may change before general availability, targeted for early 2027. All users of the SpyCloud Investigations API can enable MCP use.
Known limitations in Early Access
- IDLink runs only when called. Searching an email with
breach_datadoes not trigger an IDLink pivot. Ask your assistant to run IDLink when you want connected identities. - Infostealer log detail starts November 2024. See the coverage note above.
- Source descriptions can be brief. Some source descriptions are more detailed in the SpyCloud Console. Use
breach_catalog_getor the Investigations Module for full source context.
Next steps
- Getting Started: get onboarded and connect your client.
- Best Practices: ask better questions and pivot efficiently.
- Troubleshooting: fix common setup and query issues.
- Security, Privacy & Data: understand authentication, data flow, and controls.
Updated 22 days ago