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

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

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)

MCP Resources (4)

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

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.

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 structured requests
caido send GET https://target.com/api/users
caido send POST https://target.com/api/login -j '{"user":"admin","pass":"test"}'
caido send PUT https://target.com/api/profile -H "Authorization: Bearer tok" -j '{"role":"admin"}'

# Send raw HTTP requests
caido raw 'GET /api/users HTTP/1.1\r\nHost: target.com\r\n\r\n'
caido raw -f request.txt --host target.com --port 8443
echo -n 'GET / HTTP/1.1\r\nHost: example.com\r\n\r\n' | caido raw -

# Browse proxy history
caido history
caido history -f 'req.host.eq:"target.com"' -n 20

# Get full request/response details
caido request 12345

# Encode/decode
caido encode base64 "hello world"
caido decode url "%3Cscript%3E"
caido encode hex "test"

Commands

Global Flags

Architecture

caido-mcp-server/
  cmd/
    mcp/          MCP server (stdio transport)
    cli/          Standalone CLI
  internal/
    auth/         OAuth device flow, PAT support, token store, auto-refresh
    httputil/     HTTP parsing, fingerprinting, response diff, CRLF normalization
    replay/       Replay session management, cookie jar, response polling
    resources/    MCP read-only resources (requests, sessions, sitemap, findings)
    tools/        MCP tool definitions (one file per tool)
    testutil/     Mock GraphQL server, MCP test helpers, fixtures

Both cmd/mcp and cmd/cli share internal/ packages. The project uses caido-community/sdk-go for all GraphQL communication with Caido.

Troubleshooting

MCP server logs: ~/.cache/claude-cli-nodejs/*/mcp-logs-caido/

Security

Sensitive HTTP headers (Authorization, Cookie, Set-Cookie, API keys) are automatically redacted in all tool output to prevent credential leakage to LLM context. All string inputs are length-validated server-side. Request batch sizes are capped.

PAT tokens and OAuth tokens are stored with 0600 permissions and never appear in process arguments or log output.

To report a security issue, open a GitHub issue or contact the maintainer directly.

Contributing

1. Fork the repo
2. Create a feature branch
3. go build ./... and go test ./... -race
4. Open a PR (CI runs build, test, vet, staticcheck)

Built with caido-community/sdk-go and modelcontextprotocol/go-sdk.

License

MIT