Agents and MCP
Plonix lets an AI agent work with your live project: the traffic you captured, the map of the target, detected technologies, scope and findings. It does this through MCP, the protocol coding agents such as Claude Code use for tools.
Agents get read-only access. They can look at everything the project holds and cannot send requests, change scope or record, edit or delete findings. The one thing they can leave behind is a suggested edit to a request you are editing on the Bench, which you review and apply yourself (see Suggested Bench edits). The engine enforces this, not the agent.
Connect Claude Code#
In the Plonix window, open Agents › Setup and press Connect Claude Code. Plonix adds itself to Claude Code for all your projects; there is nothing to install or put on your PATH first. The button shows when Claude Code is installed on this computer.
From a terminal, the same in one command:
plonix connect claude
The plonix command comes with the app: on a Mac choose Plonix › Install Command Line Tool… once; on Windows the installer puts it on your PATH (open a new terminal after installing). If you build from source, cargo install --path crates/plonix-cli installs it.
Plonix · connect Claude Code
✓ Agent token ~/.plonix/agent-token (read-only)
✓ Claude Code added MCP server "plonix" for all your projects: /Users/you/.cargo/bin/plonix mcp
What the agent can do (read-only; a Bench edit is only suggested, for you to apply):
status · search_traffic · get_request · get_insights · get_messages · list_hosts · list_endpoints · detected_tech · get_scope · list_findings · list_users · get_access_check · list_skills · get_skill · findings_report · propose_bench_edit · propose_request
Not allowed:
✗ Send or replay requests
✗ Accept, reject or remove scope rules
✗ Record, edit or delete findings
✗ Open browsers, sign in to the window or stop the engine
✗ Install, update or remove anything from the Market
✗ See, edit, forward or drop requests held in Intercept
✗ Apply a suggested edit to a Bench draft, or start a payload run
plonix connect claude runs claude mcp add-json for you. Options:
--scope user(default) makes Plonix available in every project,--scope localonly in the current directory,--scope projectwrites a shared.mcp.jsonin the current directory.--printchanges nothing and prints the command and the.mcp.jsonentry to add yourself. This is also what you get when theclaudecommand isn't installed.
Running it again replaces the earlier entry, so it is safe after moving or upgrading Plonix.
Then start capturing (plonix open <target>, or open Plonix.app) and ask Claude Code, for example:
Use Plonix to find in-scope API endpoints that returned errors, then read the most interesting request and tell me what stands out.
Using Plonix, list every endpoint on the target that takes an id parameter and group them by host.
Look at Plonix scope suggestions and explain which ones really belong to the target and why.
The Agents screen in the Plonix window (⌘8) shows what each agent reads as it works, and its Setup panel lists which agents are connected and what they are allowed to do (see The Agents screen).
Other MCP clients#
Any MCP client can run Plonix as a stdio server:
{
"mcpServers": {
"plonix": { "type": "stdio", "command": "plonix", "args": ["mcp"] }
}
}
Set PLONIX_HOME in the server's environment if your data is not in ~/.plonix.
Tools#
| Tool | What it returns |
|---|---|
status | Project, capture counts, scope rules, pending suggestions, proxy address |
search_traffic | Captured requests matching a query (the same search language as the window and plonix search), newest first, with paging |
get_request | One request and its response in full, with decoded bodies (clipped to max_body_chars) |
get_insights | What stands out in a request: decodable tokens such as JWTs, personal data, secrets |
get_messages | The WebSocket messages sent over the connection a handshake opened, oldest first |
list_hosts | Every host seen, with request counts and scope decision |
list_endpoints | Methods, paths, statuses and parameter names seen on a host |
detected_tech | Technologies detected per host, with confidence and evidence |
get_scope | Scope rules and suggested domains with their evidence |
list_findings | Findings with severity, status, description and evidence request ids |
findings_report | The findings as a Markdown report with their evidence requests and responses (bodies clipped); false positives left out unless asked for. Evidence on hosts outside scope is left out when agents see in-scope traffic only |
list_users | The users you saved to test as: name, note, and which headers and cookies each carries, by name only. Credential values are never shared |
get_access_check | The last Access check you ran: each request replayed as every saved user and signed out, with status, size and Plonix's notes. Rows on hosts outside scope are left out when agents see in-scope traffic only |
propose_bench_edit | Leaves a suggested edit to a Bench draft for you to review: the draft id, a summary and the complete edited request. Sends nothing and changes nothing |
propose_request | Leaves a new request for you to try, such as a captured request with another id: a summary, and a captured request id to start from or the full request. It waits above the Bench with Open on the Bench and Discard. Sends nothing |
Every tool is marked read-only in its MCP annotations, except propose_bench_edit and propose_request: each stores a suggestion, so it is marked as not read-only, but it is not destructive and never reaches the network.
Suggested Bench edits#
When you ask Claude about a request on the Bench, the prompt carries that draft's id and invites Claude to propose a concrete edit with propose_bench_edit. The tool takes the draft id, a short summary and the complete edited request (method, URL, headers, body).
- The engine only stores the proposal, in memory, for that draft. It checks that it is a request the Bench could hold (an
http/httpsURL, a valid method and header names, no line breaks in header values, sane sizes) and keeps a few per draft. It never sends it and never touches the draft. - The Bench shows it as a diff against your draft as it is now, with Apply to draft and Discard (bench.md). Applying only changes the draft; sending stays your click on Send, through the usual scope check.
- JWTs: Claude has no signing key, so an edited token keeps its original signature and is marked unsigned until you re-sign it in the Lens. A signature Claude made up is replaced with the original.
- Agents can only add a proposal (
POST /api/bench/proposals). Listing, comparing, applying and discarding are yours (those routes are refused to the agent token), and so are sending and runs. - Claude can also suggest a request of its own with
propose_request(no draft needed). It shows in a strip above the Bench tabs, Claude suggests trying, with the method, URL and why; Open on the Bench puts it in a new tab for you to look at and send, Discard drops it. An agent that sees in-scope traffic only cannot suggest a request to another host. - Switch it off in Settings › AI agents (Suggest requests and edits on the Bench): the tool disappears and the route is refused with
capability_off.
In the in-app conversation, Claude's proposal shows up as Suggested an edit to the request, with Review on the Bench once the answer is done. A Claude Code session in a terminal can propose too, as long as you pass it the draft id from the prompt (Copy prompt and Open in Terminal include it).
Ask Claude Code from the app#


