Back to search
caido-opencode-mcp-connector
MCP serverGitHub
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
Markdown
[](/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
- # caido-opencode-mcp-connector
- 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.
- 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.
- ```mermaid
- flowchart LR
- A[opencode] -- "MCP over stdio" --> B[caido-mcp-server]
- B -- "GraphQL + OAuth token" --> C[Caido]
- C -- "proxies" --> D[Target app]
- ```
- 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`.
- ## Requirements
- | Component | Notes |
- |-----------|-------|
- | [Caido](https://caido.io) | Running, with a project open. Default address `http://127.0.0.1:8080` |
- | [opencode](https://opencode.ai) | Tested with **v2.3.2**. 1.x config format is also supported (see [Config format](#config-format)) |
- | [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 |
- | `bash`, `python3`, `curl` | Used by the script. No Python packages needed |
- Tested on Kali Linux. It should also work on other Linux distributions and on macOS.
- ## Quick start
- ```bash
- 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 `connect.sh` does
- Each step is checked, and the script stops with a specific message at the first one that fails.
- 1. **Caido is up.** It sends a request to `$CAIDO_URL/graphql`.
- 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.
- 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.
- 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.
- 5. **Reload and verify opencode.** It restarts opencode's background service and waits until `opencode mcp list` shows `caido connected`.
- 6. **Launch opencode.** This step is skipped with `--check`.
- The script is safe to re-run: if nothing needs to change, it only verifies.
- **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)).
- ### Options
- ```
- ./connect.sh [options] [-- opencode args...]
- --check Set up and verify only; do not launch opencode
- --url URL Caido instance URL (default: $CAIDO_URL or http://127.0.0.1:8080)
- --bin PATH Path to caido-mcp-server (default: auto-detect)
- --serve-arg ARG Extra argument for 'caido-mcp-server serve' (repeatable)
- --name NAME MCP server name in opencode config (default: caido)
- --config FILE opencode config file (default: ~/.config/opencode/opencode.json)
- --remove Remove the MCP entry from the opencode config and exit
- -y, --yes Don't prompt (auto-install caido-mcp-server if missing)
- ```
- Examples:
- ```bash
- ./connect.sh --check # verify only
- ./connect.sh -- ~/engagements/acme # open opencode in a specific directory
- ./connect.sh --url http://10.0.0.5:8080 # Caido on another host
- ./connect.sh --serve-arg --read-only # agent can read history but never send traffic
- ./connect.sh --serve-arg --toolsets --serve-arg core \
- --serve-arg --compact # smaller tool list = less context used
- ./connect.sh --name caido-ro --serve-arg --read-only # a second, read-only entry next to 'caido'
- ./connect.sh --remove # undo the opencode config change
- ```
- `--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:
- | `serve` flags | Tools | Tool list size | Can send traffic |
- |---------------|-------|----------------|------------------|
- | *(default)* | 76 | 95.6 KB | yes |
- | `--enforce-scope` | 70 | 90.7 KB | in-scope hosts only |
- | `--read-only` | 32 | 35.3 KB | no |
- | `--toolsets core --compact` | 31 | 24.0 KB | yes |
- 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.
- ## Manual setup
- If you'd rather not run the script, these are the steps it performs.
- ```bash
- # 1. Install the MCP server
- 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
- # 2. Authenticate against Caido (approve the request in Caido/your browser)
- CAIDO_URL=http://127.0.0.1:8080 caido-mcp-server login
- # 3. Register it with opencode
- opencode mcp add caido --global --env CAIDO_URL=http://127.0.0.1:8080 -- "$(command -v caido-mcp-server)" serve
- # 4. Reload and verify
- opencode service restart
- opencode mcp list # repeat if it says "No MCP servers configured" (see Troubleshooting)
- ```
- ### Config format
- opencode **2.x** (`~/.config/opencode/opencode.json`), also in [`examples/opencode.json`](examples/opencode.json):
- ```json
- {
- "mcp": {
- "servers": {
- "caido": {
- "type": "local",
- "command": ["/home/you/.local/bin/caido-mcp-server", "serve"],
- "environment": { "CAIDO_URL": "http://127.0.0.1:8080" },
- "enabled": true
- }
- }
- }
- }
- ```
- 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.
- Use an absolute path in `command`. opencode's background service doesn't necessarily have your interactive shell's `PATH`.
- ## Troubleshooting
- | Symptom | Cause / fix |
- |---------|-------------|
- | `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. |
- | 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. |
- | `Caido is not reachable` | Caido isn't running, or it listens on a different address. Start it, open a project, or pass `--url`. |
- | Probe fails with `Invalid token` / `token expired, no refresh token` | Run `CAIDO_URL=... caido-mcp-server login` again. `connect.sh` does this automatically. |
- | 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. |
- | `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. |
- | 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. |
- | Model context fills up quickly | Start the server with `--serve-arg --toolsets --serve-arg core --serve-arg --compact` (v4.x). |
- Where to look:
- - opencode logs: `~/.local/share/opencode/log/opencode.log` (`grep -i mcp`)
- - opencode effective config: `opencode debug config`
- - caido-mcp-server tokens: `~/.caido-mcp/`
- ## Security notes
- - **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.
- - 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).
- - 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.
- - The Caido OAuth token in `~/.caido-mcp/` grants full API access to your Caido instance. Treat it like a password.
- ## Uninstall
- ```bash
- ./connect.sh --remove # remove the opencode entry (backup kept as .bak)
- rm -f ~/.local/bin/caido-mcp-server # if the script installed it
- rm -rf ~/.caido-mcp # stored Caido tokens
- ```
- ## Credits
- - [caido-mcp-server](https://github.com/c0tton-fluff/caido-mcp-server) by c0tton-fluff, which provides the MCP server this project wires up.
- - [Caido](https://caido.io) and [opencode](https://opencode.ai).
- This project is not affiliated with Caido or opencode.
- ## License
- [MIT](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.