# Setup > Connect an MCP client to WhisperGraph: Claude's Connectors Directory, config for Claude Code, Cursor, VS Code, Windsurf and ChatGPT, OAuth or API key. *Source: https://www.whisper.security/docs/ai/mcp/setup* --- This page walks you through connecting an MCP client to WhisperGraph MCP. For the full tool-by-tool surface and example questions, see the [MCP Reference](/docs/ai/mcp/reference). On Claude — web, Desktop and mobile — you do not need the endpoint at all: WhisperGraph is listed in the [Claude Connectors Directory](https://claude.ai/directory/whisper-graph) and connects in three clicks. Every other client takes the URL `https://mcp.whisper.security`. ## What this connector does WhisperGraph MCP gives an AI assistant read access to WhisperGraph — an internet-infrastructure graph of 7.5B nodes and 39.7B edges spanning seven linked layers: | Layer | What is in it | |-------|---------------| | Physical | Submarine cables, cable landings, facilities, internet exchanges, CDN PoPs, cloud regions | | Network | ASNs, announced and registered prefixes, BGP paths and peering, RPKI ROAs | | Addressing | IPv4, IPv6, CIDR blocks, GeoIP city and country | | Naming and DNS | Hostnames, domain hierarchy, TLDs, nameservers, DNSSEC, certificate transparency | | Ownership | Organizations, WHOIS and RDAP registrants, registrars | | Email | MX, the full SPF chain, DMARC | | Threat | Feeds and scores, threat actors, ATT&CK techniques, Tor relays, TLS fingerprints | **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](/docs/support) or email [support@whisper.security](mailto:support@whisper.security). ## Set up ### Claude (web, Desktop and mobile) Whisper is listed in the **Claude Connectors Directory** as **WhisperGraph**, so on Claude there is no URL to type and nothing to configure. 1. Open **Customize → Connectors** 2. Click **+** and choose **Browse connectors** 3. Find **WhisperGraph** and click **Connect** — the OAuth sign-in runs from there 4. Sign in with your [Whisper Security](https://console.whisper.security/sign-in?redirect_url=https%3A%2F%2Fwww.whisper.security%2Fdocs%2Fai%2Fmcp%2Fsetup) account; you land back with the connector enabled 5. In a chat, switch it on via the **+** button → **Connectors** The listing lives at [claude.ai/directory/whisper-graph](https://claude.ai/directory/whisper-graph) and is readable before you sign in to anything: it names the connector's endpoint and every one of the seven tools, so you can inspect the whole surface before you connect it. **What the Community label means.** Claude marks WhisperGraph a **Community** connector and shows a notice saying that connectors in that category pass automated review but are not verified by Anthropic. That is the default state of a new listing rather than a finding about this server — the promotion to *Verified* is Anthropic's to make and cannot be applied for. What the notice asks you to do is check who you are connecting to, and the listing is built for exactly that: the surface is read-only end to end, and all seven tool names are published on the listing for inspection before you connect. Remote connectors are never configured through `claude_desktop_config.json`. That file configures local (stdio) servers only — a remote connection is opened from Anthropic's infrastructure rather than from your machine, so it is managed in the UI. #### Claude on Team and Enterprise An organization **Owner** enables the connector once for the whole org from **Settings → Connectors**. Each member then signs in individually from their own **Customize → Connectors**, so every member's queries run under their own Whisper credential. #### Or add it as a custom connector The directory listing above is the supported path on Claude. Adding the endpoint by hand is the fallback — for a client build with no directory browser, or to point at a deployment other than production. 1. Open **Customize → Connectors** (on Claude Desktop, **Settings → Connectors**) 2. Click **+** and choose **Add custom connector** 3. Enter the URL `https://mcp.whisper.security` and click **Add** 4. Back in the list, click **Connect** next to *whisper-graph* — a browser window opens for OAuth 5. Sign in with your [Whisper Security](https://console.whisper.security/sign-in?redirect_url=https%3A%2F%2Fwww.whisper.security%2Fdocs%2Fai%2Fmcp%2Fsetup) account to finish Adding the connector does not authenticate you; the **Connect** button in step 4 is what starts the sign-in flow. 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. Two constraints belong to this route alone and not to the directory listing: on an organization only an Owner may add a custom connector, and Claude restricts how many custom connectors an account may add at all. Anthropic moves these menu paths independently of this page. If a step does not match what you see, the Claude Help Center has the current one. ### Claude Code ```bash 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: ```json { "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: ```json { "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: ```json { "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`: ```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](https://console.whisper.security/sign-in?redirect_url=https%3A%2F%2Fwww.whisper.security%2Fdocs%2Fai%2Fmcp%2Fsetup) account ChatGPT supports OAuth only — Bearer API keys are not exposed in the UI. ### OpenAI Codex Add to `~/.codex/config.toml`: ```toml [mcp_servers.whisper-graph] url = "https://mcp.whisper.security" ``` Then authenticate: ```bash codex mcp login whisper-graph ``` ### Other clients Any MCP client that speaks Streamable HTTP works. | Transport | URL | Notes | |-----------|-----|-------| | Streamable HTTP | `https://mcp.whisper.security` | The only transport, and what `/.well-known/mcp.json` advertises. On `initialize` the server offers every protocol revision it supports and settles on the one your client asks for, up to `2025-11-25`, so a client on an older revision still connects. | For STDIO-only clients, use the `mcp-remote` bridge: ```bash npx mcp-remote https://mcp.whisper.security ``` Need the server to run on your own machine over stdio? The CLI ships one: [Local MCP server](/docs/cli/mcp). --- ### 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](https://console.whisper.security/sign-in?redirect_url=https%3A%2F%2Fwww.whisper.security%2Fdocs%2Fai%2Fmcp%2Fsetup) and generate an API key 2. Add a `headers` block to your client's MCP config with `Authorization: Bearer YOUR_API_KEY`. An `X-API-Key: YOUR_API_KEY` header is accepted as well **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: ```bash 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: ```json { "mcpServers": { "whisper-graph": { "url": "https://mcp.whisper.security", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` For VS Code (`.vscode/mcp.json`): ```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`): ```json { "mcpServers": { "whisper-graph": { "serverUrl": "https://mcp.whisper.security", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` For OpenAI Codex (`~/.codex/config.toml`): ```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: ```bash npx mcp-remote https://mcp.whisper.security --header "Authorization: Bearer YOUR_API_KEY" ``` Keep your API key out of version control. ## Validating your connection 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 — **42 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**: | Group | Tools | |-------|-------| | Graph & docs | `query`, `explain_indicator`, `explain_schema`, `read_docs`, `list_workflows`, `run_workflow` | | Host identity | `identify` | Every one is annotated `readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true`, 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. ## OAuth scopes 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. | Scope | What it grants | |-------|----------------| | `mcp:read` | All seven tools: `query` (read-only Cypher), `explain_indicator`, `explain_schema`, `read_docs`, `list_workflows`, `run_workflow`, `identify`. Also the four resources (`whisper://schema/full`, `whisper://stats`, `whisper://quota`, `whisper://server`) and the 10 prompts. That is the entire surface, and nothing on it can change any state. | | `offline_access` | A refresh token, so the connection survives without sending you back through the browser. No additional data access. | | `mcp:query` | Also advertised — a legacy name that grants the same whole surface. Ask for `mcp:read`. | 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. ## Two failures that do not look like failures **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](/docs/ai/mcp/query) 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. ## How to read the answer 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. On a network or ASN row, `score` is an aggregate over the whole range and `factors[]` shows how it was built, so read both. When the engine has evidence but no aggregate to report, the row says so with `score: null` and `level: UNSCORED` rather than a clean-looking zero. For an ASN the separate `reputation` block is a 0–100 scale where higher is better, never a threat score. A low or missing `score` on a CIDR or ASN is not a clean network on its own. > **Read `coverage` before `band`.** Only `known-clean` licenses the word "clean"; `no-data` means > *unknown*, which is a different thing again; `malicious-evidenced` and `ambiguous` mean there is > evidence, whatever the band says. > Full contract: [Coverage — what we looked at](/docs/whisper-graph/procedures/coverage). ## Your first investigation 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](/docs/ai/mcp/investigation). ## Data handling The [Privacy Policy](/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](/privacy-policy). **Removing your data.** Revoke the connector in your client and delete the API key in [the console](https://console.whisper.security/sign-in?redirect_url=https%3A%2F%2Fwww.whisper.security%2Fdocs%2Fai%2Fmcp%2Fsetup). For audit-log deletion inside the 30-day window, email [privacy@whisper.security](mailto:privacy@whisper.security). ## Support - **Support docs:** [whisper.security/docs/support](/docs/support) — start here; no sign-in needed. - **Email:** [support@whisper.security](mailto:support@whisper.security) — include the `x-request-id` from the response you are asking about - **Security disclosures:** [security@whisper.security](mailto:security@whisper.security) — metadata at [`/.well-known/security.txt`](https://mcp.whisper.security/.well-known/security.txt)