Agents & MCP
Ground AI agents in the live WhisperGraph over MCP: 7 tools, all read-only, a shared workflow gallery, and evidence behind every answer.
On this page (6)
Agents & MCP Documentation
A flat lookup API returns the same nothing for a host no feed has ever seen and for a host that is positively known clean, and a language model fills that gap by guessing. That is the failure mode this connector exists to fix. Verdicts from WhisperGraph carry a coverage block, so an agent can tell "not listed at this granularity" apart from "safe", and every query and run_workflow result ships an evidence block with the exact Cypher that ran, the row count, and the timing — so the agent can cite the query behind each claim instead of asserting one.
The second problem is staleness. An assistant answering infrastructure questions from its training data is working from a snapshot that ages by the day: DNS records move, and threat feeds add and drop indicators continuously. Whisper's MCP server at https://mcp.whisper.security connects any MCP-capable client to the live graph — over 7.4 billion nodes and 39.4 billion edges — so the agent runs the lookup instead of recalling one.
What the server offers
The server speaks MCP over streamable HTTP and advertises 7 tools, 4 resources, and 10 prompts. Every tool reads; none writes. The surface is provably read-only — write and admin Cypher is rejected before it reaches the database — so nothing an agent asks through this connector can change the graph.
The seven tools
| Tool | What it does |
|---|---|
query | Run read-only Cypher; returns columns, rows, statistics, and the evidence block. The primary tool. |
explain_indicator | Threat verdict for one or many indicators — IP, hostname, CIDR, or ASN: score, level, factors, sources, and coverage. |
explain_schema | The schema on demand: the full label catalogue, or one label's properties, edges, and a sample traversal. |
read_docs | List, search, or fetch these docs as Markdown, pulled on demand instead of held in always-on context. |
list_workflows | Search the workflow gallery; each result carries its full parameter space, so an agent can run any variant. |
run_workflow | Run one or more gallery workflows by slug in a single call, with per-step results and an evidence trail. |
identify | Whose infrastructure a set of hostnames belongs to — vendor and role attribution, deliberately not a threat verdict. |
Read-only is the whole surface
No tool on this server writes, no scope unlocks one, and there is no contribution path. The guarantee is enforced rather than asserted: the engine is read-only, and a pre-check refuses write and admin Cypher — and mutating CALL procedures — before execution, including under an EXPLAIN prefix. whisper.submit and whisper.watch do exist as procedures on the graph engine; no tool here calls them, and the pre-check denies them by name. Every tool attests readOnlyHint: true, destructiveHint: false, and the attestation is exhaustive — a client can turn those hints straight into permissions.
Found bad data or a false positive? Open a ticket or email support@whisper.security.
Every deployment advertises the same seven tools. There is no profile or tier that adds or removes one, so tools/list is the contract wherever you connect. The full surface, with input shapes and response fields, is in the Reference; the scope-by-scope breakdown and the data-handling summary are in Setup.
The four resources cover the full schema (whisper://schema/full), live graph statistics (whisper://stats), your own service context (whisper://quota), and the server descriptor (whisper://server). The 10 prompts are generated from the workflow gallery: each wraps one run_workflow call for a flagship investigation, from indicator enrichment to typosquat hunting. Two gallery workflows — attack-surface and indicator — are deliberately not advertised as prompts, because both run longer than a client will wait on a tool call; they stay reachable through run_workflow by slug, where you pick the entity and own the latency.
What it cannot tell you
This reads Whisper's map of the public internet. It does not read your logs, your endpoints, your mail, or your 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.
And a clean verdict is a statement about coverage, not about safety. level: NONE means "not listed at this granularity"; band: UNKNOWN means "never seen". A domain registered this morning has no feed history and will read clean — expected behaviour, not an all-clear.
Read
coveragebeforeband. 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.explaindoes not returncoverageat all. Full contract: Coverage — what we looked at.
Connect
Authentication is always required — there is no anonymous mode: sign in and an API key is created for you automatically, then add the server to your client. In Claude Code:
claude mcp add --transport http whisper-graph https://mcp.whisper.security \
--header "Authorization: Bearer YOUR_API_KEY"
Replace YOUR_API_KEY before you run it — claude mcp add only writes config, so it succeeds on the placeholder and the failure surfaces later, inside the agent, as a 401.
Interactive clients such as Claude Desktop can skip the key and sign in through OAuth 2.1 instead. Setup has working configs for Claude, Claude Code, Cursor, VS Code, ChatGPT, and generic MCP clients.
Read these in order
- Setup — connect your client (about ten minutes), read the OAuth scope table, and see how your data is handled.
- Your first investigation — one alert worked end to end, including the pivot the score never suggests and the step where the conclusion gets falsified.
- Workflow gallery — the shared investigation library behind
list_workflowsandrun_workflow: what to run, and what it returns. - Reference — every tool, resource and prompt, with input shapes, response fields, and the evidence model.
- Query language — the error envelope, the nine safety rules, self-correction, and the procedures callable inside
query.
Agents that need their own key without a human in the loop: Agent Sign-up. Agents that speak plain HTTP can skip MCP entirely and call the Cypher API with an X-API-Key header.