Skip to content
Back to search

caido-mcp-server

MCP server for Caido proxy integration. Enables AI assistants like Claude Code to browse, analyse, and interact with HTTP traffic.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/c0tton-fluff/caido-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/c0tton-fluff/caido-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/c0tton-fluff--caido-mcp-server/badge.svg)](/listings/c0tton-fluff--caido-mcp-server)

HTML

<a href="/listings/c0tton-fluff--caido-mcp-server"><img src="/api/listings/c0tton-fluff--caido-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

curl -fsSL https://raw.githubusercontent.com/c0tton-fluff/caido-mcp-server/main/install.sh | bash

Or download a pre-built binary from [Releases](https://github.com/c0tton-fluff/caido-mcp-server/releases) (macOS, Linux, Windows - amd64/arm64).

Or install with the Go toolchain (Go 1.25+):

go install github.com/c0tton-fluff/caido-mcp-server/v4/cmd/caido-mcp-server@latest

The binary lands in `$(go env GOPATH)/bin` (add it to your `PATH`). The installed binary reports its module version via `caido-mcp-server --version`.

<details> <summary>Build from source</summary>

git clone https://github.com/c0tton-fluff/caido-mcp-server.git
cd caido-mcp-server
go build -ldflags "-X github.com/c0tton-fluff/caido-mcp-server/v4/internal/buildinfo.version=$(git describe --tags)" -o caido-mcp-server ./cmd/caido-mcp-server

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 841 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="https://raw.githubusercontent.com/caido/caido/main/brand/png/logo.png" alt="Caido" width="120"/>
  3. </p>
  4. <h1 align="center">caido-mcp-server</h1>
  5. <p align="center">
  6. MCP server and CLI for <a href="https://caido.io">Caido</a> web proxy - browse, replay, and analyze HTTP traffic from AI assistants or your terminal.
  7. </p>
  8. <p align="center">
  9. <a href="https://go.dev"><img src="https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go&logoColor=white" alt="Go"></a>
  10. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a>
  11. <a href="https://github.com/c0tton-fluff/caido-mcp-server/releases"><img src="https://img.shields.io/github/v/release/c0tton-fluff/caido-mcp-server" alt="Release"></a>
  12. <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-8A2BE2" alt="MCP"></a>
  13. <a href="https://github.com/c0tton-fluff/caido-mcp-server/actions/workflows/ci.yml"><img src="https://github.com/c0tton-fluff/caido-mcp-server/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  14. </p>
  15. ---
  16. ## What It Does
  17. Two ways to interact with your Caido proxy:
  18. - **MCP Server** - expose 76 tools and 6 read-only resources to AI assistants (Claude Code, Cursor, etc.) via the Model Context Protocol
  19. - **CLI** - standalone terminal client for pentesters who prefer the command line
  20. Both share the same auth token, the same Go SDK, and the same codebase.
  21. ## Features
  22. | Category | Capabilities |
  23. |----------|-------------|
  24. | **Proxy History** | Search requests with HTTPQL, get full request/response details, diff two responses |
  25. | **Replay** | Send HTTP requests (raw or a pasted cURL command), get response inline (status, headers, body). Per-session cookie jar auto-persists `Set-Cookie` between calls |
  26. | **WebSocket** | Browse WS history; open a socket through Caido Replay (0.59+), send frames, long-poll pushed frames (e.g. graphql-ws subscriptions), close |
  27. | **Race conditions** | Single-packet, last-byte-sync and sequential runs through Caido Replay Pipelines (0.59+), with a status-code tally per run |
  28. | **Automate** | Access fuzzing sessions, results, and payloads. Start/pause/resume/cancel tasks |
  29. | **Findings** | Create, list, delete, and export security findings |
  30. | **Sitemap** | Browse discovered endpoints |
  31. | **Scopes** | Full lifecycle: create, rename, delete target scope definitions; check if a host/URL is in scope |
  32. | **Projects** | Full lifecycle: create, rename, select, delete projects |
  33. | **Workflows** | List, run, and toggle automation workflows |
  34. | **Tamper** | List, create, update, toggle, and delete Match & Replace rules in all four GUI modes (update raw, update value, add, remove); dry-run a rule against a raw request before committing it |
  35. | **Intercept** | Check status, pause/resume, list/forward/drop intercepted requests |
  36. | **Environments** | Create, select, delete variable environments (tokens, keys) |
  37. | **Filters** | Create, list, and delete saved HTTPQL filter presets |
  38. | **Hosted Files** | List payload files served by Caido |
  39. | **Tasks** | List and cancel running background tasks |
  40. | **Plugins** | List installed plugin packages |
  41. | **Instance** | Get Caido version and platform info |
  42. **Built-in security and performance:**
  43. - Credential redaction - Authorization, Cookie, and API key headers are redacted in tool output by default (including raw request/response dumps and the `caido://requests/{id}` resource); opt out with `CAIDO_ALLOW_SENSITIVE_HEADERS` (see [Revealing sensitive headers](#revealing-sensitive-headers))
  44. - Secret environment variables - values of `SECRET` variables are redacted in `caido_list_environments`; the same opt-out applies
  45. - Read-only mode - `serve --read-only` registers only the tools that read state, so nothing that sends traffic or changes the project can be called (see [Read-only mode](#read-only-mode))
  46. - Scope enforcement - `serve --enforce-scope` refuses any request, batch, race or WebSocket connection to a host outside the project scope, and withholds the tools that could change the scope (see [Scope enforcement](#scope-enforcement))
  47. - Toolsets and compact mode - `serve --toolsets core --compact` cuts the advertised tool list from about 92 KB to about 23 KB, so an agent spends less context before its first call (see [Toolsets](#toolsets))
  48. - Tool annotations - every tool declares `readOnlyHint`/`destructiveHint`/`idempotentHint`/`openWorldHint` so MCP clients can distinguish read-only, destructive, and external-network tools
  49. - Session cookie jar - RFC 6265 jar per replay session; `Set-Cookie` from a response is auto-attached to the next `send_request` against the same session
  50. - Response fingerprinting - auto-detects content kind (json/html/xml/text/binary) so agents know what they're dealing with
  51. - Adaptive body limits - JSON gets 4KB, HTML 3KB, binary 200B (override with explicit `bodyLimit`)
  52. - Response diff - repeated identical responses in the same session collapse to a one-line summary, saving tokens
  53. - Input validation - length limits on all string inputs to prevent context flooding
  54. - Token auto-refresh - expired OAuth tokens refresh mid-session automatically
  55. - Session reuse - single replay session per server lifetime, no sprawl
  56. ### Session cookie jar
  57. The `caido_send_request` tool maintains an in-memory `http.CookieJar` per replay session. Cookies set via `Set-Cookie` in any response are stored and auto-injected into subsequent requests targeting the same RFC 6265 domain/path. Pass `useCookieJar: false` to a single call to disable injection (useful for session-fixation testing or to verify auth gates). Use `caido_clear_session_cookies` to wipe a session jar between test runs and `caido_get_session_cookies` to introspect what is stored (cookie values are not returned, only metadata).
  58. The output of `caido_send_request` includes a `cookieJar` block with `injectedCookies` (names sent on this call) and `storedCookies` (names captured from `Set-Cookie`), so the LLM can verify the chain stayed authenticated.
  59. ### Response fingerprinting
  60. Every `caido_send_request` / `caido_batch_send` response includes a compact fingerprint so an agent can reason about a response without the full body:
  61. - `title` - HTML `<title>`, if present
  62. - `redirect` - Location target on a 3xx
  63. - `cookieNames` - names set via `Set-Cookie` (values are never included)
  64. - `wordCount` - body word count, for size/diff comparison
  65. - `notableHeaders` - non-standard response headers (`Server`, `X-Powered-By`, custom `X-*`). App and flag signal often hides here - check these on every response, including 4xx/5xx.
  66. The fingerprint stays populated even when `includeBody: false`.
  67. ### Revealing sensitive headers
  68. By default, sensitive headers (`Authorization`, `Cookie`, `Set-Cookie`, `Proxy-Authorization`, `X-Api-Key`, `X-Auth-Token`, `X-CSRF-Token`, `X-XSRF-Token`) are replaced with `[REDACTED]` in tool output to avoid leaking credentials into the model context. On an authorized engagement where you need the real values — to analyze or replay a captured authenticated request, or to produce a working `caido_export_curl` PoC — set `CAIDO_ALLOW_SENSITIVE_HEADERS` to a truthy value (`1`, `true`):
  69. ```json
  70. {
  71. "mcpServers": {
  72. "caido": {
  73. "command": "caido-mcp-server",
  74. "args": ["serve"],
  75. "env": {
  76. "CAIDO_URL": "http://127.0.0.1:8080",
  77. "CAIDO_ALLOW_SENSITIVE_HEADERS": "true"
  78. }
  79. }
  80. }
  81. }
  82. ```
  83. When enabled, real credential values flow through tool output to the model; leave it unset to keep redaction. The same toggle reveals the values of `SECRET` environment variables in `caido_list_environments`. It does not affect the session cookie jar, which only ever reports cookie names and metadata, never values.
  84. ### Read-only mode
  85. Start the server with `--read-only` (or set `CAIDO_MCP_READ_ONLY=1`) to expose only the tools annotated read-only. Tools that send traffic or change the Caido project are not registered at all, so a client cannot call them even by name. Use it to let an agent review captured traffic without the ability to touch a target or the project.
  86. ```json
  87. {
  88. "mcpServers": {
  89. "caido-readonly": {
  90. "command": "caido-mcp-server",
  91. "args": ["serve", "--read-only"],
  92. "env": {
  93. "CAIDO_URL": "http://127.0.0.1:8080"
  94. }
  95. }
  96. }
  97. }
  98. ```
  99. The startup banner reports the mode and the reduced tool count. A `CAIDO_MCP_READ_ONLY` value that is not a boolean stops the server instead of starting it with every tool.
  100. ### Toolsets
  101. Every MCP client loads the full tool list into the model's context at the start of a session. With all 76 tools that list is about 92 KB. Two options shrink it:
  102. - `--toolsets` (or `CAIDO_MCP_TOOLSETS`) registers only the toolsets you name, comma separated.
  103. - `--compact` (or `CAIDO_MCP_COMPACT=1`) leaves the output schemas out of the list. Results still carry structured content.
  104. | Configuration | Tools | Tool list |
  105. |---------------|-------|-----------|
  106. | default | 76 | 92.0 KB |
  107. | `--compact` | 76 | 62.0 KB |
  108. | `--toolsets core` | 31 | 39.4 KB |
  109. | `--toolsets core --compact` | 31 | 23.3 KB |
  110. | Toolset | Tools |
  111. |---------|-------|
  112. | `history` | Captured HTTP traffic: list, read, diff, sitemap, body conversion |
  113. | `replay` | Send requests, replay sessions and collections, session cookie jars |
  114. | `websocket` | WebSocket history and WebSocket replay |
  115. | `race` | Race pipelines and the raw-socket race window |
  116. | `scopes` | List, check, create, change and delete scopes |
  117. | `findings` | List, create, delete and export findings |
  118. | `automate` | Automate sessions, entries and task control |
  119. | `intercept` | Intercept queue and TLS pass-through options |
  120. | `tamper` | Match & Replace rules |
  121. | `workflows` | List, run and toggle workflows |
  122. | `environments` | Environments and their variables |
  123. | `admin` | Instance, projects, filter presets, hosted files, tasks, plugins |
  124. | `core` | Shorthand for `history,replay,scopes,findings` |
  125. ```json
  126. {
  127. "mcpServers": {
  128. "caido": {
  129. "command": "caido-mcp-server",
  130. "args": ["serve", "--toolsets", "core,websocket", "--compact"],
  131. "env": {
  132. "CAIDO_URL": "http://127.0.0.1:8080"
  133. }
  134. }
  135. }
  136. }
  137. ```
  138. Toolsets combine with `--read-only` and `--enforce-scope`. An unknown toolset name stops the server with the list of valid names. With a toolset selection the server instructions name no specific tool, since which tools exist is then your choice.
  139. ### Scope enforcement
  140. Start the server with `--enforce-scope` (or set `CAIDO_MCP_ENFORCE_SCOPE=1`) to make the project scope a hard boundary for the agent:
  141. ```json
  142. {
  143. "mcpServers": {
  144. "caido": {
  145. "command": "caido-mcp-server",
  146. "args": ["serve", "--enforce-scope"],
  147. "env": {
  148. "CAIDO_URL": "http://127.0.0.1:8080"
  149. }
  150. }
  151. }
  152. }
  153. ```
  154. | | |
  155. |---|---|
  156. | Refused | A target host outside every scope, for `caido_send_request`, `caido_edit_request`, `caido_batch_send` (per request), `caido_race_pipeline`, `caido_race_window_send` and `caido_ws_connect` |
  157. | Withheld | `caido_create_scope`, `caido_update_scope`, `caido_delete_scope`, `caido_select_project`, `caido_create_project`, `caido_delete_project`, so the agent cannot move the boundary |
  158. | Fails closed | Scopes cannot be read, the project has no scope, or the only scopes have an empty allowlist: nothing is sent |
  159. | Not covered | Traffic the server does not address itself: forwarding an intercepted browser request, starting an Automate session, running a workflow |
  160. A host is in scope when one scope's allowlist matches it and that scope's denylist does not, the same rule `caido_is_in_scope` reports. Scopes are read on every send, so a change you make in Caido applies to the next request. A refused target is refused before any Replay session is created.
  161. ---
  162. ## MCP Server
  163. ### Install
  164. ```bash
  165. curl -fsSL https://raw.githubusercontent.com/c0tton-fluff/caido-mcp-server/main/install.sh | bash
  166. ```
  167. Or download a pre-built binary from [Releases](https://github.com/c0tton-fluff/caido-mcp-server/releases) (macOS, Linux, Windows - amd64/arm64).
  168. Or install with the Go toolchain (Go 1.25+):
  169. ```bash
  170. go install github.com/c0tton-fluff/caido-mcp-server/v4/cmd/caido-mcp-server@latest
  171. ```
  172. The binary lands in `$(go env GOPATH)/bin` (add it to your `PATH`). The installed binary reports its module version via `caido-mcp-server --version`.
  173. <details>
  174. <summary>Build from source</summary>
  175. ```bash
  176. git clone https://github.com/c0tton-fluff/caido-mcp-server.git
  177. cd caido-mcp-server
  178. go build -ldflags "-X github.com/c0tton-fluff/caido-mcp-server/v4/internal/buildinfo.version=$(git describe --tags)" -o caido-mcp-server ./cmd/caido-mcp-server
  179. ```
  180. </details>
  181. ### Quick Start
  182. **Option A: Static access token (recommended)**
  183. This server talks to the **local Caido app's [GraphQL API](https://docs.caido.io/app/concepts/graphql#authentication)**, which authenticates with the **access token from your Caido login session** — *not* a Caido Cloud [Personal Access Token](https://docs.caido.io/dashboard/concepts/pat). A Cloud PAT (prefixed `caido_`) is for the cloud/dashboard API and will **not** authenticate against your local instance.
  184. Grab the access token from the Caido GUI: open developer tools (`CTRL`+`SHIFT`+`I`) and run this in the Console tab:
  185. ```javascript
  186. JSON.parse(localStorage.CAIDO_AUTHENTICATION).accessToken
  187. ```
  188. Pass it via the `CAIDO_ACCESS_TOKEN` environment variable. No login command needed.
  189. ```json
  190. {
  191. "mcpServers": {
  192. "caido": {
  193. "command": "caido-mcp-server",
  194. "args": ["serve"],
  195. "env": {
  196. "CAIDO_URL": "http://127.0.0.1:8080",
  197. "CAIDO_ACCESS_TOKEN": "your-caido-access-token"
  198. }
  199. }
  200. }
  201. }
  202. ```
  203. > **Note:** this token expires after ~7 days; for a long-lived setup use **Option B** (OAuth), which refreshes automatically. The older `CAIDO_PAT` variable is still accepted as a deprecated alias for `CAIDO_ACCESS_TOKEN`.
  204. **Option B: OAuth device flow**
  205. ```bash
  206. CAIDO_URL=http://localhost:8080 caido-mcp-server login
  207. ```
  208. This opens your browser for OAuth authentication and saves the token under `~/.caido-mcp/tokens/`. Then configure your MCP client:
  209. ```json
  210. {
  211. "mcpServers": {
  212. "caido": {
  213. "command": "caido-mcp-server",
  214. "args": ["serve"],
  215. "env": {
  216. "CAIDO_URL": "http://127.0.0.1:8080"
  217. }
  218. }
  219. }
  220. }
  221. ```
  222. Credentials are stored per instance, keyed by the canonical `CAIDO_URL`, so you can stay
  223. logged in to several Caido instances at once and switch between them without
  224. re-authenticating. Run `login` once per instance. An existing
  225. `~/.caido-mcp/token.json` from an earlier version is migrated automatically the first time
  226. you use it, so upgrading does not require a fresh login.
  227. **3. Use it**
  228. ```
  229. "List all POST requests to /api"
  230. "Send this request with a modified user ID"
  231. "Create a finding for this IDOR"
  232. "Show fuzzing results from Automate session 1"
  233. "What's in scope?"
  234. ```
  235. ### MCP Tools (76)
  236. | Tool | Description |
  237. |------|-------------|
  238. | `caido_list_requests` | List requests with HTTPQL filter, scope, ordering and pagination; returns the filter's total count |
  239. | `caido_get_request` | Get request details (metadata, headers, body). 2KB body limit default |
  240. | `caido_diff_responses` | Structural diff of two responses by Caido request ID: status/size change flags and a compact body/header summary (never dumps full bodies) |
  241. | `caido_send_request` | Send HTTP request via Replay, returns response inline. Polls up to 10s. Auto-injects session cookies and persists `Set-Cookie` (toggle with `useCookieJar`) |
  242. | `caido_batch_send` | Send multiple requests in parallel (BAC sweeps, parameter fuzzing, endpoint sweeps). Max 50 per batch |
  243. | `caido_edit_request` | Modify and resend an existing request. Preserves auth/cookies while changing method, path, headers, or body |
  244. | `caido_export_curl` | Convert a request to an executable curl command for PoC reports |
  245. | `caido_create_replay_session` | Create a named replay session, optionally seed with a request |
  246. | `caido_list_replay_sessions` | List replay sessions with kind (http, ws, pipeline) and collection |
  247. | `caido_delete_replay_sessions` | Bulk delete replay sessions by ID |
  248. | `caido_move_replay_session` | Move a session to a different collection |
  249. | `caido_rename_replay_session` | Rename a replay session (tab title) |
  250. | `caido_get_replay_entry` | Get replay entry with response. 2KB body limit default |
  251. | `caido_clear_session_cookies` | Wipe the in-memory cookie jar for a replay session |
  252. | `caido_get_session_cookies` | List metadata for cookies stored in a session jar matching a URL (values not returned) |
  253. | `caido_list_replay_collections` | List replay session collections |
  254. | `caido_create_replay_collection` | Create a named replay collection |
  255. | `caido_rename_replay_collection` | Rename a replay collection |
  256. | `caido_delete_replay_collection` | Delete a replay collection |
  257. | `caido_list_automate_sessions` | List fuzzing sessions |
  258. | `caido_get_automate_session` | Get session details with entry list |
  259. | `caido_get_automate_entry` | Get fuzz results and payloads |
  260. | `caido_automate_task_control` | Start/pause/resume/cancel fuzzing tasks |
  261. | `caido_list_findings` | List security findings |
  262. | `caido_create_finding` | Create finding linked to a request |
  263. | `caido_delete_findings` | Delete findings by IDs or reporter name |
  264. | `caido_export_findings` | Export findings for reporting |
  265. | `caido_get_sitemap` | Browse sitemap hierarchy |
  266. | `caido_list_scopes` | List target scopes |
  267. | `caido_is_in_scope` | Check whether a host or URL is in the project scope; returns the matching scope and the allow/deny rule that decided it |
  268. | `caido_create_scope` | Create new scope with allow/deny lists |
  269. | `caido_rename_scope` | Rename a scope |
  270. | `caido_update_scope` | Change a scope's name, allowlist or denylist; `addAllow` / `addDeny` append without restating the lists |
  271. | `caido_delete_scope` | Delete a scope |
  272. | `caido_list_projects` | List projects, marks current |
  273. | `caido_select_project` | Switch active project |
  274. | `caido_create_project` | Create a new project |
  275. | `caido_rename_project` | Rename a project |
  276. | `caido_delete_project` | Delete a project |
  277. | `caido_list_workflows` | List automation workflows |
  278. | `caido_run_workflow` | Execute an active or convert workflow |
  279. | `caido_toggle_workflow` | Enable or disable a workflow |
  280. | `caido_list_tamper_rules` | List Match & Replace rule collections |
  281. | `caido_create_tamper_rule` | Create a tamper rule in a collection |
  282. | `caido_update_tamper_rule` | Update an existing tamper rule |
  283. | `caido_test_tamper_rule` | Dry-run a tamper rule against a raw request |
  284. | `caido_toggle_tamper_rule` | Enable or disable a tamper rule |
  285. | `caido_delete_tamper_rule` | Delete a tamper rule |
  286. | `caido_get_instance` | Get Caido version and platform info |
  287. | `caido_intercept_status` | Get intercept status (PAUSED/RUNNING) |
  288. | `caido_intercept_control` | Pause or resume intercept |
  289. | `caido_list_intercept_entries` | List queued intercept entries with HTTPQL filtering |
  290. | `caido_forward_intercept` | Forward intercepted request, optionally with modifications |
  291. | `caido_drop_intercept` | Drop intercepted request |
  292. | `caido_list_environments` | List environments and their variables |
  293. | `caido_select_environment` | Switch active environment |
  294. | `caido_update_environment` | Set, overwrite or delete environment variables by name, or rename the environment. Returns names and kinds, never values |
  295. | `caido_create_environment` | Create a new environment |
  296. | `caido_delete_environment` | Delete an environment |
  297. | `caido_list_filters` | List saved HTTPQL filter presets |
  298. | `caido_create_filter` | Save an HTTPQL query as a named filter preset |
  299. | `caido_delete_filter` | Delete a filter preset |
  300. | `caido_list_hosted_files` | List hosted payload files |
  301. | `caido_list_tasks` | List running background tasks |
  302. | `caido_cancel_task` | Cancel a running task by ID |
  303. | `caido_list_plugins` | List installed plugin packages |
  304. | `caido_list_ws_streams` | List WebSocket streams (connections) from the WebSocket tab |
  305. | `caido_list_ws_messages` | List WebSocket frames for a stream (direction/format/decoded body) |
  306. | `caido_ws_connect` | Open a WebSocket through a WS Replay session (url + headers/subprotocols, raw, or a history request); logged in history (Caido 0.59+) |
  307. | `caido_ws_send` | Send frames in order on a session's open WebSocket |
  308. | `caido_ws_read` | Long-poll a session's WebSocket for new (pushed) frames, with until/skip rules and a resume cursor |
  309. | `caido_ws_close` | Close a session's open WebSocket |
  310. | `caido_convert_body` | Convert a request body between JSON, form-urlencoded, XML, and multipart |
  311. | `caido_race_pipeline` | Race requests through a Caido Replay Pipeline (single-packet, last-byte or sequential; Caido 0.59+); logged in history |
  312. | `caido_race_window_send` | Fire raw HTTP/1.1 requests with synchronized last-byte send for race-condition testing (bypasses Caido proxy) |
  313. | `caido_passthrough_options` | Read or update pass-through options (tunnel without recording; keep history to in-scope only; Caido 0.59+) |
  314. ### MCP Resources (6)
  315. Read-only data exposed via the MCP resources protocol. Agents can read these without consuming tool calls.
  316. | URI | Description |
  317. |-----|-------------|
  318. | `caido://requests/{id}` | Full HTTP request and response for a given request ID |
  319. | `caido://replay-sessions/{id}` | Replay session details with entry list |
  320. | `caido://sitemap` | Root domains from the sitemap |
  321. | `caido://findings` | Security finding summaries (up to 100) |
  322. | `caido://scopes` | All target scopes with their allow/deny rules |
  323. | `caido://project` | Current project, instance version, and connection status |
  324. <details>
  325. <summary>Parameter reference</summary>
  326. #### caido_list_requests
  327. | Parameter | Type | Description |
  328. |-----------|------|-------------|
  329. | `httpql` | string | HTTPQL filter query (Caido 0.58+: `req.header["Name"].cont:"x"`, `resp.body.cont:"x"`) |
  330. | `limit` | int | Max requests (default 20, max 100) |
  331. | `after` | string | Pagination cursor |
  332. | `orderBy` | string | Sort field: `id`, `createdAt`, `host`, `method`, `path`, `query`, `fileExtension`, `source`, `statusCode`, `roundtripTime`, `responseLength`. Omit for Caido's default order |
  333. | `order` | string | `asc` or `desc` (default `desc` when `orderBy` is set; `desc` without `orderBy` sorts by id, i.e. newest first) |
  334. | `scopeId` | string | Only requests inside this scope (ID from `caido_list_scopes`); `totalCount` then counts in-scope matches |
  335. `totalCount` in the response is every request matching `httpql`, not just the rows on the page, so `{"httpql": "...", "limit": 1}` counts matches in one call. The newest N is `{"limit": N, "order": "desc"}`. `nextCursor` keeps the requested order, so `after` pages contiguously.
  336. #### caido_get_request
  337. | Parameter | Type | Description |
  338. |-----------|------|-------------|
  339. | `ids` | string[] | Request IDs (required) |
  340. | `include` | string[] | `requestHeaders`, `requestBody`, `responseHeaders`, `responseBody` |
  341. | `bodyOffset` | int | Byte offset |
  342. | `bodyLimit` | int | Byte limit (default 2000) |
  343. #### caido_send_request
  344. | Parameter | Type | Description |
  345. |-----------|------|-------------|
  346. | `raw` | string | Full HTTP request (this or `curl` is required) |
  347. | `curl` | string | A cURL command to send instead of `raw` (bash form, e.g. browser "Copy as cURL"); sets host/port/tls from its URL |
  348. | `host` | string | Target host (overrides Host header) |
  349. | `port` | int | Target port |
  350. | `tls` | bool | Use HTTPS (default true) |
  351. | `sessionId` | string | Replay session (auto-managed if omitted) |
  352. | `collectionId` | string | File the request as a new session in this collection (not with `sessionId`) |
  353. | `name` | string | Title for that new session (not with `sessionId`) |
  354. | `bodyLimit` | int | Response body byte limit (default 2000) |
  355. | `bodyOffset` | int | Response body byte offset (default 0) |
  356. | `useCookieJar` | bool | Auto-inject session cookies and persist `Set-Cookie` (default true); set false to disable for this call only |
  357. | `includeBody` | bool | Include response body text (default true); the fingerprint is always populated |
  358. | `marker` | string | String to search for in the response body; when set, `output.reflected` reports whether it was found |
  359. #### caido_race_pipeline
  360. | Parameter | Type | Description |
  361. |-----------|------|-------------|
  362. | `host` | string | Target host (required) |
  363. | `port` | int | Target port (default 443 with TLS, 80 without) |
  364. | `tls` | bool | Use TLS (default true) |
  365. | `requests` | array | 1..50 `{label, raw}` requests; repeat one request N times to race it (required) |
  366. | `strategy` | string | `last-byte` (default), `single-packet` (needs Caido's experimental v2 network stack), or `sequential` |
  367. | `convertToHttp2` | bool | single-packet: send over one HTTP/2 connection (default true) |
  368. | `fireOnPartial` | bool | single-packet/last-byte: release the requests that prepared even if some failed (default false) |
  369. | `abortOnFailure` | bool | sequential: stop at the first failure |
  370. | `collectionId` / `name` | string | File and title the pipeline session |
  371. | `bodyLimit` | int | Per-response body bytes (default 256, max 4096) |
  372. | `timeoutSec` | int | Seconds to wait for all responses (default 30, max 120) |
  373. Returns `statusCounts` (e.g. `{"200":2,"409":18}`) plus per-request status, timing and body.
  374. #### caido_ws_connect / send / read / close
  375. Drive a WebSocket (e.g. a graphql-ws subscription) through Caido: the socket is opened from a WS Replay session, so every frame lands in WS history and the named replay tab. The tools take the session's `sessionId`; `caido_ws_read` also reads any stream by `streamId`.
  376. | Tool | Parameter | Description |
  377. |------|-----------|-------------|
  378. | `caido_ws_connect` | `url` + `headers` + `subprotocols` | Build the upgrade request from a `ws://`/`wss://` URL; headers override generated ones by name |
  379. | | `raw` + `host`/`port`/`tls` | Or a full raw upgrade request |
  380. | | `requestId` | Or a captured upgrade request from history |
  381. | | `sessionId` | Reuse a WS session with the new handshake (closes an open connection on it). Some Caido plans allow a single WS session |
  382. | | `reuse` | When the plan's WS session limit blocks creating one and exactly one WS session exists, reuse it (moved into `collectionId`, renamed to `name`) |
  383. | | `collectionId` / `name` | File and title the session |
  384. | | `connect` | `false` only prepares the tab (default true) |
  385. | | `timeoutSec` | Handshake wait, and on a reused session the wait for its open connection to close (default 10, max 60) |
  386. | `caido_ws_send` | `frames` | 1..50 `{body, format: TEXT\|BINARY, base64}` sent in order |
  387. | | `delayMs` | Pause between frames (max 10000) |
  388. | `caido_ws_read` | `after` | Cursor from the previous read; drop it after reconnecting |
  389. | | `waitMs` | Long-poll time (default 3000, max 120000) |
  390. | | `untilContains` / `untilCount` | Stop at a matching frame / after N frames (at most one; default: return as soon as frames arrive) |
  391. | | `skipBodies` | Drop exact bodies such as keep-alives; PING/PONG are always dropped |
  392. | | `includeSent` | Also return client frames (default: server frames only) |
  393. | | `limit` / `bodyLimit` | Frames per read (default 50, max 200) / bytes per frame body (default 4096, max 65536) |
  394. | `caido_ws_close` | `timeoutSec` | Wait for Caido to close the socket (default 10, max 60). `closed: false` means nothing was open; `timedOut: true` that the close was not confirmed and the socket may still be open. Caido's API sends no status code or reason |
  395. `caido_ws_connect` returns `statusCode` (101 on success), response headers, `open`, and the body of a rejected handshake; `error` when the connection failed before any response (refused, DNS, TLS), `pending` when `timeoutSec` passed first. It also returns the `name`, `collectionId` and `collectionName` the session is filed under; on a reused session, `previousStreamId` is the earlier run the tab no longer shows (read it with `caido_ws_read streamId`), `movedFrom` the collection it left, and `reused` that `reuse=true` took it. `caido_ws_read` frames carry `direction` `sent`/`received`; `more: true` means the read hit its scan cap with frames left (read again with the cursor), `open: false` that the connection closed; `skippedSent` / `skippedBodies` / `skippedControl` count frames left out as client frames, `skipBodies` matches and PING/PONG. `caido_list_ws_streams` adds `replaySessionId` to streams opened from a WS replay session. Caveat: Caido 0.59.1 replay recording drops server frames that arrive back to back (under ~20ms apart).
  396. #### caido_get_replay_entry
  397. | Parameter | Type | Description |
  398. |-----------|------|-------------|
  399. | `id` | string | Replay entry ID (required) |
  400. | `bodyOffset` | int | Byte offset |
  401. | `bodyLimit` | int | Byte limit (default 2000) |
  402. #### caido_get_automate_entry
  403. | Parameter | Type | Description |
  404. |-----------|------|-------------|
  405. | `id` | string | Entry ID (required) |
  406. | `limit` | int | Max results |
  407. | `after` | string | Pagination cursor |
  408. #### caido_create_finding
  409. | Parameter | Type | Description |
  410. |-----------|------|-------------|
  411. | `requestId` | string | Associated request (required) |
  412. | `title` | string | Finding title (required) |
  413. | `description` | string | Finding description |
  414. #### caido_create_scope
  415. | Parameter | Type | Description |
  416. |-----------|------|-------------|
  417. | `name` | string | Scope name (required) |
  418. | `allowlist` | string[] | Hostnames to include, e.g. `example.com`, `*.example.com` (required) |
  419. | `denylist` | string[] | Hostnames to exclude |
  420. #### caido_select_project
  421. | Parameter | Type | Description |
  422. |-----------|------|-------------|
  423. | `id` | string | Project ID to switch to (required) |
  424. #### caido_intercept_control
  425. | Parameter | Type | Description |
  426. |-----------|------|-------------|
  427. | `action` | string | `pause` or `resume` (required) |
  428. #### caido_list_intercept_entries
  429. | Parameter | Type | Description |
  430. |-----------|------|-------------|
  431. | `filter` | string | HTTPQL filter query |
  432. | `limit` | int | Max entries (default 20, max 100) |
  433. | `after` | string | Pagination cursor |
  434. #### caido_forward_intercept
  435. | Parameter | Type | Description |
  436. |-----------|------|-------------|
  437. | `id` | string | Intercept entry ID (required) |
  438. | `raw` | string | Modified raw HTTP request (base64-encoded, optional) |
  439. #### caido_drop_intercept
  440. | Parameter | Type | Description |
  441. |-----------|------|-------------|
  442. | `id` | string | Intercept entry ID (required) |
  443. #### caido_automate_task_control
  444. | Parameter | Type | Description |
  445. |-----------|------|-------------|
  446. | `action` | string | `start`, `pause`, `resume`, or `cancel` (required) |
  447. | `session_id` | string | Automate session ID (required for start) |
  448. | `task_id` | string | Automate task ID (required for pause/resume/cancel) |
  449. #### caido_delete_findings
  450. | Parameter | Type | Description |
  451. |-----------|------|-------------|
  452. | `ids` | string[] | Finding IDs to delete |
  453. | `reporter` | string | Delete all findings by this reporter |
  454. #### caido_export_findings
  455. | Parameter | Type | Description |
  456. |-----------|------|-------------|
  457. | `ids` | string[] | Finding IDs to export |
  458. | `reporter` | string | Export all findings by this reporter |
  459. #### caido_list_environments
  460. No parameters required. Returns all environments with variables and selected/global context.
  461. #### caido_select_environment
  462. | Parameter | Type | Description |
  463. |-----------|------|-------------|
  464. | `id` | string | Environment ID (required, empty string to deselect) |
  465. #### caido_run_workflow
  466. | Parameter | Type | Description |
  467. |-----------|------|-------------|
  468. | `id` | string | Workflow ID (required) |
  469. | `type` | string | `active` or `convert` (required) |
  470. | `request_id` | string | Request ID (required for active workflows) |
  471. | `input` | string | Input data (required for convert workflows) |
  472. #### caido_toggle_workflow
  473. | Parameter | Type | Description |
  474. |-----------|------|-------------|
  475. | `id` | string | Workflow ID (required) |
  476. | `enabled` | bool | Enable or disable (required) |
  477. #### caido_list_tamper_rules
  478. No parameters required. Returns all tamper rule collections with nested rules
  479. (`id`, `name`, `section`, `enabled`, `condition`, `sources`).
  480. #### caido_create_tamper_rule
  481. | Parameter | Type | Description |
  482. |-----------|------|-------------|
  483. | `collection_id` | string | Collection ID (required) |
  484. | `name` | string | Rule name (required) |
  485. | `section` | string | Section to match (required), see below |
  486. | `operation` | object | Operation mode and parameters, see below |
  487. | `match` | string | Legacy shorthand for `operation.match` |
  488. | `replace` | string | Legacy shorthand for `operation.value` |
  489. | `condition` | string | HTTPQL filter condition |
  490. | `sources` | string[] | Traffic sources: INTERCEPT, REPLAY, AUTOMATE, IMPORT, PLUGIN, WORKFLOW, SAMPLE |
  491. ##### Operation modes
  492. | `operation.kind` | Meaning | Fields |
  493. |---|---|---|
  494. | `updateRaw` | Pattern match over the raw section text | `match`, `match_kind`, `value` |
  495. | `updateValue` | Set the value of a named header or query param | `name`, `value` |
  496. | `add` | Insert a new header or query param | `name`, `value` |
  497. | `remove` | Delete a named header or query param | `name` |
  498. `match_kind` selects how `match` is read: `regex` (default), `value` (literal
  499. substring, no escaping) or `full` (the entire section, `match` must be omitted).
  500. Use `workflow_id` instead of `value` to supply the replacement from a convert
  501. workflow.
  502. All four modes are available on `requestHeader`, `responseHeader` and
  503. `requestQuery`. Every other section supports exactly one mode, and asking for
  504. another returns an error naming the modes it does support:
  505. `requestAll`, `requestBody`, `requestFirstLine`, `requestPath`, `responseAll`,
  506. `responseBody`, `responseFirstLine` take `updateRaw`; `requestMethod`,
  507. `requestSNI`, `responseStatusCode` take `updateValue` (they always apply, so
  508. they accept no `match` or `name`).
  509. Omitting `operation` entirely falls back to the section's default mode with the
  510. legacy `match`/`replace` fields, so existing callers keep working unchanged.
  511. #### caido_update_tamper_rule
  512. Full update: pass the complete rule state, not a partial patch. Accepts the same
  513. `section`, `operation` and legacy `match`/`replace` parameters as
  514. `caido_create_tamper_rule`.
  515. | Parameter | Type | Description |
  516. |-----------|------|-------------|
  517. | `id` | string | Tamper rule ID (required) |
  518. | `name` | string | Rule name (required) |
  519. | `section` | string | Section to match (required) |
  520. | `operation` | object | Operation mode and parameters |
  521. | `match` | string | Legacy shorthand for `operation.match` |
  522. | `replace` | string | Legacy shorthand for `operation.value` |
  523. | `condition` | string | HTTPQL filter condition |
  524. | `sources` | string[] | Traffic sources |
  525. #### caido_test_tamper_rule
  526. Dry-run a rule against a raw HTTP request or response and return the transformed
  527. result. Nothing is persisted and no traffic is sent. Accepts the same `section`,
  528. `operation` and legacy `match`/`replace` parameters as
  529. `caido_create_tamper_rule`.
  530. | Parameter | Type | Description |
  531. |-----------|------|-------------|
  532. | `raw` | string | Raw HTTP request or response to transform (required) |
  533. | `section` | string | Section to match (required) |
  534. | `operation` | object | Operation mode and parameters |
  535. Returns `raw` (the transformed message) and `changed` (whether the rule matched
  536. anything at all), which is the quickest way to catch a rule that silently
  537. matches nothing.
  538. #### caido_toggle_tamper_rule
  539. | Parameter | Type | Description |
  540. |-----------|------|-------------|
  541. | `id` | string | Tamper rule ID (required) |
  542. | `enabled` | bool | Enable or disable (required) |
  543. #### caido_delete_tamper_rule
  544. | Parameter | Type | Description |
  545. |-----------|------|-------------|
  546. | `id` | string | Tamper rule ID (required) |
  547. </details>
  548. ---
  549. ## CLI
  550. Standalone terminal client for Caido. No MCP required - use it directly from your shell.
  551. ### Install
  552. ```bash
  553. curl -fsSL https://raw.githubusercontent.com/c0tton-fluff/caido-mcp-server/main/install.sh | TOOL=cli bash
  554. ```
  555. Or download from [Releases](https://github.com/c0tton-fluff/caido-mcp-server/releases).
  556. Or install with the Go toolchain (Go 1.25+):
  557. ```bash
  558. go install github.com/c0tton-fluff/caido-mcp-server/v4/cmd/caido-cli@latest
  559. ```
  560. <details>
  561. <summary>Build from source</summary>
  562. ```bash
  563. git clone https://github.com/c0tton-fluff/caido-mcp-server.git
  564. cd caido-mcp-server
  565. go build -o caido-cli ./cmd/caido-cli
  566. ```
  567. </details>
  568. ### Usage
  569. Requires authentication - run `caido-mcp-server login` first to store a token. (The CLI reads the stored login token; it does not consume the `CAIDO_ACCESS_TOKEN` env var that the MCP server uses.)
  570. ```bash
  571. # Check connection and auth
  572. caido-cli status -u http://localhost:8080
  573. # Send structured requests
  574. caido-cli send GET https://target.com/api/users
  575. caido-cli send POST https://target.com/api/login -j '{"user":"admin","pass":"test"}'
  576. caido-cli send PUT https://target.com/api/profile -H "Authorization: Bearer tok" -j '{"role":"admin"}'
  577. # Send raw HTTP requests
  578. caido-cli raw 'GET /api/users HTTP/1.1\r\nHost: target.com\r\n\r\n'
  579. caido-cli raw -f request.txt --host target.com --port 8443
  580. echo -n 'GET / HTTP/1.1\r\nHost: example.com\r\n\r\n' | caido-cli raw -
  581. # Parallel requests via Replay (BAC sweeps, param fuzzing, endpoint sweeps)
  582. caido-cli batch sweep https://target.com/api/profile -t "owner=eyJ1...,cross=eyJ2...,noauth"
  583. caido-cli batch fuzz "https://target.com/api/search?q=test" -p q -v "test,test',1 OR 1=1" -H "Authorization: Bearer eyJ..."
  584. caido-cli batch ep -t eyJ... https://target.com/dashboard https://target.com/admin
  585. caido-cli batch file batch.json
  586. # Browse proxy history
  587. caido-cli history
  588. caido-cli history -f 'req.host.eq:"target.com"' -n 20
  589. # Get full request/response details
  590. caido-cli request 12345
  591. # Encode/decode
  592. caido-cli encode base64 "hello world"
  593. caido-cli decode url "%3Cscript%3E"
  594. caido-cli encode hex "test"
  595. ```
  596. ### Commands
  597. | Command | Description |
  598. |---------|-------------|
  599. | `status` | Check Caido instance health and auth token |
  600. | `send METHOD URL` | Send structured HTTP request via Replay API |
  601. | `raw` | Send raw HTTP request (argument, file with `-f`, or stdin with `-`) |
  602. | `batch MODE` | Parallel requests via Replay: `sweep` (N tokens), `fuzz` (N values), `ep` (N URLs), `file` (JSON spec) |
  603. | `history` | List proxy history with HTTPQL filtering |
  604. | `request ID` | Get full request/response by ID |
  605. | `encode TYPE VALUE` | Encode value (`url`, `base64`, `hex`) |
  606. | `decode TYPE VALUE` | Decode value (`url`, `base64`, `hex`) |
  607. ### Global Flags
  608. | Flag | Description |
  609. |------|-------------|
  610. | `-u, --url` | Caido instance URL (or set `CAIDO_URL`) |
  611. | `-b, --body-limit` | Response body byte limit (default 2000) |
  612. ---
  613. ## Architecture
  614. ```
  615. caido-mcp-server/
  616. cmd/
  617. caido-mcp-server/ MCP server (stdio transport)
  618. caido-cli/ Standalone CLI
  619. internal/
  620. auth/ OAuth device flow, static access token (CAIDO_ACCESS_TOKEN), token store, auto-refresh
  621. buildinfo/ Version resolution (ldflag or go-install module version)
  622. httputil/ HTTP parsing, fingerprinting, response diff, CRLF normalization
  623. replay/ Replay session management, cookie jar, response polling
  624. resources/ MCP read-only resources (requests, sessions, sitemap, findings)
  625. tools/ MCP tool definitions (one file per tool)
  626. testutil/ Mock GraphQL server, MCP test helpers, fixtures
  627. ```
  628. The `cmd/` directory names match the installed binary names so `go install .../cmd/caido-mcp-server@latest` produces a correctly-named binary. Both commands share `internal/` packages. The project uses [caido-community/sdk-go](https://github.com/caido-community/sdk-go) for all GraphQL communication with Caido.
  629. ---
  630. ## Troubleshooting
  631. | Error | Fix |
  632. |-------|-----|
  633. | `Invalid token` | `CAIDO_ACCESS_TOKEN` must be the local Caido **access token** (not a Cloud PAT) — re-grab it from the GUI console, or run `caido-mcp-server login` again |
  634. | `token expired, no refresh token` | The static access token expires after ~7 days; re-grab it into `CAIDO_ACCESS_TOKEN`, or use `caido-mcp-server login` (OAuth auto-refreshes) |
  635. | `poll failed: timed out` | Target server slow; use `get_replay_entry` with the returned `entryId` |
  636. | `no authentication token found` | Set `CAIDO_ACCESS_TOKEN` env var or run `caido-mcp-server login` before `serve` |
  637. MCP server logs: `~/.cache/claude-cli-nodejs/*/mcp-logs-caido/`
  638. ---
  639. ## Security
  640. Sensitive HTTP headers (Authorization, Cookie, Set-Cookie, API keys) are redacted everywhere output leaves the server - structured tool output, raw request/response dumps, fuzz templates, and the `caido://requests/{id}` resource all pass through a single redaction choke-point to prevent credential leakage to LLM context. On an authorized engagement you can opt out with `CAIDO_ALLOW_SENSITIVE_HEADERS` (see [Revealing sensitive headers](#revealing-sensitive-headers)). All string inputs are length-validated server-side, and request batch sizes are capped.
  641. Access tokens (via `CAIDO_ACCESS_TOKEN`) and OAuth tokens are stored with 0600 permissions and never appear in process arguments or log output.
  642. To report a security issue, open a GitHub issue or contact the maintainer directly.
  643. ---
  644. ## Contributing
  645. 1. Fork the repo
  646. 2. Create a feature branch
  647. 3. `go build ./...` and `go test ./... -race`
  648. 4. Open a PR (CI runs build, test, vet, staticcheck)
  649. ### Local pre-push gate
  650. A tracked `.githooks/pre-push` runs the same checks as CI's `lint` + `test` jobs (gofmt, `go vet`, `golangci-lint run ./...`, `go test ./... -race`) so failures are caught before they reach CI. Enable it once per clone:
  651. ```
  652. git config core.hooksPath .githooks
  653. go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2
  654. ```
  655. Built with [caido-community/sdk-go](https://github.com/caido-community/sdk-go) and [modelcontextprotocol/go-sdk](https://github.com/modelcontextprotocol/go-sdk).
  656. ## License
  657. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.