Skip to content
Back to search

caido-opencode-mcp-connector

Connect the Caido web proxy to the opencode AI agent through caido-mcp-server: one script to install, authenticate, configure, verify and launch.

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/akobe-ajibolu--caido-opencode-mcp-connector/badge.svg)](/listings/akobe-ajibolu--caido-opencode-mcp-connector)

HTML

<a href="/listings/akobe-ajibolu--caido-opencode-mcp-connector"><img src="/api/listings/akobe-ajibolu--caido-opencode-mcp-connector/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.

git clone https://github.com/Akobe-Ajibolu/caido-opencode-mcp-connector.git
cd caido-opencode-mcp-connector

# 1. Start Caido and open a project.
# 2. Set everything up, verify it, and launch opencode:
./connect.sh

The first run opens an authorization request in Caido/your browser. Approve it once; the token is stored in `~/.caido-mcp/` and refreshed automatically.

After that, ask opencode things like:

List the last 20 POST requests to /api in Caido
Show me requests that returned 500 errors on example.com
Replay request 1423 with the user id changed to 2 and compare the responses
Create a Caido finding for the IDOR on request 1423
Summarise the results of Automate session 1

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 · 189 lines · 1 finding marked
  1. # caido-opencode-mcp-connector
  2. Connect the [Caido](https://caido.io) web proxy to the [opencode](https://opencode.ai) AI coding agent, so opencode can search your proxy history, replay requests, read Automate results and record findings.
  3. opencode has no built-in Caido integration. It does support MCP servers, and [caido-mcp-server](https://github.com/c0tton-fluff/caido-mcp-server) exposes Caido as one. This repo is the glue: one script that installs, authenticates, configures, verifies and launches the whole chain. It also documents the problems you're likely to hit along the way.
  4. ```mermaid
  5. flowchart LR
  6. A[opencode] -- "MCP over stdio" --> B[caido-mcp-server]
  7. B -- "GraphQL + OAuth token" --> C[Caido]
  8. C -- "proxies" --> D[Target app]
  9. ```
  10. opencode launches `caido-mcp-server serve` as a child process and talks MCP to it over stdin/stdout. The server translates each tool call into Caido GraphQL API calls, using a token it got from `caido-mcp-server login`.
  11. ## Requirements
  12. | Component | Notes |
  13. |-----------|-------|
  14. | [Caido](https://caido.io) | Running, with a project open. Default address `http://127.0.0.1:8080` |
  15. | [opencode](https://opencode.ai) | Tested with **v2.3.2**. 1.x config format is also supported (see [Config format](#config-format)) |
  16. | [caido-mcp-server](https://github.com/c0tton-fluff/caido-mcp-server) | Installed automatically if it's missing. Tested with **v4.5.0** (recommended) and v1.1 |
  17. | `bash`, `python3`, `curl` | Used by the script. No Python packages needed |
  18. Tested on Kali Linux. It should also work on other Linux distributions and on macOS.
  19. ## Quick start
  20. ```bash
  21. git clone https://github.com/Akobe-Ajibolu/caido-opencode-mcp-connector.git
  22. cd caido-opencode-mcp-connector
  23. # 1. Start Caido and open a project.
  24. # 2. Set everything up, verify it, and launch opencode:
  25. ./connect.sh
  26. ```
  27. The first run opens an authorization request in Caido/your browser. Approve it once; the token is stored in `~/.caido-mcp/` and refreshed automatically.
  28. After that, ask opencode things like:
  29. ```
  30. List the last 20 POST requests to /api in Caido
  31. Show me requests that returned 500 errors on example.com
  32. Replay request 1423 with the user id changed to 2 and compare the responses
  33. Create a Caido finding for the IDOR on request 1423
  34. Summarise the results of Automate session 1
  35. ```
  36. ## What `connect.sh` does
  37. Each step is checked, and the script stops with a specific message at the first one that fails.
  38. 1. **Caido is up.** It sends a request to `$CAIDO_URL/graphql`.
  39. 2. **Find the server.** It looks for `caido-mcp-server` in this order: `--bin` / `CAIDO_MCP_BIN`, the binary your existing opencode entry already uses, your `PATH`, then `~/.local/bin`. If none is found, it offers to install the latest upstream release.
  40. 3. **End-to-end probe.** It starts `caido-mcp-server serve` itself, does the MCP handshake, lists the tools, and calls `caido_list_requests`. If that fails, the usual cause is a missing or expired token, so it runs `caido-mcp-server login` and probes again.
  41. 4. **Write the opencode config.** It adds or updates the `caido` entry in `~/.config/opencode/opencode.json`. It saves a `.bak` backup first, and leaves your other settings and extra environment variables alone.
  42. 5. **Reload and verify opencode.** It restarts opencode's background service and waits until `opencode mcp list` shows `caido connected`.
  43. 6. **Launch opencode.** This step is skipped with `--check`.
  44. The script is safe to re-run: if nothing needs to change, it only verifies.
  45. **Upgrading from caido-mcp-server v1.x:** run `./connect.sh --bin /path/to/v4/caido-mcp-server`. Your existing login is migrated, so you won't need to log in again. Because v4 deletes the old token file during that migration, don't keep a v1 entry around (see [Troubleshooting](#troubleshooting)).
  46. ### Options
  47. ```
  48. ./connect.sh [options] [-- opencode args...]
  49. --check Set up and verify only; do not launch opencode
  50. --url URL Caido instance URL (default: $CAIDO_URL or http://127.0.0.1:8080)
  51. --bin PATH Path to caido-mcp-server (default: auto-detect)
  52. --serve-arg ARG Extra argument for 'caido-mcp-server serve' (repeatable)
  53. --name NAME MCP server name in opencode config (default: caido)
  54. --config FILE opencode config file (default: ~/.config/opencode/opencode.json)
  55. --remove Remove the MCP entry from the opencode config and exit
  56. -y, --yes Don't prompt (auto-install caido-mcp-server if missing)
  57. ```
  58. Examples:
  59. ```bash
  60. ./connect.sh --check # verify only
  61. ./connect.sh -- ~/engagements/acme # open opencode in a specific directory
  62. ./connect.sh --url http://10.0.0.5:8080 # Caido on another host
  63. ./connect.sh --serve-arg --read-only # agent can read history but never send traffic
  64. ./connect.sh --serve-arg --toolsets --serve-arg core \
  65. --serve-arg --compact # smaller tool list = less context used
  66. ./connect.sh --name caido-ro --serve-arg --read-only # a second, read-only entry next to 'caido'
  67. ./connect.sh --remove # undo the opencode config change
  68. ```
  69. `--read-only`, `--toolsets`, `--compact` and `--enforce-scope` are flags of caido-mcp-server v4.x. Older builds don't recognise them, so the probe in step 3 will fail. Measured against v4.5.0:
  70. | `serve` flags | Tools | Tool list size | Can send traffic |
  71. |---------------|-------|----------------|------------------|
  72. | *(default)* | 76 | 95.6 KB | yes |
  73. | `--enforce-scope` | 70 | 90.7 KB | in-scope hosts only |
  74. | `--read-only` | 32 | 35.3 KB | no |
  75. | `--toolsets core --compact` | 31 | 24.0 KB | yes |
  76. The tool list is loaded into the model's context at the start of every opencode session, so the smaller configurations leave more room for actual traffic.
  77. ## Manual setup
  78. If you'd rather not run the script, these are the steps it performs.
  79. ```bash
  80. # 1. Install the MCP server
  81. curl -fsSL https://raw.githubusercontent.com/c0tton-fluff/caido-mcp-server/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 110 on GitHub
  82. # 2. Authenticate against Caido (approve the request in Caido/your browser)
  83. CAIDO_URL=http://127.0.0.1:8080 caido-mcp-server login
  84. # 3. Register it with opencode
  85. opencode mcp add caido --global --env CAIDO_URL=http://127.0.0.1:8080 -- "$(command -v caido-mcp-server)" serve
  86. # 4. Reload and verify
  87. opencode service restart
  88. opencode mcp list # repeat if it says "No MCP servers configured" (see Troubleshooting)
  89. ```
  90. ### Config format
  91. opencode **2.x** (`~/.config/opencode/opencode.json`), also in [`examples/opencode.json`](examples/opencode.json):
  92. ```json
  93. {
  94. "mcp": {
  95. "servers": {
  96. "caido": {
  97. "type": "local",
  98. "command": ["/home/you/.local/bin/caido-mcp-server", "serve"],
  99. "environment": { "CAIDO_URL": "http://127.0.0.1:8080" },
  100. "enabled": true
  101. }
  102. }
  103. }
  104. }
  105. ```
  106. opencode **0.x/1.x** used the same entry, but directly under `mcp` without `servers` (`"mcp": { "caido": { ... } }`). `connect.sh` detects your opencode version and writes the right shape.
  107. Use an absolute path in `command`. opencode's background service doesn't necessarily have your interactive shell's `PATH`.
  108. ## Troubleshooting
  109. | Symptom | Cause / fix |
  110. |---------|-------------|
  111. | `opencode mcp list` says **No MCP servers configured**, even though the config is correct | opencode's background service hadn't loaded the config yet when you asked; it's a race at startup. Run the command again after a few seconds, or `opencode service restart`. `connect.sh` polls for this. |
  112. | opencode log shows `mcp transport error ... server error: context canceled` | The server process exited during startup. Usually it's a stale or broken binary. Rebuild or reinstall it, then run `./connect.sh --check` to get the real error from the probe. |
  113. | `Caido is not reachable` | Caido isn't running, or it listens on a different address. Start it, open a project, or pass `--url`. |
  114. | Probe fails with `Invalid token` / `token expired, no refresh token` | Run `CAIDO_URL=... caido-mcp-server login` again. `connect.sh` does this automatically. |
  115. | HTTPQL filters error out (e.g. a GraphQL type error on `HTTPQL`) | Old caido-mcp-server builds (v1.x) send the filter in a format newer Caido versions reject. Upgrade to v4.x, where HTTPQL filtering works. |
  116. | `no authentication token found` after upgrading, or with two caido-mcp-server versions side by side | v4 moves tokens to `~/.caido-mcp/tokens/<instance>.json`. The first time it runs, it takes over the old `~/.caido-mcp/token.json` and **deletes** it, which logs out any v1 build still in your config. Either point every entry at v4, or run `login` again with the old binary. |
  117. | Tools appear in `mcp list` but the model never uses them | Name the tool or Caido explicitly in your prompt ("use Caido to..."), or try a model that is better at tool use. |
  118. | Model context fills up quickly | Start the server with `--serve-arg --toolsets --serve-arg core --serve-arg --compact` (v4.x). |
  119. Where to look:
  120. - opencode logs: `~/.local/share/opencode/log/opencode.log` (`grep -i mcp`)
  121. - opencode effective config: `opencode debug config`
  122. - caido-mcp-server tokens: `~/.caido-mcp/`
  123. ## Security notes
  124. - **Only use this against targets you're authorised to test.** Through these tools, an AI agent can send real traffic via Caido Replay and Automate.
  125. - If you want the agent to analyse captured traffic without being able to send requests, use `--serve-arg --read-only`. To keep it inside your Caido project scope, use `--serve-arg --enforce-scope` (v4.x).
  126. - Newer caido-mcp-server builds redact `Authorization`, `Cookie` and API-key headers in tool output by default. Turning that off (`CAIDO_ALLOW_SENSITIVE_HEADERS`) sends real credentials to your model provider.
  127. - The Caido OAuth token in `~/.caido-mcp/` grants full API access to your Caido instance. Treat it like a password.
  128. ## Uninstall
  129. ```bash
  130. ./connect.sh --remove # remove the opencode entry (backup kept as .bak)
  131. rm -f ~/.local/bin/caido-mcp-server # if the script installed it
  132. rm -rf ~/.caido-mcp # stored Caido tokens
  133. ```
  134. ## Credits
  135. - [caido-mcp-server](https://github.com/c0tton-fluff/caido-mcp-server) by c0tton-fluff, which provides the MCP server this project wires up.
  136. - [Caido](https://caido.io) and [opencode](https://opencode.ai).
  137. This project is not affiliated with Caido or opencode.
  138. ## License
  139. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

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