Connect an AI agent (MCP server)
Spider exposes a remote Model Context Protocol server at
https://<your-spider>/mcp. Agents such as claude.ai, Claude Desktop, ChatGPT and Claude Code connect
to it with OAuth: no binary to install, no API key to distribute.
Requirements
- The
MCPlicence capability (TEAM tier and above). - Helm:
customers.oauth.enabled: trueandglobal.flips.mcp: true. - For claude.ai and ChatGPT: the instance must be reachable from the internet.
Connect
Find the URL in the Analysis UI: Settings → Connected apps → Connect an AI agent.
| Client | How |
|---|---|
| claude.ai / Claude Desktop | Settings → Connectors → Add custom connector → paste the URL |
| ChatGPT | Settings → Apps & Connectors → Developer mode → Create → paste the URL |
| Claude Code | claude mcp add --transport http spider https://<your-spider>/mcp |
The first call opens Spider's consent screen. Approved agents are listed on the same Settings tab, where one click revokes them; a revoked agent is cut off within 30 seconds.
Which agent platforms may connect, and how they identify themselves (dynamic registration or Client ID Metadata Documents), is an administrator decision: see Connecting agents with OAuth.
What an agent can do
| Tool | Purpose |
|---|---|
spider_whoami, spider_list_teams | Identity, and the teams you can read through |
spider_fields | Field reference for a data type - agents call it before querying |
spider_search, spider_stats, spider_outliers, spider_aggs | Query HTTP, PostgreSQL, MySQL, Redis, gRPC, Kafka, DNS, MQTT, MongoDB, SSE/WebSocket, TCP, packets, network usage, hosts |
spider_get | One document, optionally with truncated content |
spider_topic_map | Pub/sub map of MQTT, Redis or Kafka traffic: who publishes to which topic, who receives it, and the flagged problems |
spider_mongo_cursor | Summary of a whole MongoDB cursor: batches, documents, wall and server time, outcome |
spider_resources | Whisperers, controllers, gociphers, users, attachments |
spider_link | A private Network-View link |
spider_list_namespaces, spider_list_workloads, spider_list_sidecars | Kubernetes discovery |
spider_attach, spider_detach | Time-boxed capture - only when enabled by the operator |
spider_capture_plan, spider_capture_status, spider_suggest_enrichment, spider_link_ids | Capture Advisor, read tools - need the ADVISOR licence |
spider_capture_probe, spider_capture_apply, spider_capture_restore, spider_apply_enrichment, spider_apply_link_ids | Capture Advisor, write tools - only when enabled by the operator |
An agent acts with the full rights of the user who approved it, limited to the whisperers that user owns. To read through a team, the agent passes that team's id as
team on each call (spider_list_teams lists them); there is no session state. The server speaks MCP
2026-07-28, 2025-11-25 and 2025-06-18.
Capture Advisor tools
Nine tools drive the Capture Advisor, the same service behind the capture-setup wizard of the Analysis UI and the spider capture and spider templates commands of the Spider CLI. They need the ADVISOR licence capability (TEAM tier and above) and global.flips.advisor; see Installing the Capture Advisor. Arguments are in snake_case, and every tool accepts team like the other tools.
| Tool | Kind | Purpose |
|---|---|---|
spider_capture_plan | read | Plan the capture of a namespace: workloads to attach, ports and protocols to parse, configuration diff |
spider_capture_status | read | Show a probe or apply run (run_id) |
spider_suggest_enrichment | read | Template and tag candidates for a whisperer |
spider_link_ids | read | Business ids shared by several protocols or services, with one tag rule per location |
spider_capture_probe | write | Attach briefly to confirm the protocol of uncertain ports |
spider_capture_apply | write | Write the plan to a whisperer, attach it and observe for a window |
spider_capture_restore | write | Cancel a probe or apply run and undo it |
spider_apply_enrichment | write | Write chosen template and tag candidates to a whisperer configuration |
spider_apply_link_ids | write | Write chosen link-ids rules, across protocols, in one atomic request |
The write tools are registered only when mcpServer.captureControl.enabled is on, the flag that also gates spider_attach and spider_detach; there is no separate Advisor flag. They are distinct tools so your agent's own approval prompt applies to each one. With the flag off they are absent from the tool list.
- Capture arguments (
spider_capture_plan,spider_capture_probe,spider_capture_apply):controllerandnamespace, and exactly one ofwhisperer_id(an existing INTERFACE whisperer) ornew_whisperer_name. Optional:start_dateandstop_date(window of traffic read for the plan, ISO 8601 or relative like-1h; not onspider_capture_apply),include_dns(also plan, or for apply capture, DNS),exclude_workloads(list ofnamespace:kind:name) andexclude_strict.port_protocols(plan and apply, list of{workload, port, protocol}) gives an unidentified port its protocol by hand, only when the user knows what runs there; it never overrides an identified port (a non-matching entry comes back inportProtocolsIgnored).probe_run(plan and apply) folds a finished probe run of the same namespace into the plan. spider_capture_probealso takesports(restricts the probe to ports of the plan, never adds one) andttl(ISO 8601, defaulted and capped by the server). It injects ephemeral containers into workload pods: call it only after the user reviewed the plan.spider_capture_applyalso takeswindow(ISO 8601 duration of the observation window, bounded by the server),short_life(store the observed data under the short-life retention policy) andconfirm. Withoutconfirm: trueit is a dry run: the diff and the operations are returned and nothing is written; a dry-run answer too large for the response budget is refused, never trimmed.spider_capture_statusis not strictly read-only: reading a run past its window settles it (the observation settings are put back).spider_capture_restoretakesrun_id; an unknown run id and another user's run id give the same answer.spider_suggest_enrichmenttakeswhisperer, and optionallyprotocol(http,psql,redis,mysql,kafka,mqtt,mongo,grpc),start_date,stop_dateandmax_coms. Its whole answer is labelled as untrusted content, since candidates and examples come from captured traffic.spider_apply_enrichmenttakeswhisperer,protocol,position, thecandidatesto append (eachkindandruleexactly as returned by the suggestion) andconfirm. Withoutconfirm: trueit is a server dry run. Review proposals that replace existing rules cannot be applied through MCP: use the CLI.spider_link_idstakeswhisperer,start_date,stop_dateandmax_coms; the answer is untrusted content capped at 64 KiB.spider_apply_link_idstakeswhisperer, therules(eachprotocol,kind,rule, and optionallyconceptandnameSource),position(appendorprepend) andconfirm. Renaming a concept means giving the same newnameto every rule of it. Withoutconfirm: trueit is a server dry run; with it, one all-or-nothing write.- Advisor answers are bounded like the other tools. Limits that protect the cluster (attachments per plan, probe lifetime, window bounds, one probe per whisperer) are enforced by the Advisor and cannot be loosened by the tool.
Operator settings
| Helm value | Default | Effect |
|---|---|---|
global.flips.mcp | false | Deploys the MCP server and its routes |
mcpServer.captureControl.enabled | false | Registers spider_attach/spider_detach and the five Capture Advisor write tools |
global.flips.advisor | false | Deploys the Advisor service the Capture Advisor tools call; needs the ADVISOR licence |
mcpServer.captureControl.defaultTtl / maxTtl | PT30M / PT2H | Capture duration default and cap; the controller detaches automatically (requires Controller 3.2.1 or later) |
Content (request/response bodies, Redis values, Kafka records) is never returned by searches, only by
spider_get on request, truncated and labelled as untrusted data. Set allowPayloads: false in the
mcp Config document to forbid content through MCP entirely.
Tokens are checked against the server's own resource identifier (RFC 8707). By default a token with no
audience, from a client that never sent resource, is still accepted; set requireResourceBinding: true
in the mcp Config document to accept only tokens bound to this server. A token bound to a different
resource is always refused.
Security notes
- Captured traffic can contain text written by anyone. Agents are told to treat it as data, and the tools that change state are narrow: links are private only, captures are off by default and always time-boxed.
- Public links remain available from the Analysis UI and the
spiderCLI, not through MCP.