Setup

Six read-only tools that let an AI assistant explore the graph without writing Cypher by hand:

• query — run any Cypher query against WhisperGraph; returns columns, rows, statistics, and an evidence block. Supports format (table / graph / compact) and count-first page / pageSize pagination.
• explain_indicator — structured threat-intel assessment (severity, factors, sources) for an IP, hostname, ASN, or CIDR.
• explain_schema — the schema, on demand. No argument returns the label catalogue (label + count + scale); pass a label to get that entity's properties, inbound/outbound edges, and a runnable sample traversal. The schema is never dumped into context up front.
• read_docs — pull the Whisper docs (whisper.security/docs/**) on demand: list, search, or fetch one page as Markdown. Keeps the Cypher reference and cookbook out of the always-on context.
• list_workflows — search the shared workflow & recipe gallery; each item comes back with its summary and full parameter space, so the agent can run any variant.
• run_workflow — run one or more gallery playbooks by slug in a single call (a multi-step investigation collapsed into one tool call); returns chained per-step results, derived signals, and an evidence trail.

run_workflow is how whole investigations run in one call. Typosquat sweeps, WHOIS history, host identity, and CDN de-cloaking are all gallery recipes — see the Workflow & recipe gallery.

Plus on-demand resources such as whisper://quota (your plan's current rate limits) and a set of built-in prompts for common investigation patterns. Once connected, you can ask things like:

• "Who hosts www.google.com? Show the IP, prefix, and ASN."
• "Find all hostnames resolving to 8.8.8.8."
• "What threat feeds list 185.220.101.1?"
• "Run the typosquat sweep for paypal.com."
• "Whose infrastructure is github.com, and is it dangerous?"
• "What are the real origin IPs behind www.cloudflare.com?"

For the full surface — all 6 tools, the resources, the prompts, and the gallery — see the MCP Reference.

Authentication is always required. There is no way to run the server without it — every request must carry credentials. You have two paths:

• OAuth 2.1 (recommended) — the server supports RFC 7591 Dynamic Client Registration with PKCE (S256), so most clients connect with just the URL and no manual key handling.
• Static API key — for clients that don't speak OAuth: send Authorization: Bearer <key> with a key from the Whisper console.

All requests are read-only — clients cannot mutate the graph.

Stay connected. Sessions last ~6 months and survive server deployments — you won't be asked to sign in again after an update. Refresh tokens (and your client's registration) persist server-side and rotate automatically, so an actively-used connection effectively stays signed in.

Claude Desktop

1. Open Settings → Connectors
2. Scroll to the bottom and click Add custom connector
3. Enter the URL https://mcp.whisper.security and click Add
4. Back in the Connectors list, click Connect next to whisper-graph — a browser window opens for OAuth
5. Sign in with your Whisper Security account to finish

Adding the connector does not authenticate you; the Connect button in step 4 is what starts the sign-in flow.

Remote connectors require a Pro, Max, Team, or Enterprise plan.

Claude.ai (Web)

Available on Pro, Max, Team, and Enterprise plans. Free accounts are limited to one custom connector; Team and Enterprise connectors are added by an organization owner.

1. Sign in at claude.ai and open Customize → Connectors
2. Click + and choose Add custom connector
3. Enter the URL https://mcp.whisper.security and click Add
4. The connector appears in the list — click Connect next to whisper-graph and complete the OAuth sign-in with your Whisper Security account
5. In a chat, enable it via the + button → Connectors → toggle on whisper-graph

Claude Code

claude mcp add --transport http whisper-graph https://mcp.whisper.security

Opens your browser for sign-in on first use. Options come before the server name; the URL is positional after the name. Scope options:

• --scope user -- all projects
• --scope project -- current project only
• --scope local -- this machine, this project (default)

Cursor

1. Open Settings → Tools & Integrations
2. Click Add new global MCP server
3. Paste:

{
  "mcpServers": {
    "whisper-graph": {
      "url": "https://mcp.whisper.security"
    }
  }
}

4. Save and restart Cursor For team-wide config, use .cursor/mcp.json in the project root instead.

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "whisper-graph": {
      "type": "http",
      "url": "https://mcp.whisper.security"
    }
  }
}

For user-level config (all projects), use Command Palette > MCP: Add Server.

Windsurf

1. Open Settings (Cmd+, on Mac, Ctrl+, on Windows)
2. Search for MCP
3. Click View raw config
4. Add:

{
  "mcpServers": {
    "whisper-graph": {
      "serverUrl": "https://mcp.whisper.security"
    }
  }
}

5. Save and restart Windsurf uses serverUrl instead of url.

Antigravity

1. Click ... at the top of the chat panel
2. Click MCP Servers > Manage MCP Servers > View raw config
3. Add to mcp_config.json:

{
  "mcpServers": {
    "whisper-graph": {
      "serverUrl": "https://mcp.whisper.security"
    }
  }
}

4. Go back to Manage MCP Servers and click refresh Config file: ~/.gemini/antigravity/mcp_config.json

ChatGPT

Custom MCP connectors require Developer Mode, available in beta on Pro, Plus, Business, Enterprise, and Edu plans (not on Free or Go). On Business and Enterprise, a workspace admin must enable it first.

1. Open Settings → Apps & Connectors → Advanced settings and turn on Developer mode
2. Go back to Settings → Apps & Connectors and click Create
3. Enter the URL https://mcp.whisper.security and submit
4. Open a new chat — when you first invoke the connector, ChatGPT prompts you to authenticate; complete the OAuth sign-in with your Whisper Security account

ChatGPT supports OAuth only — Bearer API keys are not exposed in the UI.

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.whisper-graph]
url = "https://mcp.whisper.security"

Then authenticate:

codex mcp login whisper-graph

Other clients

Any MCP client that speaks Streamable HTTP works.

npx mcp-remote https://mcp.whisper.security

Key concepts: MCP · Knowledge graph · Reconciled verdict.

Connecting through API key

OAuth is the recommended authentication path — the server supports RFC 7591 Dynamic Client Registration with PKCE (S256), so most clients can connect with just the URL and no manual key handling. Static API keys are the fallback for clients that don't speak OAuth. Either way, a request with no credentials is rejected — there is no anonymous mode and no switch to disable auth.

If your client doesn't support OAuth, you can authenticate with an API key instead.

1. Go to console.whisper.security and generate an API key
2. Add a headers block to your client's MCP config with Authorization: Bearer YOUR_API_KEY

For Cursor, Claude Code, and other clients that follow the standard mcpServers shape:

{
  "mcpServers": {
    "whisper-graph": {
      "url": "https://mcp.whisper.security",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

For VS Code (.vscode/mcp.json):

{
  "servers": {
    "whisper-graph": {
      "type": "http",
      "url": "https://mcp.whisper.security",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

For Windsurf and Antigravity (serverUrl instead of url):

{
  "mcpServers": {
    "whisper-graph": {
      "serverUrl": "https://mcp.whisper.security",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

For OpenAI Codex (~/.codex/config.toml):

[mcp_servers.whisper-graph]
url = "https://mcp.whisper.security"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }

Claude.ai and Claude Desktop's connector UI only expose OAuth — they do not support custom Bearer headers. To use an API key with these clients, point them at the mcp-remote STDIO bridge instead:

npx mcp-remote https://mcp.whisper.security --header "Authorization: Bearer YOUR_API_KEY"

Keep your API key out of version control.

Once the connector is registered, ask the assistant:

"List the WhisperGraph node labels."

The MCP client should invoke the explain_schema tool (no argument) and return the label catalogue — 39 labels (HOSTNAME, IPV4, IPV6, ASN, ANNOUNCED_PREFIX, FEED_SOURCE, TOR_RELAY, TLS_FINGERPRINT, VENDOR, …) with live counts and scale. If you instead get an apology or a hand-written list of what the assistant thinks the schema looks like, the tool isn't connected — recheck the connector URL and re-authenticate.

To confirm a fully-featured connection, check the connector surface in your client's MCP/tools panel. A complete connection exposes the 6 tools — query, explain_indicator, explain_schema, read_docs, list_workflows, run_workflow. If you see fewer, the client may be caching an older connection — disconnect and reconnect.

As a second test, try a one-call investigation:

"Run the typosquat sweep for paypal.com."

This should invoke run_workflow with the tmpl-brand-variants recipe and return registered lookalike domains — along with the evidence trail showing the exact Cypher behind each step.

Connection confirmed? Now feel the value — ask a real question instead of a schema dump:

Investigate 185.220.101.42 — who owns it, where is it hosted, is it a Tor exit, and what else is nearby?

The assistant answers in plain language, usually with a single run_workflow call against a recon/threat recipe (resolving and scoring the address, pulling a reconciled threat verdict with explain_indicator, and listing co-hosted infrastructure on the same prefix) — a multi-source investigation collapsed into one tool call instead of five round-trips. Every step comes back with the Cypher that produced it in the evidence block.

A couple more starting points to try:

Map the infrastructure behind paypal.com — registrant, nameservers, hosting ASN, and any registered lookalike domains.

What does the graph know about AS13335 — how many prefixes does it announce, and where is it physically present?

Live numbers will differ. WhisperGraph reflects the current state of the internet, not a fixed snapshot — verdicts, counts, and co-tenants change as feeds and routing refresh.

What the free tier includes

AI Context (MCP) is available on every plan, including the free tier — sign up on the Console (no credit card) for a monthly query allowance suitable for evaluation; paid plans raise the quotas. To check your current limits at any time, ask the assistant to read the whisper://quota resource:

Read the whisper://quota resource and tell me my plan and remaining quota.

Most connection problems fall into one of these buckets. For the full query-time error model (every errorCode and what it means), see the MCP Reference.

• MCP Reference — every tool, resource, and prompt the connector exposes, the evidence model, and the schema-introspection pattern AI agents should use before writing queries.
• Workflow & recipe gallery — discover and run the shared investigation playbooks with list_workflows / run_workflow.
• Cypher API Reference — if you'd rather call the graph directly over REST without MCP.

• Open a ticket: console.whisper.security/support
• Email: support@whisper.security
• Security disclosures: security@whisper.security