Skip to main content

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 MCP licence capability (TEAM tier and above).
  • Helm: customers.oauth.enabled: true and global.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.

ClientHow
claude.ai / Claude DesktopSettings → Connectors → Add custom connector → paste the URL
ChatGPTSettings → Apps & Connectors → Developer mode → Create → paste the URL
Claude Codeclaude 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​

ToolPurpose
spider_whoami, spider_list_teamsIdentity, and the teams you can read through
spider_fieldsField reference for a data type - agents call it before querying
spider_search, spider_stats, spider_outliers, spider_aggsQuery HTTP, PostgreSQL, MySQL, Redis, gRPC, Kafka, DNS, MQTT, MongoDB, SSE/WebSocket, TCP, packets, network usage, hosts
spider_getOne document, optionally with truncated content
spider_topic_mapPub/sub map of MQTT, Redis or Kafka traffic: who publishes to which topic, who receives it, and the flagged problems
spider_mongo_cursorSummary of a whole MongoDB cursor: batches, documents, wall and server time, outcome
spider_resourcesWhisperers, controllers, gociphers, users, attachments
spider_linkA private Network-View link
spider_list_namespaces, spider_list_workloads, spider_list_sidecarsKubernetes discovery
spider_attach, spider_detachTime-boxed capture - only when enabled by the operator
spider_capture_plan, spider_capture_status, spider_suggest_enrichment, spider_link_idsCapture Advisor, read tools - need the ADVISOR licence
spider_capture_probe, spider_capture_apply, spider_capture_restore, spider_apply_enrichment, spider_apply_link_idsCapture 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.

ToolKindPurpose
spider_capture_planreadPlan the capture of a namespace: workloads to attach, ports and protocols to parse, configuration diff
spider_capture_statusreadShow a probe or apply run (run_id)
spider_suggest_enrichmentreadTemplate and tag candidates for a whisperer
spider_link_idsreadBusiness ids shared by several protocols or services, with one tag rule per location
spider_capture_probewriteAttach briefly to confirm the protocol of uncertain ports
spider_capture_applywriteWrite the plan to a whisperer, attach it and observe for a window
spider_capture_restorewriteCancel a probe or apply run and undo it
spider_apply_enrichmentwriteWrite chosen template and tag candidates to a whisperer configuration
spider_apply_link_idswriteWrite 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): controller and namespace, and exactly one of whisperer_id (an existing INTERFACE whisperer) or new_whisperer_name. Optional: start_date and stop_date (window of traffic read for the plan, ISO 8601 or relative like -1h; not on spider_capture_apply), include_dns (also plan, or for apply capture, DNS), exclude_workloads (list of namespace:kind:name) and exclude_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 in portProtocolsIgnored). probe_run (plan and apply) folds a finished probe run of the same namespace into the plan.
  • spider_capture_probe also takes ports (restricts the probe to ports of the plan, never adds one) and ttl (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_apply also takes window (ISO 8601 duration of the observation window, bounded by the server), short_life (store the observed data under the short-life retention policy) and confirm. Without confirm: true it 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_status is not strictly read-only: reading a run past its window settles it (the observation settings are put back). spider_capture_restore takes run_id; an unknown run id and another user's run id give the same answer.
  • spider_suggest_enrichment takes whisperer, and optionally protocol (http, psql, redis, mysql, kafka, mqtt, mongo, grpc), start_date, stop_date and max_coms. Its whole answer is labelled as untrusted content, since candidates and examples come from captured traffic.
  • spider_apply_enrichment takes whisperer, protocol, position, the candidates to append (each kind and rule exactly as returned by the suggestion) and confirm. Without confirm: true it is a server dry run. Review proposals that replace existing rules cannot be applied through MCP: use the CLI.
  • spider_link_ids takes whisperer, start_date, stop_date and max_coms; the answer is untrusted content capped at 64 KiB. spider_apply_link_ids takes whisperer, the rules (each protocol, kind, rule, and optionally concept and nameSource), position (append or prepend) and confirm. Renaming a concept means giving the same new name to every rule of it. Without confirm: true it 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 valueDefaultEffect
global.flips.mcpfalseDeploys the MCP server and its routes
mcpServer.captureControl.enabledfalseRegisters spider_attach/spider_detach and the five Capture Advisor write tools
global.flips.advisorfalseDeploys the Advisor service the Capture Advisor tools call; needs the ADVISOR licence
mcpServer.captureControl.defaultTtl / maxTtlPT30M / PT2HCapture 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 spider CLI, not through MCP.