Reversee MCP tools
Reversee exposes 19 Model Context Protocol tools so AI agents — Claude Code, Cursor, or any MCP client — can inspect and control its reverse proxy: search and summarize captured traffic, replay requests, install interceptors for mocking and fault injection, and decode JWTs and gRPC. Read-only by default; the proxy-changing tools stay locked until you opt in.
Setup
Launch the Reversee app, then register the server. No config files, no API keys.
Claude Code
claude mcp add reversee -- npx -y reversee-mcp
Cursor — ~/.cursor/mcp.json
{
"mcpServers": {
"reversee": { "command": "npx", "args": ["-y", "reversee-mcp"] }
}
}
How access works
The bridge talks to the app over a token-authenticated local socket (Unix domain socket / Windows named pipe, mode 0600) — never a TCP port. Only your user account can reach it.
--allow-mcp-control). When the app isn't running, every call returns a
clear “launch Reversee” message.
Every captured request has a stable, monotonic trafficId — assigned once,
never reused, never reset (not on clear, not on a proxy restart). It's the durable
handle you pass to get_traffic_entry and replay_request.
The 19 tools
Descriptions below are verbatim — this is exactly what an agent reads in the
tools/list response. The app owns this catalog and serves it to the bridge
at startup, so tools added in an update reach agents automatically.
Orientation & status
Current Reversee state: app version, whether the proxy is running, listen/destination config, traffic and breakpoint counts.
No parameters.
Run setup checks: destination configured, ports valid, root certificate present, proxy process state.
No parameters.
Export diagnostics: versions, platform, full settings, proxy state, traffic count, breakpoints, log location.
No parameters.
Configuration & proxy control
Full Reversee proxy configuration (listen/destination, interceptors, rewrite flags).
No parameters.
Update Reversee configuration. Accepts a partial settings object; unknown keys and invalid values are ignored. Keys: listenProtocol/destProtocol (http|https), listenPort/destPort (1-65535), dest (host), interceptRequest/interceptResponse (bool), requestInterceptor/responseInterceptor (JS source), rewriteRedirects/rewriteHost/allowSelfSignedUpstream (bool). Requires "Allow MCP to Control the Proxy" enabled in the app. Returns the resulting config.
patch (object, required) — partial settings object.
Start the reverse proxy with the current configuration. Requires control to be enabled in the app.
No parameters.
Stop the reverse proxy. Requires control to be enabled in the app.
No parameters.
Restart the proxy worker process (also recovers from a wedged interceptor). Requires control to be enabled in the app.
No parameters.
Inspecting traffic
List captured requests (newest last): method, URL, status, content type, total time. Bodies are elided; use get_traffic_entry for full details.
offset (integer ≥ 0), limit (integer 1–200, default 50).
Filter captured requests server-side so you fetch only what matters (avoids dumping everything). All filters combine with AND. Bodies are elided in results; use get_traffic_entry for full detail.
text, method, status (e.g. 404,
"2xx", ">=400"), urlContains,
urlRegex, contentType, header,
bodyContains, minTotalMs, hasError,
offset, limit.
Aggregate view of all captured traffic: counts by status class and method, content types, top hosts, the error requests, and the slowest requests. Use this to orient before drilling in.
slowest (integer 1–50, default 5).
Full details of one captured request: headers, bodies, timings, a copy-pasteable curl command, the upstream target, and any decoded JWTs found in its Authorization header or cookies.
trafficId (integer, required).
Decode a JWT (header + claims, with exp/iat parsed). Inspection only — the signature is not verified.
token (string, required) — a leading Bearer is fine.
Acting on traffic
Re-send a captured request to its upstream, optionally with edits — the agent way to test a hypothesis ("what if this header/body/status were different?"). Records a new traffic entry and returns it. Requires control to be enabled in the app.
trafficId (integer, required), overrides (object:
method, url, headers — a null value deletes a
header, body).
Install (or clear/toggle) a request or response interceptor — arbitrary JavaScript
that rewrites traffic on the fly, for mocking, fault injection, or header rewriting.
The code runs per matching request in a sandbox. Request interceptors can mutate
requestParams (host, path, method, port, headers, body). Response
interceptors can mutate responseParams (statusCode, headers, body) and
read requestParams. Example (force a 500):
responseParams.statusCode = 500; responseParams.body =
"{\"error\":\"injected\"}";. Requires control to be enabled in the app.
kind ("request" | "response", required),
code (string — omit to leave unchanged),
enabled (boolean).
Breakpoints & gRPC
List the configured breakpoint rules (URL regex + HTTP methods).
No parameters.
List saved protobuf specs used to decode gRPC traffic (id, name, source) plus any compile errors.
No parameters.
Save a protobuf spec for decoding gRPC traffic. Provide raw .proto text (source "proto") or a base64-encoded FileDescriptorSet (source "descriptor"). Returns the updated spec list and compile errors. Requires "Allow MCP to Control the Proxy" enabled in the app.
name (string, required), source ("proto" |
"descriptor", required), content (string, required).
Delete a saved protobuf spec by id. Requires "Allow MCP to Control the Proxy" enabled in the app.
id (string, required).
Agent workflows
A few end-to-end patterns these tools were designed for.
summarize_session to orient → search_traffic with
hasError: true or status: ">=400" to find failures →
get_traffic_entry on the interesting ids for full detail.
Find the failing request, then replay_request with a changed
header/body/url and compare the new entry — no client changes needed.
set_interceptor (response) to force a status or body,
drive the client, then clear it with enabled: false.
get_traffic_entry surfaces decoded JWTs inline;
decode_jwt inspects a token in hand. Load a schema with
add_proto_spec and gRPC messages come back as JSON.
Prefer no UI? reversee --headless --allow-mcp-control runs the proxy + MCP
socket with no window, for CI- or agent-driven automation. See the
headless docs.