Fissure MCP bridge
An optional Model Context Protocol bridge that lets an MCP host (Claude Code) drive Fissure's local control API as an agent: check liveness, send a single request, run scans (poll-based), and read findings, with no point-and-click.
The bridge is a thin, stateless stdio process. All the real logic stays in the C engine behind the control API (see ../docs/11_CONTROL_API.md); the bridge only translates MCP tool calls into HTTP requests and returns the JSON.
Contents
fissure_control_client.py- a pure standard-library HTTP client for the control API (no third-party dependency). Importable and testable on its own, and usable directly from any Python script.fissure_mcp_bridge.py- the FastMCP stdio server. One MCP tool per route.
Where to find it
You do not need a source checkout: every package ships this directory
and the Claude skills next to the binary. With the .deb the
bridge is /opt/fissure/bridge/ and the skills are under
/opt/fissure/skills/; the Windows installer puts them in
bridge\ and skills\ under the install
directory; the AppImage carries them as usr/bin/bridge/ and
usr/bin/skills/, which you copy out once with
--appimage-extract. The exact commands are in step 1b of
docs/13_MCP_AND_SKILL_SETUP.md. Below,
<bridge-dir> is whichever of these directories you
use (or <repo>/bridge in a checkout).
Prerequisites
Enable the control API in Fissure: Settings -> Control API -> "Enable local control API" (or run
fissure serve --api-key <token>). Copy the port and the token shown there.Install the MCP Python SDK into a virtualenv (the client itself needs no third-party package; only
fissure_mcp_bridge.pyneeds the SDK). A venv keeps it isolated and gives you a concrete interpreter path to point the MCP config at:python3 -m venv ~/.venvs/fissure-mcp ~/.venvs/fissure-mcp/bin/pip install "mcp>=1.27,<2"v1.x is the stable line (tested with 1.28 and 1.30). If a stable v2 is out when you set this up and you prefer it, adjust the import (
from mcp.server import ...) per its migration guide and pin accordingly. Either way, pin a bounded version.
Registering with Claude Code
Add the bridge as a stdio MCP server, passing the URL and token as
environment variables (never hardcode the token). Point the command
after -- at the venv's python (the interpreter
that has mcp), not a bare python:
claude mcp add fissure-control \
--env SUITE_API_URL=http://127.0.0.1:8777 \
--env SUITE_API_TOKEN=<token-from-app-settings> \
-- ~/.venvs/fissure-mcp/bin/python <bridge-dir>/fissure_mcp_bridge.py
(With the .deb:
/opt/fissure/bridge/fissure_mcp_bridge.py.)
(Verify the exact flags with claude mcp add --help.)
After this, the host sees the tools below. Rotating the token in the app
means updating the env value in the MCP config; no code change.
Other clients (Claude Desktop, ChatGPT)
- Claude Desktop launches the same stdio bridge from an
mcpServersentry in itsclaude_desktop_config.json(command = the venv python, args = this script, env =SUITE_API_URL/SUITE_API_TOKEN). - ChatGPT needs a remote MCP server, not a stdio subprocess. Run the
bridge with a network transport
(
FISSURE_MCP_TRANSPORT=streamable-httpor=sse, optionalFISSURE_MCP_HOST/FISSURE_MCP_PORT, default127.0.0.1:8779) behind a trusted tunnel, and point the connector at the endpoint path:/mcpfor streamable-HTTP,/ssefor SSE (the bare host answers 404). The default is 8779, one above the control-driven proxy's default 8778 (POST /api/proxy/startwithout aport), so the two never collide. Alternatively, drive the HTTP control API directly from a Custom GPT Action.
Full step-by-step for all three clients (and installing the skills /
methodology) is in docs/13_MCP_AND_SKILL_SETUP.md.
Verifying the bridge
With the control API running
(fissure serve --api-key <token> or the Settings
toggle), a quick end-to-end check before registering:
# the control API answers (no token needed for status)
curl -s http://127.0.0.1:8777/api/status
# the bridge's client drives the API end to end (health, findings, a request,
# an async scan). SUITE_TARGET_URL must be a SECOND control instance's status
# endpoint: the test asserts GET 200 and POST 404 on it and then scans it, which a
# control /api/status satisfies exactly, and it is a different accept loop than the
# one under test (the single accept loop cannot serve a request nested inside its
# own call). Start a throwaway second instance on another port and point at it:
fissure serve --port 8780 --insecure >/dev/null 2>&1 & # tokenless, so a POST to its /api/status gives 404 not 401
SUITE_API_URL=http://127.0.0.1:8777 SUITE_API_TOKEN=<token> \
SUITE_TARGET_URL=http://127.0.0.1:8780/api/status \
~/.venvs/fissure-mcp/bin/python ../tests/mcp_bridge_smoke.py # prints SMOKE OK
The authoritative way to run it is make tests (the C
test test_mcp_bridge stands up both instances with the
right target and runs this script); the recipe above is the manual
equivalent.
The smoke test is a source-tree check:
tests/mcp_bridge_smoke.py is not shipped in the installed
layouts (the .deb, the AppImage and the Windows installer
ship only the two .py files and this README under
bridge/). From an installed package, verify with the
client's health() call instead, run from the installed
bridge directory (for example /opt/fissure/bridge):
SUITE_API_URL=http://127.0.0.1:8777 SUITE_API_TOKEN=<token> \
~/.venvs/fissure-mcp/bin/python -c \
"import fissure_control_client as a; print(a.health())"
# {'status': 'ok', 'name': 'fissure', 'version': '<x.y.z>'}
or, once the bridge is registered, ask the MCP host to call the
health tool.
Driving a whole engagement
The tools below are building blocks; to run a full bug-bounty engagement (scope, authenticated scan, manual confirmation, report) rather than a single call:
From Claude Code, use the shipped
fissure_bug_bountyskill (../.claude/skills/fissure_bug_bounty/in a source checkout; in an installed package it sits next to this directory, at../skills/fissure_bug_bounty/). It drives these MCP tools with the right methodology (scope-first, the poll pattern, confirming scanner leads by hand, evidence-driven reporting). Claude Code auto-discovers skills in the.claude/skills/of your working directory, so the skills are available whenever you run Claude Code inside the Fissure repo; to drive Fissure from another directory (say your target's own repo), or from an installed package, copy every skill folder into~/.claude/skills/(from a package:cp -r /opt/fissure/skills/* ~/.claude/skills/; from a checkout:cp -r .claude/skills/* ~/.claude/skills/). Register the bridge above, then just ask Claude:- Bug bounty / pentest: "test an authorized target" (the skill sets scope and confirms authorization before any active traffic).
- CTF / lab: "solve this CTF" or "capture the flag at
<url>", where the challenge itself is the authorization and the skill switches to flag-hunting mode (exploit to the flag; see the skill'sreferences/ctf.md, which is../.claude/skills/fissure_bug_bounty/references/ctf.mdin a checkout and../skills/fissure_bug_bounty/references/ctf.mdwhen installed).
From a plain Python script, import
fissure_control_clientdirectly (it needs no MCP SDK):import sys, time; sys.path.insert(0, ".") import fissure_control_client as api # SUITE_API_URL / SUITE_API_TOKEN from env api.set_scope(allow="target.test") # authorized target only job = api.start_scan("http://target.test/", active=True) jid = job["job_id"] while api.get_scan_status(jid)["status"] not in ("done", "cancelled", "error"): time.sleep(1) print(api.report(fmt="markdown")["report"])
See the "Automating a bug-bounty engagement" section of ../docs/11_CONTROL_API.md for the curl / Python / Claude walkthrough.
Tools
| Tool | Control-API route | Notes |
|---|---|---|
health |
GET /api/status |
Liveness / connectivity check |
send_request |
POST /api/request |
Send one request, return the response |
start_scan |
POST /api/scans |
Returns {job_id}; optional login object
for an authenticated scan |
get_scan_status |
GET /api/scans/{id} |
Status + progress |
get_scan_findings |
GET /api/scans/{id}/findings |
Findings once the job is done |
cancel_scan |
POST /api/scans/{id}/cancel |
Request cancellation |
get_findings |
GET /api/findings |
All control-API findings this session |
transform |
POST /api/transform |
Multitool encode/decode/hash |
smart_decode |
POST /api/smartdecode |
Auto-peel an encoding chain |
compare |
POST /api/compare |
Line/word/byte diff + similarity |
sequence |
POST /api/sequence |
Token randomness (shannon/monobit/chi2) |
jwt |
POST /api/jwt |
JWT decode/verify/sign/crack |
report |
GET /api/report?format= |
Export findings (+min_severity/host/source filters, risk score) |
intruder |
POST /api/intruder |
Payload-position attack (sniper/.../grep) |
discover |
POST /api/discover |
Content discovery (paths that exist) |
get_scope |
GET /api/scope |
Read the scope allowlist |
set_scope |
POST /api/scope |
Set the scope (applied to scans/intruder/discover) |
graphql |
POST /api/graphql |
GraphQL argument workshop (count/arg/mutate) |
cookie |
POST /api/cookie |
Signed-cookie workshop (detect/verify/sign/crack/decrypt) |
saml |
POST /api/saml |
SAML workshop (decode/inspect/edit/strip/xsw/genkey/sign/verify) |
inspect |
POST /api/inspect |
Decompose a request into headers/query/cookies/body |
scope_import |
POST /api/scopeimport |
Parse H1/Bugcrowd/vendor/host-list scope text |
js_transform |
POST /api/jstransform |
Run a user JavaScript transform over a string |
bcheck |
POST /api/bcheck |
Compile a .bcheck into a QuickJS check |
apispec |
POST /api/apispec |
Import an OpenAPI/Swagger/Postman definition |
apispec_fetch |
POST /api/apispecfetch |
Probe a live target for a served OpenAPI/Swagger spec and import it |
recon |
POST /api/recon |
Route recon-tool host/URL output into the inventory and scope |
headless_crawl |
POST /api/headlesscrawl |
Headless JS-render crawl (katana -headless) routed into the inventory |
jsmine |
POST /api/jsmine |
Mine endpoint URLs and secrets out of a JavaScript body |
smuggle |
POST /api/smuggle |
Probe a URL for HTTP request smuggling (desync) by timing |
massassign |
POST /api/massassign |
Probe for mass assignment (autobound privileged fields) + HTTP parameter pollution |
storedxss |
POST /api/storedxss |
Stored/second-order XSS by write-then-read canary correlation |
ssrf |
POST /api/ssrf |
Out-of-band blind SSRF, incl. gopher/dict alternate schemes (needs OAST) |
paramminer |
POST /api/paramminer |
Mine hidden parameters the target reacts to |
groupsend |
POST /api/groupsend |
Send a request group (seq/parallel/H2 race) |
wsrepeater |
POST /api/wsrepeater |
Open a WS, send one frame, collect replies |
jscheck |
POST /api/jscheck |
Run a scriptable (QuickJS) check vs a target |
authmatrix |
POST /api/authmatrix |
Replay under N identities -> access verdicts |
authz |
POST /api/authz |
Autorize-style access-control replay |
rolediff |
POST /api/rolediff |
Offline diff of two role site-maps |
plugins |
GET /api/plugins |
List bundled OSS-tool plugins + install state |
plugin_run |
POST /api/plugins/run |
Run an installed plugin vs a target -> findings |
plugin_install |
POST /api/plugins/install |
Build (not run) a dependency install command |
oast_start |
POST /api/oast/start |
Start the out-of-band (OAST) listener |
oast_stop |
POST /api/oast/stop |
Stop the OAST listener (hits stay readable) |
oast_status |
GET /api/oast/status |
running/port/base_url/count |
oast_mint |
POST /api/oast/mint |
Mint a canary {token,url} for a blind sink |
oast_poll |
GET /api/oast/poll?token= |
Whether a canary was hit (out-of-band proof) |
oast_history |
GET /api/oast/history |
All recorded OAST interactions |
projects |
GET /api/projects |
List projects/workspaces + the active one |
project_op |
POST /api/projects |
Create/delete/activate a project |
env |
GET /api/env |
The per-project environment library |
env_op |
POST /api/env |
Add/activate an env, set/remove a variable |
env_expand |
POST /api/env/expand |
Expand {{vars}} in text |
tags |
GET /api/tags |
Inline transform tags (custom + variables) |
tags_op |
POST /api/tags |
Set/remove a custom tag or a variable |
tags_eval |
POST /api/tags/eval |
Evaluate inline transform tags over text |
organizer |
GET /api/organizer |
The per-project saved-request queue |
organizer_add |
POST /api/organizer |
Stash a request (optionally in a collection) |
organizer_remove |
POST /api/organizer/remove |
Remove a saved request by id |
session_save |
POST /api/session/save |
Persist control findings to a named session |
session_load |
POST /api/session/load |
Merge a saved session back into the store |
report_pwndoc |
POST /api/report/pwndoc |
Push findings to a PwnDoc instance |
report_pdf |
POST /api/report/pdf |
Render HTML + run a PDF command over it |
proxy_start |
POST /api/proxy/start |
Start the control-driven intercepting proxy |
proxy_stop |
POST /api/proxy/stop |
Stop the proxy (history stays browsable) |
proxy_status |
GET /api/proxy/status |
running/host/port/flows/intercept |
proxy_history |
GET /api/proxy/history |
Captured flows (newest window) |
proxy_flow |
GET /api/proxy/history/{i} |
One flow's request/response |
intercept_status |
GET /api/proxy/intercept |
enabled/pending + the held request |
intercept_set |
POST /api/proxy/intercept |
Enable/disable interception |
intercept_resolve |
POST /api/proxy/intercept/resolve |
Forward (opt. edited) or drop the held request |
Scans use the poll pattern: start_scan returns a
job_id, the agent calls get_scan_status until
status is done, then
get_scan_findings. Pass a login login-config
object to start_scan for an authenticated scan (the job
reports status error if the login fails); see
resources/login/dvwa.json and
docs/12_DVWA_LAB.md. Each tool call is short and the agent
stays in control.
Configuration
Read from the environment (both SUITE_* and
FISSURE_* names are accepted):
SUITE_API_URL/FISSURE_API_URL- base URL, defaulthttp://127.0.0.1:8777.SUITE_API_TOKEN/FISSURE_API_TOKEN- the control-API token.SUITE_API_TIMEOUT/FISSURE_API_TIMEOUT- seconds to wait for a control-API reply, default 600. Several routes block until an external tool or a multi-request campaign finishes, so keep it generous; a non-positive or non-numeric value falls back to the default.
The MCP transport is read by fissure_mcp_bridge.py
only:
FISSURE_MCP_TRANSPORT-stdio(default),streamable-http(also accepted ashttporstreamable_http, served at/mcp) orsse(served at/sse).FISSURE_MCP_HOST- bind address of a network transport, default127.0.0.1.FISSURE_MCP_PORT- its port, default8779(an invalid value falls back to it). It sits one above the control-driven proxy's default 8778 so both can run with defaults.
Errors
- Connection refused -> the control API is off; enable it in the app settings.
401-> bad or missing token; updateSUITE_API_TOKEN.- Other non-2xx -> the engine's JSON error is surfaced.
Scope
Only scan targets you are authorized to test.
active/aggressive scans generate traffic and
intrusive probes; the same scope rules as the interactive scanner
apply.