Caido Mcp Server

caido-mcp-server

MCP server and CLI for Caido web proxy - browse, replay, and analyze HTTP traffic from AI assistants or your terminal.

---

What It Does

Two ways to interact with your Caido proxy:

• MCP Server - expose 64 tools and 4 read-only resources to AI assistants (Claude Code, Cursor, etc.) via the Model Context Protocol
• CLI - standalone terminal client for pentesters who prefer the command line

Both share the same auth token, the same Go SDK, and the same codebase.

Features

| Category | Capabilities | |----------|-------------| | Proxy History | Search requests with HTTPQL, get full request/response details | | Replay | Send HTTP requests, get response inline (status, headers, body). Per-session cookie jar auto-persists Set-Cookie between calls | | Automate | Access fuzzing sessions, results, and payloads. Start/pause/resume/cancel tasks | | Findings | Create, list, delete, and export security findings | | Sitemap | Browse discovered endpoints | | Scopes | Full lifecycle: create, rename, delete target scope definitions | | Projects | Full lifecycle: create, rename, select, delete projects | | Workflows | List, run, and toggle automation workflows | | Tamper | List, create, toggle, and delete Match & Replace rules | | Intercept | Check status, pause/resume, list/forward/drop intercepted requests | | Environments | Create, select, delete variable environments (tokens, keys) | | Filters | Create, list, and delete saved HTTPQL filter presets | | Hosted Files | List payload files served by Caido | | Tasks | List and cancel running background tasks | | Plugins | List installed plugin packages | | Instance | Get Caido version and platform info |

Built-in security and performance:

• Credential redaction - Authorization, Cookie, and API key headers are redacted in tool output
• 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
• Response fingerprinting - auto-detects content kind (json/html/xml/text/binary) so agents know what they're dealing with
• Adaptive body limits - JSON gets 4KB, HTML 3KB, binary 200B (override with explicit bodyLimit)
• Response diff - repeated identical responses in the same session collapse to a one-line summary, saving tokens
• Input validation - length limits on all string inputs to prevent context flooding
• Token auto-refresh - expired OAuth tokens refresh mid-session automatically
• Session reuse - single replay session per server lifetime, no sprawl

Session cookie jar

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).

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.

---

MCP Server

Install

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

Or download a pre-built binary from Releases (macOS, Linux, Windows - amd64/arm64).

Build from source

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

Quick Start

Option A: Personal Access Token (recommended)

Generate a PAT in Caido (Settings > Developer > Personal Access Tokens) and pass it via environment variable. No login command needed.

{
  "mcpServers": {
    "caido": {
      "command": "caido-mcp-server",
      "args": ["serve"],
      "env": {
        "CAIDO_URL": "http://127.0.0.1:8080",
        "CAIDO_PAT": "your-personal-access-token"
      }
    }
  }
}

Option B: OAuth device flow

CAIDO_URL=http://localhost:8080 caido-mcp-server login

This opens your browser for OAuth authentication and saves the token to ~/.caido-mcp/token.json. Then configure your MCP client:

{
  "mcpServers": {
    "caido": {
      "command": "caido-mcp-server",
      "args": ["serve"],
      "env": {
        "CAIDO_URL": "http://127.0.0.1:8080"
      }
    }
  }
}

3. Use it

"List all POST requests to /api"
"Send this request with a modified user ID"
"Create a finding for this IDOR"
"Show fuzzing results from Automate session 1"
"What's in scope?"

MCP Tools (64)

