Running an engagement with an agent

An engagement runs in three parts. You set it up, the agent tests and records, and you supervise and correct. This page describes that loop.

The handshake

When your client starts the MCP server, three things reach the agent before its first tool call:

1. A statement that Red Clippy is the system of record for this engagement, and that assets, observations, checks and findings belong in it rather than in the transcript.
2. If the session is pinned, which engagement it is pinned to, so tools taking a pentest_id default to it.
3. The Red Team Instructions document in full, resolved for this engagement.

The third item matters most. An agent that has to ask for the doctrine will often not bother, so it arrives in the handshake instead. get_instructions re-reads it on demand.

Setup

Create the pentest. Code, name, dates, and the scope text from the engagement letter. Do this in the browser: it takes a minute, and the scope text is what both you and the agent read before touching anything. See Pentests.

Declare the scope. Add the domains, hosts and IP ranges you are authorised to test, and mark anything excluded as out of scope. Type them in, or paste the customer’s list to the agent and have it enter them. Either way, an agent checks these markings before touching anything. See Scope and assets and The network view.

Connect the agent, pinned to this engagement. See Connecting an agent over MCP.

Testing

From there the agent runs the tools it would run anyway, from its own shell, and posts the results back. In practice that means:

Recon. Subdomain enumeration, DNS, certificate transparency, content discovery. Raw output goes in with ingest_tool_output, one call per scan file regardless of size. Anything it worked out itself goes in with create_asset or bulk_observations.

Triage. Real scope units become assets with create_asset or promote_observation. Everything else stays an observation. This step decides whether your asset list is still usable in a week, so say in your first message what you consider asset-worthy.

Scope decisions. set_asset_marking and bulk_set_asset_marking for in and out of scope and reachability; add_ip_range and apply_ip_range for whole CIDRs.

Coverage. list_checks returns the catalogue for an asset with its current status. As the agent clears ground it calls mark_check or bulk_mark_checks with notes, so coverage is recorded as it happens rather than reconstructed afterwards.

Findings. create_finding with severity, CVSS vector, CWE, details, impact, proof of concept and remediation, tagged asset:<value> and check:<code>. attach_evidence uploads the screenshot or the raw output that proves it.

Wrap-up. pentest_coverage and get_pentest_summary say what is left.

Supervision

Watch it land in the browser, live. Everything the agent writes is an ordinary row you can edit, reclassify or delete, and it will see your edits on its next read.

Three habits are worth building:

Check the coverage view. The engagement Overview percentage and the per asset check counts show what has actually been tested. An agent that has filed six findings but cleared nine checks has not tested the target. It has skimmed it. See Workspace and coverage.

Read the findings, not the summary. The agent’s account of its own work is a summary of a summary. The finding rows are the deliverable, and each one has a proof of concept field that either proves the claim or does not. See Findings.

Correct the classification. Severity, status, and whether something is a finding at all are judgement calls. Reclassifying an agent’s high to medium, or its finding to a false positive, takes ten seconds in the browser and is exactly the kind of decision a human should be making.

Multiple engagements

An MCP server is pinned to at most one engagement and an API key belongs to exactly one organization. Run one MCP entry per active engagement, in one working folder per client, and switch engagements by switching servers. Nothing stops you pointing two clients at the same server. The separation exists so that you do not have to rely on an agent keeping two clients’ data apart by itself.

Working without an agent

Everything above goes through the same REST API the panel uses. Anything an agent records you can enter, correct or delete yourself; anything you enter it can read. Run an engagement entirely by hand, entirely through the agent, or switch between the two mid-session.