Setup

WhisperGraph MCP gives an AI assistant read access to WhisperGraph — an internet-infrastructure graph of over 7.4 billion nodes and 39 billion edges spanning eight linked layers:

What it is for. Security investigation: triage an indicator, map a domain's attack surface, pivot a WHOIS registrant to the rest of their estate, find registered lookalikes of a brand, grade a network's routing security. The value is in the joins — one traversal crosses layers that are separate products everywhere else.

What it does to your systems: nothing. The connector reads a graph Whisper already holds. It does not scan, probe, or connect to any host you name; it has no access to your network, files, or mail; and naming a domain or IP in a question never causes traffic to it.

What it cannot tell you. This reads Whisper's map of the public internet. It does not read your logs, endpoints, mail or network traffic, so it can tell you what a domain or IP is — never whether anything in your environment contacted it. Pair it with your SIEM or EDR for that half of the question.

What it writes: nothing. Every tool here reads; there is no write tool, no write scope, and no contribution path. The free-form query path refuses write and admin Cypher, and mutating procedures, before execution — so the guarantee holds for the one place a caller supplies Cypher, not just for the prepared tools. To report bad data or a false positive, open a ticket or email support@whisper.security.

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.

Claude.ai (Web)

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 on Team and Enterprise

The steps above are the individual path. On a Team or Enterprise organization, only an Owner can add a custom connector, and it is added once for the whole org — a member who follows the steps above will not find an Add custom connector button.

1. An Owner opens Organization settings → Connectors, clicks Add, hovers Custom, chooses Web, and enters https://mcp.whisper.security. OAuth client credentials can be supplied under Advanced settings if you registered a client manually; they are not required, because the server supports Dynamic Client Registration.
2. Each member then opens Customize → Connectors, finds whisper-graph marked Custom, and clicks Connect to complete their own OAuth sign-in. Each member authenticates individually, so each member's queries run under their own Whisper credential.

Claude Code

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

Then run /mcp inside a session (or claude mcp login whisper-graph from the shell) to complete the OAuth sign-in in your browser. 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

Cursor reads MCP servers from a JSON file. Create or edit ~/.cursor/mcp.json for all projects (or .cursor/mcp.json in the project root for one project) and add:

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

Then open Customize and enable whisper-graph. Team-wide configuration is managed from the Cursor Dashboard → Integrations & MCP.

VS Code (GitHub Copilot)

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, which is in beta and is not exposed on every ChatGPT account. On a workspace account, an admin has to turn it on before you can.

1. Open Settings → Security and login and turn on Developer mode
2. Go 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

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. Sign in to the console and generate an API key
2. Add a headers block to your client's MCP config with Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your real key in every snippet below. claude mcp add and its equivalents only write configuration — they succeed on the literal placeholder, and the failure surfaces later, inside the assistant, as HTTP 401 {"error":"Invalid API key"}.

For Claude Code, pass the header as a flag when adding the server:

claude mcp add --transport http whisper-graph https://mcp.whisper.security \
  --header "Authorization: Bearer YOUR_API_KEY"

For Cursor 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 — 40 labels (HOSTNAME, IPV4, IPV6, ASN, ANNOUNCED_PREFIX, PREFIX, ORGANIZATION, REGISTRAR, TOR_RELAY, …) 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 the connection, check the connector surface in your client's MCP/tools panel. A session against https://mcp.whisper.security advertises 7 tools, all read-only:

