Investigations MCP

🚧
Early Access
SpyCloud 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.

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, 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 12 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 (4 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, infostealer, 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_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 coverage
Infostealer 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 and infostealer 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 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 populations
Large gaps between their numbers are expected. In domain_stats, infected_employees counts only staff who signed in to a first-party site at their own domain, so a zero there does not mean no employee exposure. Use total_botnet_records for that.

Identity graph: IDLink (2 tools)

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 a graph summary (top pivots, node counts, and totals) and a `query_id`. Set `max_depth` to 1 (default and recommended) or 2. Graphs are capped at 2,000 nodes and 15,000 edges.	You want to find the other identities, accounts, and devices connected to a subject.
`idlink_nodes`	Retrieves nodes from a prior `idlink_query` by `query_id`, filtered by node type, minimum confidence, or depth. Returns 25 nodes per page by default, up to 100.	You want specific records from a graph without loading the entire graph.

The two-step pattern protects your assistant's context window: see the shape of the graph first, then pull only the slice you need.

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.

How access is enforced

A tool call succeeds only when all three layers allow it:

Subscription entitlement. Your organization's Investigations subscription determines which datasets are available.
User scopes. SpyCloud assigns MCP scopes to each user during onboarding.
Per-tool enforcement. SpyCloud checks the user's scopes on every tool call.

Scope	Grants access to
`mcp:breach`	Breach data tools
`mcp:infostealer`	Infostealer log tools
`mcp:idlink`	Identity graph tools
`mcp:stats`	Domain and exposure analytics tools

Known limitations in Early Access

IDLink runs only when called. Searching an email with breach_data does not trigger an IDLink pivot. Ask your assistant to run IDLink when you want connected identities.
Domain tools return statistics, not records. To pull individual records for a domain, use the Investigations API.
Infostealer detail starts November 2024. See the coverage note above.
Capped results return oldest first. A query that reaches the 1,000-record cap returns the oldest records first. Add a date window to see the most recent records.
Source descriptions can be brief. Some source descriptions are more detailed in the SpyCloud Console. Use breach_catalog_get or 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.