MCP tool reference

red-clippy mcp exposes 82 tools. This page groups them by area so you can see what is covered. The authoritative descriptions and JSON schemas come from tools/list on the running server, which is what your agent actually reads.

Every tool is scoped to the organization the API key belongs to. Tools taking a pentest_id accept the session pin instead when the server was started with --pentest or RED_CLIPPY_PENTEST.

Engagements

Tool	What it does
`list_pentests`	List pentests, most recent first, paginated. Filters on free text and status.
`create_pentest`	Create an engagement. The code is immutable afterwards.
`get_pentest_summary`	One snapshot: severity counts, totals for findings, recon, assets and nmap scans, recon counts by kind, the testable in-scope asset count, five recent findings and scans, and phase progress.
`pentest_coverage`	Check coverage rollup across every asset opened so far.

Engagement phases

Tool	What it does
`list_phases`	List the phases for a pentest.
`add_phase`	Add a custom phase.
`mark_phase`	Set a phase’s status.
`delete_phase`	Remove a phase.

Red Team Instructions

Tool	What it does
`get_instructions`	Return the resolved document and the level it came from.
`set_instructions`	Write an override at the org or pentest level.
`reset_instructions`	Delete the override at a level, falling back to the next one down.

Assets

Tool	What it does
`list_assets`	List scope units, with filters.
`create_asset`	Create one.
`get_asset`	Fetch one by id, including its attributes JSON.
`update_asset`	Patch one by id.
`delete_asset`	Delete by id.
`delete_asset_by_value`	Delete by value. Cascades observations and check runs, and reports how many findings still tag the value.
`set_asset_marking`	Set scope and reachability by value.
`bulk_set_asset_marking`	Apply the same marking to many values in one transaction.
`list_asset_aliases`	List aliases pointing at a canonical asset.
`set_asset_alias`	Mark one asset as an alias of another.
`clear_asset_alias`	Detach an alias, making it a standalone asset again.
`promote_observation`	Turn an observation into its own asset.
`demote_asset`	The inverse: turn an asset back into an observation under its parent.

Observations and ports

Tool	What it does
`list_observations`	List observations for a pentest, paginated.
`create_observation`	Add one.
`bulk_observations`	Add many in one transaction. This is the one to use after a recon run.
`get_observation`	Fetch one by id.
`update_observation`	Patch one by id.
`delete_observation`	Delete one by id.
`observations_for_asset`	Everything attached to one asset, unpaginated.
`list_ports`	Engagement-wide open port and service search.

IP ranges

Tool	What it does
`list_ip_ranges`	The customer-declared perimeter, which is not the same thing as asset rows.
`add_ip_range`	Declare a range.
`update_ip_range`	Replace the editable fields of one.
`apply_ip_range`	Declare a range and fan its scope decision out to every IP asset inside it.
`delete_ip_range`	Remove a declared range.
`asset_ranges`	Which declared ranges contain a given address.
`get_range_map`	The unified scope tree: declared ranges, discovered clusters, loose blocks, singletons.

API endpoints

Tool	What it does
`list_api_endpoints`	List endpoints on an `api` asset.
`add_api_endpoint`	Attach one.
`add_api_endpoints_bulk`	Attach many in one call, for importing a specification.
`get_api_endpoint`	Fetch one with its JSON fields parsed.
`update_api_endpoint`	Patch one.
`delete_api_endpoint`	Delete one.
`export_api_endpoint_curl`	Build a copy-pastable cURL command using the parent asset as the base URL.
`export_api_asset_openapi`	Synthesise an OpenAPI 3.1 document from every REST endpoint on the asset.

Methodology checks

Tool	What it does
`list_checks`	The catalogue for one asset, with current status per check.
`mark_check`	Set one check’s status and notes.
`bulk_mark_checks`	Flip many checks on a single asset to the same status, atomically.

Findings and evidence

Tool	What it does
`create_finding`	Record a finding.
`list_findings`	List findings for a pentest, paginated and filterable.
`get_finding`	Fetch one in full: details, impact, proof of concept, remediation, CVSS, tags.
`update_finding`	Patch one.
`delete_finding`	Delete one, and its attachments.
`attach_evidence`	Upload a file against a finding.
`list_evidence`	List a finding’s attachments. Metadata only, no bytes.
`delete_evidence`	Delete an attachment by id.

create_finding’s description carries writing guidance the agent will follow: confirm with the operator before recording a finding, keep details, impact and remediation to a paragraph each, keep scope identifiers out of the title, and describe what needs to change in remediation rather than emitting commands, config snippets or library versions that may be wrong for the target’s stack.

Asset working files

Tool	What it does
`list_asset_files`	List files and folders under an asset’s directory.
`read_asset_file`	Read one file.
`write_asset_file`	Create or overwrite one.
`create_asset_folder`	Create an empty folder.
`delete_asset_file`	Delete a file, or a folder recursively.

Tool output

Tool	What it does
`ingest_tool_output`	Import a scanner report. Auto-detects the format, writes assets, observations, findings and the raw scan in one transaction.
`add_nmap`	Attach raw nmap output as a scan record.
`get_nmap_scan`	Retrieve one scan by id, including its raw output.

The scan engine

Tool	What it does
`list_scan_tools`	The tool registry by stage, with availability on this host.
`scan_coverage`	Funnel progress, plus how many hosts are waiting for the next stage.
`scan_coverage_by_range`	The same, broken down per declared in-scope range.
`mark_covered`	Record targets as already scanned so future launches skip them.
`enqueue_scan`	Launch a run.
`list_scans`	Recent runs with status and progress counts.
`get_scan`	One run with its per-target tasks.
`skip_scan_task`	Skip one target inside a run, killing it if mid-scan.
`cancel_scan`	Cancel a running scan.
`delete_scan`	Delete one finished run.
`clear_scans`	Bulk-delete finished runs.

Attack graph

Tool	What it does
`link`	Create a directed edge between two nodes (observation, asset or finding) with a free-form relation.
`unlink`	Delete an edge by id.
`neighbors`	Everything reachable from a node up to `depth` edges (default 1, max 5), in a given direction.
`attack_paths`	Paths from one node to another, up to `max_depth` hops (default 5, max 8).

Search

Tool	What it does
`org_search`	Keyword search across every source table in the organization.

Keyboard shortcuts

Red Clippy Documentation