Troubleshooting

🚧
Early Access
SpyCloud Investigations MCP is in Early Access. Tools, limits, and behavior may change before general availability, targeted for early 2027.

Quick reference

Symptom	Likely cause	What to do
Server never starts and no error appears (Claude Desktop)	Node.js is missing, so `npx` can't launch the bridge and the sign-in prompt never opens	Install Node.js, then fully quit and relaunch Claude Desktop
Signed in, but no SpyCloud tools appear	Your user has MCP access but no dataset scopes	Contact Product Success to confirm your scopes
One specific tool is missing	Your scopes don't include that dataset	Contact Product Success
HTTP 403	Entitlement gap, or a request sent to the wrong base path	Confirm your Investigations entitlement and the endpoint Product Success provided
Zero results where you expect hits	Selector format mismatch	Username search is case-sensitive. Remove the leading `+` from phone numbers. There is no email-domain search type.
Results seem to stop short	The 1,000-record cap returns the oldest records first	Add a date window to the query
Log "not found," but the log ID appears elsewhere	Infostealer log detail starts with logs published in November 2024	Confirm the log was published after that date
Connection blocked	Some datacenter IP ranges are blocked by SpyCloud's web application firewall	Check your network egress. If your agent runs in a cloud environment, contact Product Success.
Slow responses, timeouts, or context errors	A large result set is streaming through the model	Use `detail_level` `summary`, a result limit, or a narrower date window, or write results to a file
Queries used up faster than expected	Agents chain several tool calls per question, and each call draws one query	Ask more specific questions, and ask your assistant to confirm before running large pivots

Setup and connection

I don't see the SpyCloud server in my client

Check that:

the endpoint is entered exactly as provided, including /mcp,
your configuration matches the example for your client in Getting Started,
you restarted the client after changing its configuration, and
your client supports remote HTTP transport and OAuth.

ChatGPT doesn't show the option to add a custom connector

Custom connectors require Developer Mode and a ChatGPT plan that supports them. On workspace plans, your ChatGPT admin may need to enable Developer Mode or approve the connector.

ChatGPT connected, but the SpyCloud tools don't run

Enable the SpyCloud connector for the conversation from the tools menu, then ask a question that names an asset. If it still fails, disconnect and reconnect the connector, then start a new chat.

Sign-in fails with a redirect or callback error

SpyCloud accepts sign-in only from approved client redirect URLs. If you're using an unsupported client or routing through an AI gateway, contact Product Success.

Sign-in and access

I'm being asked to sign in again

This is expected. Access tokens are short-lived and refresh tokens aren't issued by default. Sign in again when prompted.

I authenticated, but I see no tools

Your user has baseline MCP access but no dataset scopes. Contact Product Success to confirm your scopes.

A specific tool isn't available

Tool availability depends on your Investigations subscription and your MCP scopes. Contact Product Success to review your access.

Results

My query is taking longer than expected

Large breach searches can take several seconds. Identity graph and statistics calls are usually faster. If a broad query runs long, narrow the asset, dataset, or date window.

I asked the same question twice and got different results

The underlying data didn't change. Your assistant decides which tools to call and how to summarize them, so similar prompts can produce different tool sequences. For more consistent results, name the dataset you want and ask the assistant to show its tool calls. For fully repeatable queries, use the Investigations API.

The results look incomplete or wrong

Ask your assistant: "Which SpyCloud tools did you call, and with what parameters?" Then narrow or clarify your request. If the SpyCloud tool response itself appears incorrect, contact SpyCloud.

IDLink results didn't appear

IDLink runs only when your assistant calls it. Searching an email with breach_data does not trigger IDLink. Ask for an IDLink pivot explicitly.

Getting help

Contact your SpyCloud representative or SpyCloud Support. To speed resolution, include:

your MCP client and version,
the approximate time of the issue, with time zone,
the tool calls and parameters your assistant used, and
any error message, exactly as shown.

Don't paste sensitive result data into a support request unless SpyCloud asks for it.