| Tool | Description | |------|-------------| | caido_list_requests | List requests with HTTPQL filter and pagination | | caido_get_request | Get request details (metadata, headers, body). 2KB body limit default | | 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) | | caido_batch_send | Send multiple requests in parallel (BAC sweeps, parameter fuzzing, endpoint sweeps). Max 50 per batch | | caido_edit_request | Modify and resend an existing request. Preserves auth/cookies while changing method, path, headers, or body | | caido_export_curl | Convert a request to an executable curl command for PoC reports | | caido_create_replay_session | Create a named replay session, optionally seed with a request | | caido_list_replay_sessions | List replay sessions | | caido_delete_replay_sessions | Bulk delete replay sessions by ID | | caido_move_replay_session | Move a session to a different collection | | caido_get_replay_entry | Get replay entry with response. 2KB body limit default | | caido_clear_session_cookies | Wipe the in-memory cookie jar for a replay session | | caido_get_session_cookies | List metadata for cookies stored in a session jar matching a URL (values not returned) | | caido_list_replay_collections | List replay session collections | | caido_create_replay_collection | Create a named replay collection | | caido_rename_replay_collection | Rename a replay collection | | caido_delete_replay_collection | Delete a replay collection | | caido_list_automate_sessions | List fuzzing sessions | | caido_get_automate_session | Get session details with entry list | | caido_get_automate_entry | Get fuzz results and payloads | | caido_automate_task_control | Start/pause/resume/cancel fuzzing tasks | | caido_list_findings | List security findings | | caido_create_finding | Create finding linked to a request | | caido_delete_findings | Delete findings by IDs or reporter name | | caido_export_findings | Export findings for reporting | | caido_get_sitemap | Browse sitemap hierarchy | | caido_list_scopes | List target scopes | | caido_create_scope | Create new scope with allow/deny lists | | caido_rename_scope | Rename a scope | | caido_delete_scope | Delete a scope | | caido_list_projects | List projects, marks current | | caido_select_project | Switch active project | | caido_create_project | Create a new project | | caido_rename_project | Rename a project | | caido_delete_project | Delete a project | | caido_list_workflows | List automation workflows | | caido_run_workflow | Execute an active or convert workflow | | caido_toggle_workflow | Enable or disable a workflow | | caido_list_tamper_rules | List Match & Replace rule collections | | caido_create_tamper_rule | Create a tamper rule in a collection | | caido_update_tamper_rule | Update an existing tamper rule | | caido_toggle_tamper_rule | Enable or disable a tamper rule | | caido_delete_tamper_rule | Delete a tamper rule | | caido_get_instance | Get Caido version and platform info | | caido_intercept_status | Get intercept status (PAUSED/RUNNING) | | caido_intercept_control | Pause or resume intercept | | caido_list_intercept_entries | List queued intercept entries with HTTPQL filtering | | caido_forward_intercept | Forward intercepted request, optionally with modifications | | caido_drop_intercept | Drop intercepted request | | caido_list_environments | List environments and their variables | | caido_select_environment | Switch active environment | | caido_create_environment | Create a new environment | | caido_delete_environment | Delete an environment | | caido_list_filters | List saved HTTPQL filter presets | | caido_create_filter | Save an HTTPQL query as a named filter preset | | caido_delete_filter | Delete a filter preset | | caido_list_hosted_files | List hosted payload files | | caido_list_tasks | List running background tasks | | caido_cancel_task | Cancel a running task by ID | | caido_list_plugins | List installed plugin packages | | caido_list_ws_streams | List WebSocket streams (connections) from the WebSocket tab | | caido_list_ws_messages | List WebSocket frames for a stream (direction/format/decoded body) | | caido_convert_body | Convert a request body between JSON, form-urlencoded, XML, and multipart | | caido_race_window_send | Fire raw HTTP/1.1 requests with synchronized last-byte send for race-condition testing (bypasses Caido proxy) |

MCP Resources (4)

Read-only data exposed via the MCP resources protocol. Agents can read these without consuming tool calls.

| URI | Description | |-----|-------------| | caido://requests/{id} | Full HTTP request and response for a given request ID | | caido://replay-sessions/{id} | Replay session details with entry list | | caido://sitemap | Root domains from the sitemap | | caido://findings | Security finding summaries (up to 100) |

Parameter reference

caidolistrequests

| Parameter | Type | Description | |-----------|------|-------------| | httpql | string | HTTPQL filter query | | limit | int | Max requests (default 20, max 100) | | after | string | Pagination cursor |

caidogetrequest

| Parameter | Type | Description | |-----------|------|-------------| | ids | string[] | Request IDs (required) | | include | string[] | requestHeaders, requestBody, responseHeaders, responseBody | | bodyOffset | int | Byte offset | | bodyLimit | int | Byte limit (default 2000) |

caidosendrequest

| Parameter | Type | Description | |-----------|------|-------------| | raw | string | Full HTTP request (required) | | host | string | Target host (overrides Host header) | | port | int | Target port | | tls | bool | Use HTTPS (default true) | | sessionId | string | Replay session (auto-managed if omitted) |