The Plonix window has an Ask Claude button on a request (the Lens), a finding, a host (the Map), a scope suggestion and a request you are editing on the Bench (where Claude can also suggest an edit). It opens a sheet that:
- writes a question suited to that spot, which you can edit;
- shows exactly what will be shared, split into named parts (request, response, what Plonix spotted, technologies, endpoints, scope evidence), each with its size, and lets you untick any part;
- clips each request and response body, and estimates the total size against your limit;
- warns, and makes you confirm, when the context is larger than your limit, so a huge payload is never sent silently.
Ask Claude runs Claude Code on this computer and shows the answer in the sheet as it is written. The run is wired to Plonix's read-only MCP server and nothing else: your other MCP servers are not loaded, and Claude Code's shell, file, web and sub-agent tools are switched off, even if your own Claude Code settings allow them, so text hidden in captured traffic has nothing to act with. The answer is formatted with headings, lists, tables and code blocks you can copy. While it works, a line under the conversation says what Claude is doing (thinking, looking at traffic, writing the answer), how many tokens it has read and written, and how long it has taken. If Claude Code goes quiet, the sheet says so; after two minutes of silence, or five minutes in all, the run is stopped with a message saying why.
Copy prompt puts the prompt on your clipboard. Open in Claude Code writes the prompt to a private file under $PLONIX_HOME/claude/ and opens Claude Code in a new Terminal window reading that file, so captured text never goes on a command line. If the Plonix MCP server is connected in that session, Claude Code can follow up with the read-only tools.
The Agents screen#
The Agents screen is where you work with Claude on the project as a whole:
- Ask box. Ask about the whole project, such as what to look at next or which hosts belong to the target. Under the box, skills start with one click (a skill that needs a host or a request id asks for it first), and a few starter questions sit next to them.
- From Claude. Turn on Watch my traffic and Claude keeps an eye on the project while you browse. When new in-scope traffic arrives and then goes quiet for a moment, Claude reads it and leaves a few items here: a short digest of what is new, notes on requests worth a look, and leads, each with one place to act on it (open the request, the Bench, a scan of that host, an access check, or a new finding). Look now asks Claude to look right away. Items you dismiss steer it away from suggesting similar ones. Unread items sit at the top, each with a coloured tag for its kind (a red LEAD, a blue NOTE, a green NEW for what is new) and the request it is about. The sidebar shows how many items are unread. Claude only reads: nothing is sent unless you click. Looks stop for the day once they reach the daily token limit you choose (200k by default); the day is your local day. Each pause gets at most one look, at the newest requests, and reopening a project starts watching from then on, so a project never spends tokens on old traffic by itself. The watcher is off until you turn it on.
- Working or idle. Next to the screen's title, a dot shows whether an agent is Working (Claude is looking at your traffic or answering, or a connected agent is reading the project), Idle (with when it was last active), or Off.
- Usage by day. The button under the inbox opens the tokens Claude used in this project each day: watching and Ask Claude, side by side, for the last 90 days.
- Open an item. Click an item to open it in place: the whole note, the request it is about (method, path and status, one click to open it), what to do next, ✦ Ask Claude about this to talk it through, and everything Claude read on the look that produced it. Click it again to close it.
- Claude and Traffic. The right column switches between ✦ Claude, where you ask and pick up your conversations, and Traffic, what agents have read. The dot on Traffic turns green while an outside agent is connected.
- Conversations. Every question you ask here, or with Ask Claude anywhere in the app, is saved with the project. Open a conversation to read it again, or ask a follow-up: Claude picks up the same session, so it remembers what was said. The newest 60 conversations are kept, and you can delete any of them.
- Traffic. Each request an agent makes appears in a feed in plain words, such as "GET /v1/orders/32", "Endpoints on api.example.com" or "Searched traffic for login". Click an entry to open it in Traffic, the Map, Scope or Findings. Requests an Ask Claude conversation makes appear under that conversation's title. Refused requests are marked. The feed is kept while the project is open.
- Setup holds the rest: who is connected, the agent settings, how to connect Claude Code or another MCP client, what agents may do, and the skills. It opens on its own when nothing has been set up yet.
Saved conversations, the inbox and the activity feed are for you only. Agents cannot read any of them.
Settings#
Settings › AI agents holds these choices, for all projects (stored in $PLONIX_HOME/agents.json, so a change made in one window reaches every open project). The Agents screen shows a summary and a link there:
- On/off. Turn agent access off and every agent request is refused (
agents_disabled). - What agents can see. In-scope hosts only (the default) limits traffic, hosts, endpoints and technologies to hosts you accepted into scope; Everything captured includes out-of-scope and third-party traffic.
- Tools agents get. Switch off groups of capabilities (captured requests, insights, the map, scope, findings, scan advice, suggesting Bench edits). A switched-off capability is refused (
capability_off) and its MCP tools disappear fromtools/list. - Ask Claude. The context-size limit that triggers the warning, and how far each body is clipped.
Agents can read this policy (to explain a refusal) but can never change it: the settings route is in no mode's capability list.
How access is enforced#
plonix mcpsigns in to the engine's local API with its own token,~/.plonix/agent-token(mode0600). It never reads the full API token.- The engine checks every request made with the agent token against a fixed list of allowed routes (
crates/plonix-core/src/access.rs). Today that list contains only reads, plusPOST /api/bench/proposals, which stores a suggested Bench edit and nothing else. Anything else (/api/send,/api/replay,/api/scope/*,POST /api/findings,/api/ui/launch,/api/browser/open,/api/shutdown, every/api/interceptand/api/replaceroute) is refused with403 agent_not_allowed, and the refusal is shown on the Agents screen. - The API stays loopback-only. Plonix never sends captured traffic anywhere; the agent reads it on your machine.
- The data-scope and capability settings are applied in the same middleware, so an agent sees only what you allow whatever it asks for.
Captured traffic can include passwords, session cookies and API keys. Whatever the agent reads becomes part of its conversation, so connect only agents you trust with that data.
Later: an opt-in active mode#
The access model is built to grow one step, without loosening anything that exists today:
- A new
AgentMode::Active, switched on by you in Settings › AI agents or the CLI, stored per project. An agent can never switch it on itself. - In that mode only,
POST /api/sendandPOST /api/replayjoin the allowed routes. Both already go through scope enforcement, so an agent could only reach hosts you accepted into scope. - Matching MCP tools appear only when the engine reports that mode.
Changing scope, recording findings and controlling the engine stay with you in every mode. Active mode is not built yet.
Skills#
Skills are playbooks for one job in Plonix (get to know a host, explain a request, draft a finding). plonix mcp offers them as MCP prompts, so Claude Code lists them as /mcp__plonix__<name> commands, and as the list_skills and get_skill tools. A skill can only use what these settings allow: when a capability it reads is switched off, agents are not offered it. More skills come from the Market. See market.md.