> For the complete documentation index, see [llms.txt](https://copilot-docs.bugbase.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://copilot-docs.bugbase.ai/enterprise/settings/api-keys-and-mcp-server/mcp-tool-reference.md).

# MCP Tool Reference

Every Pentest Copilot platform MCP tool, what it does, and which roles and plans can use it.

This page lists every tool the platform MCP server offers. Exact argument types, accepted values, and limits come from each tool's input schema in your MCP client and from the `configuration_reference` returned by `get_setup_information`. Prefer those over this page when they differ.

Your client only lists the tools your API key may call. Calls to a tool outside the key's role or plan are refused, so a hidden tool cannot be used by guessing its name.

## Roles

A key has the role of the user who created it. See [API Keys & MCP Server](https://copilot-docs.bugbase.ai/enterprise/settings/api-keys-and-mcp-server.md#create-an-api-key).

* **Any** includes Viewer keys, which can only read.
* **Trial user** is the role of keys created in shared-trial workspaces.
* Tools marked **Admin, Trial user** are not available to Operator keys.

## Plan Availability

| Plans value                                   | Meaning                                                                                                                                                                                                            |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **All**                                       | Available on dedicated tenants and shared-trial workspaces.                                                                                                                                                        |
| **Dedicated only**                            | Network and Cloud assessments, agents, schedules, and organization settings. Not available in shared-trial workspaces.                                                                                             |
| **Dedicated; shared-trial with subscription** | GitHub-based code assessment. Shared-trial workspaces need an active subscription.                                                                                                                                 |
| **Debug mode only**                           | Direct graph edits. Only listed when debug mode is enabled for the tenant.                                                                                                                                         |
| **When AI configure is enabled**              | Only listed when AI configure is enabled for your deployment. See [AI Configure and Vetting](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-web-assessment/ai-configure-and-vetting.md#availability). |

In shared-trial workspaces, a call to a locked feature returns `... is only available in the enterprise deployment`.

## Common Behavior

* Each workspace sees and changes only its own data. An ID from another workspace is reported as not found.
* Tools that start scans enforce the same launch checks as the web app. See [Scan Launch Requirements](https://copilot-docs.bugbase.ai/enterprise/settings/api-keys-and-mcp-server.md#scan-launch-requirements).
* Tools that send traffic to your target are noted below: browser session validation, rate calibration, vetting, discovery and assessment launches, and agentic test runs.
* After a timeout, read current state before retrying a tool that creates or changes data.

## Getting Started

| Tool                    | What it does                                                                                           | Roles | Plans |
| ----------------------- | ------------------------------------------------------------------------------------------------------ | ----- | ----- |
| `get_setup_information` | Read the built-in setup manual and the tenant's live `configuration_reference`. Read-only; call first. | Any   | All   |

## Targets and Assets

| Tool                 | What it does                                                                                                     | Roles                       | Plans           |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------- |
| `list_assets`        | List and search targets and discovered entities by type, with paging and an optional root filter.                | Any                         | All             |
| `get_asset`          | Read one entity in full. For a `CodeSnapshot`, pages through SBOM or AI-BOM inventory.                           | Any                         | All             |
| `create_root_target` | Create a Domain, Subnet, CloudScope, or APKFile root target. Returns ownership-verification details for Domains. | Admin, Operator, Trial user | All             |
| `delete_root_target` | Delete a root target and everything discovered under it.                                                         | Admin, Operator, Trial user | All             |
| `create_asset`       | Add an entity to the graph, optionally under a parent you own. Debug use.                                        | Admin, Operator             | Debug mode only |
| `delete_asset`       | Delete one entity; `force_delete` also removes its children. Debug use.                                          | Admin, Operator             | Debug mode only |

## Exploit Graph

| Tool                   | What it does                                                             | Roles | Plans |
| ---------------------- | ------------------------------------------------------------------------ | ----- | ----- |
| `search_graph`         | Full-text search across graph entities, filtered by label, root, or run. | Any   | All   |
| `get_graph_node`       | Read one graph node with its properties and incoming relations.          | Any   | All   |
| `get_graph_root_nodes` | List the root nodes the graph expands from.                              | Any   | All   |

## Scope and Domain Policy

| Tool                      | What it does                                               | Roles                       | Plans |
| ------------------------- | ---------------------------------------------------------- | --------------------------- | ----- |
| `get_whitelist_domains`   | List allowlisted domains.                                  | Any                         | All   |
| `add_whitelist_domain`    | Allow one exact domain or subdomain for external scanning. | Admin, Operator, Trial user | All   |
| `remove_whitelist_domain` | Remove a domain allowance.                                 | Admin, Operator, Trial user | All   |
| `get_blacklist_domains`   | List excluded domains.                                     | Admin, Operator, Trial user | All   |
| `add_blacklist_domain`    | Exclude a domain from scanning.                            | Admin, Operator, Trial user | All   |
| `remove_blacklist_domain` | Remove an exclusion. This can widen scope.                 | Admin, Operator, Trial user | All   |
| `get_trajectory_rules`    | List host/path allow or deny rules for API testing.        | Admin, Operator, Trial user | All   |
| `add_trajectory_rule`     | Add a host and path-regex allow or deny rule.              | Admin, Operator, Trial user | All   |
| `remove_trajectory_rule`  | Remove a rule. Removing a deny rule widens scope.          | Admin, Operator, Trial user | All   |
| `test_trajectory_rule`    | Preview whether a host and path would be tested.           | Admin, Operator, Trial user | All   |

## Domain Verification

| Tool                          | What it does                                                    | Roles           | Plans |
| ----------------------------- | --------------------------------------------------------------- | --------------- | ----- |
| `get_domain_verifications`    | Read root-domain verification status and the DNS TXT challenge. | Admin, Operator | All   |
| `refresh_domain_verification` | Issue a new DNS challenge for an expired or replaced one.       | Admin, Operator | All   |
| `verify_domain_ownership`     | Check the published DNS TXT record. Does not change DNS.        | Admin, Operator | All   |

## Browser Sessions and Recording

| Tool                       | What it does                                                                                | Roles                       | Plans |
| -------------------------- | ------------------------------------------------------------------------------------------- | --------------------------- | ----- |
| `get_browser_sessions`     | List a Domain's browser sessions, or read one in detail with its validation history.        | Admin, Operator, Trial user | All   |
| `start_browser_recording`  | Start or re-record a login and return the recorder URL for a person to open.                | Admin, Operator, Trial user | All   |
| `get_browser_recording`    | Track a recording by ID, or find your active recording for a target.                        | Admin, Operator, Trial user | All   |
| `cancel_browser_recording` | End your own recording without saving it.                                                   | Admin, Operator, Trial user | All   |
| `import_browser_session`   | Import a session from Playwright `storage_state`, login actions, and verification criteria. | Admin, Operator, Trial user | All   |
| `update_browser_session`   | Update a session's state, metadata, starting URL, or verification criteria.                 | Admin, Operator, Trial user | All   |
| `delete_browser_session`   | Delete a session and what was recorded under it.                                            | Admin, Operator, Trial user | All   |
| `validate_browser_session` | Replay a session's login from the chosen egress to confirm it works. Sends traffic.         | Admin, Operator, Trial user | All   |

## Email Identities

| Tool                       | What it does                                                       | Roles                       | Plans |
| -------------------------- | ------------------------------------------------------------------ | --------------------------- | ----- |
| `list_email_identities`    | List inboxes for OTP and magic-link logins, with forwarding state. | Admin, Operator, Trial user | All   |
| `create_email_identity`    | Create a scoped test inbox.                                        | Admin, Operator, Trial user | All   |
| `update_email_identity`    | Update an inbox's label, notes, default, or forwarding.            | Admin, Operator, Trial user | All   |
| `archive_email_identity`   | Archive an inbox that is no longer used.                           | Admin, Operator, Trial user | All   |
| `confirm_email_forwarding` | Confirm forwarding with the token sent to the recipient.           | Admin, Operator, Trial user | All   |

## Egress and Rate Limits

| Tool                          | What it does                                                  | Roles                       | Plans |
| ----------------------------- | ------------------------------------------------------------- | --------------------------- | ----- |
| `get_egress_options`          | List scan egress locations and the sandbox IPs to allow-list. | Any                         | All   |
| `get_domain_rate_limit`       | Read a domain's calibrated request rate.                      | Admin, Operator, Trial user | All   |
| `calibrate_domain_rate_limit` | Measure a sustainable request rate. Sends controlled traffic. | Admin, Operator, Trial user | All   |

## Scan Configuration and Launch

| Tool                       | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                            | Roles                       | Plans                        |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------- |
| `validate_scan_config`     | Review a Web, Network, or Cloud configuration draft without saving or launching.                                                                                                                                                                                                                                                                                                                                                                        | Admin, Operator, Trial user | All                          |
| `save_scan_config`         | Save a run's settings and get the `scan_config_id` every launch needs.                                                                                                                                                                                                                                                                                                                                                                                  | Admin, Operator, Trial user | All                          |
| `get_scan_config`          | Read the last saved settings for a target and module.                                                                                                                                                                                                                                                                                                                                                                                                   | Admin, Operator, Trial user | All                          |
| `get_scan_estimate`        | Estimate runtime and credits for a launch. Launches nothing.                                                                                                                                                                                                                                                                                                                                                                                            | Admin, Operator, Trial user | All                          |
| `start_web_discovery`      | Start Web Discovery for one or more domains. With `config_mode` `"existing"` and one domain, reuse the scan configuration saved by its last scannable vetting run.                                                                                                                                                                                                                                                                                      | Admin, Operator, Trial user | All                          |
| `start_web_assessment`     | Start a Web Assessment for one or more domains. With `config_mode` `"existing"` and one domain, reuse the scan configuration saved by its last scannable vetting run.                                                                                                                                                                                                                                                                                   | Admin, Operator, Trial user | All                          |
| `start_web_vetting`        | AI configure: vet one domain (verified, where your deployment requires it), save its Discovery and Assessment scan configurations, and start the scan when the domain is scannable. Takes the same inputs as the wizard, including `accounts_text`, `what_changed`, and `allow_self_signup`. `intent` `"none"` vets without scanning. Follow the run with `get_submodule_status` or `get_job_status`, which include a `vetting` section. Sends traffic. | Admin, Operator             | When AI configure is enabled |
| `start_network_discovery`  | Start Network or Cloud discovery through a connected agent.                                                                                                                                                                                                                                                                                                                                                                                             | Admin, Operator             | Dedicated only               |
| `start_network_assessment` | Start a Network or Cloud assessment through a connected agent.                                                                                                                                                                                                                                                                                                                                                                                          | Admin, Operator             | Dedicated only               |

## Agents

| Tool                     | What it does                                                                | Roles           | Plans          |
| ------------------------ | --------------------------------------------------------------------------- | --------------- | -------------- |
| `list_agents`            | List registered agents and their connection state.                          | Admin, Operator | Dedicated only |
| `get_agent_details`      | Read an agent's host, OS, reported subnets, interfaces, and cloud metadata. | Admin, Operator | Dedicated only |
| `get_agent_installation` | Generate an expiring agent launcher for an authorized host.                 | Admin           | Dedicated only |

## Code Assessment

| Tool                         | What it does                                                                                | Roles                       | Plans                                     |
| ---------------------------- | ------------------------------------------------------------------------------------------- | --------------------------- | ----------------------------------------- |
| `get_github_connection`      | Read the GitHub App connection state.                                                       | Admin, Operator, Trial user | Dedicated; shared-trial with subscription |
| `begin_github_connection`    | Create a GitHub App consent URL and a short-lived setup token.                              | Admin, Operator, Trial user | Dedicated; shared-trial with subscription |
| `complete_github_connection` | Finish the GitHub connection with the returned installation ID and state.                   | Admin, Operator, Trial user | Dedicated; shared-trial with subscription |
| `list_github_repositories`   | List repositories the GitHub installation can access.                                       | Admin, Operator, Trial user | Dedicated; shared-trial with subscription |
| `list_repository_refs`       | List branches, open pull requests, and recent commits.                                      | Admin, Operator, Trial user | Dedicated; shared-trial with subscription |
| `connect_code_repository`    | Add an authorized repository as a scan target.                                              | Admin, Operator, Trial user | Dedicated; shared-trial with subscription |
| `set_repository_domain`      | Link a connected repository to a web target.                                                | Admin, Operator, Trial user | Dedicated; shared-trial with subscription |
| `get_code_scan_settings`     | Read a repository's capabilities, automation, PR-check, and autofix settings.               | Admin, Operator, Trial user | Dedicated; shared-trial with subscription |
| `update_code_scan_settings`  | Change a repository's scan settings. Future PR/push scans and autofix need explicit opt-in. | Admin, Operator, Trial user | Dedicated; shared-trial with subscription |
| `start_code_assessment`      | Start a code assessment for a branch, commit, or pull request.                              | Admin, Operator, Trial user | Dedicated; shared-trial with subscription |

## Run Control and Monitoring

| Tool                | What it does                                       | Roles                       | Plans |
| ------------------- | -------------------------------------------------- | --------------------------- | ----- |
| `get_module_stats`  | Per-run status counts, timing, and inputs.         | Any                         | All   |
| `get_jobs`          | List job records with their execution state.       | Any                         | All   |
| `get_attack_logs`   | Read paginated attack logs.                        | Any                         | All   |
| `pause_assessment`  | Pause one run.                                     | Admin, Operator, Trial user | All   |
| `resume_assessment` | Resume a paused run.                               | Admin, Operator, Trial user | All   |
| `cancel_assessment` | Cancel one run. Completed work is not rolled back. | Admin, Operator, Trial user | All   |
| `cancel_submodule`  | Cancel one in-flight step of a run.                | Admin, Operator, Trial user | All   |
| `rerun_submodule`   | Re-run one previously executed step.               | Admin, Operator, Trial user | All   |

## Schedules

| Tool                   | What it does                                          | Roles           | Plans          |
| ---------------------- | ----------------------------------------------------- | --------------- | -------------- |
| `list_scan_schedules`  | List one-time and recurring scheduled scans.          | Admin, Operator | Dedicated only |
| `create_scan_schedule` | Schedule a scan from saved scan configurations.       | Admin           | Dedicated only |
| `update_scan_schedule` | Change a schedule's timing; scope is kept.            | Admin           | Dedicated only |
| `delete_scan_schedule` | Stop future launches. Does not cancel a running scan. | Admin           | Dedicated only |

## Reports

| Tool              | What it does                                                  | Roles                       | Plans |
| ----------------- | ------------------------------------------------------------- | --------------------------- | ----- |
| `generate_report` | Generate a general or executive PDF report for a root target. | Admin, Operator, Trial user | All   |
| `list_reports`    | List generated reports, newest first.                         | Any                         | All   |

## Agentic Testing

| Tool                     | What it does                                                           | Roles                       | Plans |
| ------------------------ | ---------------------------------------------------------------------- | --------------------------- | ----- |
| `list_trajectories`      | List captured user journeys under a root.                              | Admin, Operator, Trial user | All   |
| `get_trajectory`         | Read one journey's browser and API actions, with `api_id` values.      | Admin, Operator, Trial user | All   |
| `create_trajectory`      | Register a focused flow your agent found, so it can be tested.         | Admin, Trial user           | All   |
| `get_test_case_schema`   | Read the exact `TestCaseData` schema `run_test` accepts.               | Admin, Trial user           | All   |
| `run_test`               | Prove a finding through the platform tester and write it to the graph. | Admin, Trial user           | All   |
| `get_submodule_status`   | Poll a test run's status, jobs, and findings.                          | Admin, Operator, Trial user | All   |
| `get_job_status`         | Diagnose one job: indicator results and the exact request sent.        | Admin, Operator, Trial user | All   |
| `create_oob_url`         | Create an out-of-band callback URL for blind testing.                  | Admin, Trial user           | All   |
| `get_oob_hits`           | Read callbacks recorded for an out-of-band URL.                        | Admin, Trial user           | All   |
| `path_to_root`           | Walk from an entity up to its root.                                    | Admin, Trial user           | All   |
| `list_nodes_by_property` | Find entities of one type by property values.                          | Admin, Trial user           | All   |

## Organization Settings

| Tool              | What it does                       | Roles | Plans          |
| ----------------- | ---------------------------------- | ----- | -------------- |
| `get_settings`    | Read organization-wide settings.   | Admin | Dedicated only |
| `update_settings` | Change organization-wide defaults. | Admin | Dedicated only |

## Related

* [Configure a Tenant with MCP](https://copilot-docs.bugbase.ai/enterprise/settings/api-keys-and-mcp-server/configure-tenant-with-mcp.md)
* [Agentic Testing with MCP](https://copilot-docs.bugbase.ai/enterprise/settings/api-keys-and-mcp-server/agentic-testing-with-mcp.md)