caidogetreplay_entry

| Parameter | Type | Description | |-----------|------|-------------| | id | string | Replay entry ID (required) | | bodyOffset | int | Byte offset | | bodyLimit | int | Byte limit (default 2000) |

caidogetautomate_entry

| Parameter | Type | Description | |-----------|------|-------------| | id | string | Entry ID (required) | | limit | int | Max results | | after | string | Pagination cursor |

caidocreatefinding

| Parameter | Type | Description | |-----------|------|-------------| | requestId | string | Associated request (required) | | title | string | Finding title (required) | | description | string | Finding description |

caidocreatescope

| Parameter | Type | Description | |-----------|------|-------------| | name | string | Scope name (required) | | allowlist | string[] | Hostnames to include, e.g. example.com, *.example.com (required) | | denylist | string[] | Hostnames to exclude |

caidoselectproject

| Parameter | Type | Description | |-----------|------|-------------| | id | string | Project ID to switch to (required) |

caidointerceptcontrol

| Parameter | Type | Description | |-----------|------|-------------| | action | string | pause or resume (required) |

caidolistintercept_entries

| Parameter | Type | Description | |-----------|------|-------------| | filter | string | HTTPQL filter query | | limit | int | Max entries (default 20, max 100) | | after | string | Pagination cursor |

caidoforwardintercept

| Parameter | Type | Description | |-----------|------|-------------| | id | string | Intercept entry ID (required) | | raw | string | Modified raw HTTP request (base64-encoded, optional) |

caidodropintercept

| Parameter | Type | Description | |-----------|------|-------------| | id | string | Intercept entry ID (required) |

caidoautomatetask_control

| Parameter | Type | Description | |-----------|------|-------------| | action | string | start, pause, resume, or cancel (required) | | session_id | string | Automate session ID (required for start) | | task_id | string | Automate task ID (required for pause/resume/cancel) |

caidodeletefindings

| Parameter | Type | Description | |-----------|------|-------------| | ids | string[] | Finding IDs to delete | | reporter | string | Delete all findings by this reporter |

caidoexportfindings

| Parameter | Type | Description | |-----------|------|-------------| | ids | string[] | Finding IDs to export | | reporter | string | Export all findings by this reporter |

caidolistenvironments

No parameters required. Returns all environments with variables and selected/global context.

caidoselectenvironment

| Parameter | Type | Description | |-----------|------|-------------| | id | string | Environment ID (required, empty string to deselect) |

caidorunworkflow

| Parameter | Type | Description | |-----------|------|-------------| | id | string | Workflow ID (required) | | type | string | active or convert (required) | | request_id | string | Request ID (required for active workflows) | | input | string | Input data (required for convert workflows) |

caidotoggleworkflow

| Parameter | Type | Description | |-----------|------|-------------| | id | string | Workflow ID (required) | | enabled | bool | Enable or disable (required) |

caidolisttamper_rules

No parameters required. Returns all tamper rule collections with nested rules.

caidocreatetamper_rule

| Parameter | Type | Description | |-----------|------|-------------| | collection_id | string | Collection ID (required) | | name | string | Rule name (required) | | condition | string | HTTPQL filter condition | | sources | string[] | Traffic sources: INTERCEPT, REPLAY, AUTOMATE, IMPORT, PLUGIN, WORKFLOW, SAMPLE |

caidotoggletamper_rule

| Parameter | Type | Description | |-----------|------|-------------| | id | string | Tamper rule ID (required) | | enabled | bool | Enable or disable (required) |

caidodeletetamper_rule

| Parameter | Type | Description | |-----------|------|-------------| | id | string | Tamper rule ID (required) |

---

CLI

Standalone terminal client for Caido. No MCP required - use it directly from your shell.

Install

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

Or download from Releases.

Build from source

git clone https://github.com/c0tton-fluff/caido-mcp-server.git
cd caido-mcp-server
go build -o caido-cli ./cmd/cli

Usage

Requires authentication - either set CAIDO_PAT env var or run caido-mcp-server login first.

# Check connection and auth
caido status -u http://localhost:8080

# Send structu

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [c0tton-fluff](https://github.com/c0tton-fluff)
- **Source:** [c0tton-fluff/caido-mcp-server](https://github.com/c0tton-fluff/caido-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.