Every one is annotated readOnlyHint: true, destructiveHint: false, so a client that maps annotations onto permissions can grant the whole connector without a write prompt. Alongside the tools: 4 resources (whisper://schema/full, whisper://stats, whisper://quota, whisper://server) and 10 investigation prompts.

Every deployment advertises the same seven. There is no profile, tier, or setting that adds or removes a tool, so a count other than seven means the connection itself is wrong — most often a client holding an older session, which a disconnect and reconnect clears. tools/list is the contract; read it in your client rather than assuming.

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

"Run the typosquat sweep for paypal.com."

This should invoke run_workflow with the typosquat workflow and return registered lookalike domains — along with the evidence trail showing the exact Cypher behind each step.

The connector advertises its scopes in /.well-known/oauth-authorization-server under scopes_supported; your client shows the ones it requested on the consent screen.

A client that asks for nothing in particular is granted mcp:read offline_access.

Ask for offline_access explicitly. The 401 challenge advertises a single scope — WWW-Authenticate: Bearer scope="mcp:read" — so a client that copies the challenge scope verbatim receives no refresh token, and is sent back through the browser every time the access token expires. If your client lets you set the requested scope, set it to mcp:read offline_access. If it re-authorizes you roughly hourly, this is why.

Access tokens live 1 hour; refresh tokens live up to 180 days and rotate on every use, so an actively used connection renews itself and never asks you to sign in again. A connection left idle for the whole window expires.

Every connection is read-only, whichever scope you ask for. There is no read-only variant to request because there is no other kind — mcp:read offline_access is both the default grant and the whole surface.

Static API keys are not scope-limited: a key carries whatever its tenant is entitled to.

A bounded result does not announce itself in the prose. The server can return fewer rows than the LIMIT you wrote, and the rows it does return look exactly like a whole answer. It says so in fields rather than in text: read truncated and autoLimited on the response before you conclude you have the full set. Query language covers both, and the rest of the self-correction surface.

An unrecognised key behaves differently on each surface, and only one of them tells you. On this connector an unrecognised bearer is rejected outright — HTTP 401 {"error":"Invalid API key"}. On the graph REST endpoint the same key is not rejected: the request is served as though you had sent no key at all. So an expired or revoked key shows up there as a traversal that ran yesterday and comes back refused today, never as an auth error. If that happens, suspect the key before you rewrite the query.

A verdict of NONE means "not listed at this granularity". It never means safe. A domain registered this morning has no feed history and will read clean; that is expected behaviour, not an all-clear.

Two fields say different things and both look like "nothing found":

• level: NONE — the indicator exists in the graph and is not listed in any feed.
• band: UNKNOWN — the engine has never seen this host at all.

Gate your logic on the coverage block, never on level or band alone. coverage.scope: "node-only" means the verdict covers the address itself — not its prefix, and not the ASN that routes it. And on a CIDR or an ASN, do not read score — it is scoped to a single indicator and does not carry a range's value. The row hands you the right fields instead: recoveredScore, scoreUnavailable, and a verdictDisagreement naming the column to read.

Read coverage before band. Only known-clean — coverage: known-clean. In coverage, no malicious evidence. licenses the word "clean"; no-data — coverage: no-data. Not in coverage. This is not a verdict — nothing was looked at. means unknown, which is a different thing again; malicious-evidenced — coverage: malicious-evidenced. In coverage, with positive evidence of malice. and ambiguous — coverage: ambiguous. In coverage, and the evidence points both ways. mean there is evidence, whatever the band says. whisper.explain does not return coverage at all. Full contract: Coverage — what we looked at.

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, name servers, 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?

When you want to see one worked end to end — including the pivot the score never suggests and the step where the conclusion gets falsified — read Your first investigation.

The Privacy Policy is authoritative; this is the connector-specific summary.

What leaves your client. Only what the assistant puts into a tool call — the domains, IPs, ASNs, prefixes, hashes or Cypher you asked about — plus your bearer credential. Conversation that never reaches a tool call never reaches Whisper.

What is recorded. One audit entry per request: an identifier for the calling account, the tool called, the request path and timestamp, a correlation identifier, the response status, execution time and result size, the outcome of the query-safety validator, the plan tier, and the Cypher text with string literals replaced by ?, so the indicator values, hostnames and addresses inside your query do not enter the log stream. Your IP address and user-agent are recorded at our edge proxy, not by the connector.

How long. Audit and operational logs are retained for 30 days, then permanently deleted from production systems.

What is not done with it. Your queries, results, and conversation history are not used to train Whisper machine-learning models and are not sold. No tool on this connector sends your input to a third-party model provider — your own MCP client is the only model in the loop.

What the graph holds. Public and licensed internet-infrastructure data: DNS, BGP, WHOIS, GeoIP, certificate transparency, threat feeds. No customer-uploaded content — there is no way to upload any.

The read-only guarantee. Nothing an agent does through this connector writes to the graph, under any scope and on any deployment. There is no write tool and no write scope, and the free-form query path — the only place a caller supplies Cypher — refuses write and admin clauses and mutating CALL procedures before execution, including under an EXPLAIN prefix. whisper.submit and whisper.watch are real procedures on the graph engine, but no tool on this server calls them and that same pre-check denies them by name. Every tool attests readOnlyHint: true, destructiveHint: false, and the attestation covers the whole surface.

Sub-processors. Identity, storage, hosting, edge, logging, GeoIP, billing and support processors are named in the Privacy Policy.

Removing your data. Revoke the connector in your client and delete the API key in the console. For audit-log deletion inside the 30-day window, email privacy@whisper.security.

• Support docs: whisper.security/docs/reference/support — start here; no sign-in needed.
• Email: support@whisper.security — include the x-request-id from the response you are asking about
• Security disclosures: security@whisper.security — metadata at /.well-known/security.txt