> 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/configure-tenant-with-mcp.md).

# Configure a Tenant with MCP

Set up and run Web, Network, Cloud, and Code assessments by asking an AI agent connected to the Pentest Copilot MCP server.

Once an agent is connected to the platform MCP server (see [API Keys & MCP Server](https://copilot-docs.bugbase.ai/enterprise/settings/api-keys-and-mcp-server.md)), you can set up and run assessments by describing what you want. The agent calls the same named tools the web app uses, and every scope, permission, verification, and launch check still applies.

This page explains what the agent does at each step, what it needs to ask you, and which steps only a person can complete. The agent reads the authoritative procedure from the server itself, so this page and the built-in manual agree.

## How a Setup Conversation Works

{% stepper %}
{% step %}

### The agent reads the manual

The agent calls `get_setup_information` first. It returns the full setup manual and a `configuration_reference` with the values your tenant accepts: attack vectors, network exploit categories, cloud providers, code-scan options, and scan-setting limits. Reading it performs no setup and sends no traffic.
{% endstep %}

{% step %}

### The agent inspects what already exists

Before creating anything it checks existing targets, allowlist and exclusions, browser sessions, saved scan configurations, connected agents, GitHub connection, and schedules. For a returning customer it reuses what is already set up instead of recreating it.
{% endstep %}

{% step %}

### The agent asks only for missing decisions

Expect questions about:

* the approved target and any exclusions;
* **Discovery**, **Assessment**, or both;
* public coverage, authenticated coverage, or both, and which account roles to test;
* request rate and runtime limits;
* for Network and Cloud: network-only, cloud-only, or hybrid, and **which connected agent** to use;
* which attack vectors or exploit categories are approved;
* whether the run is one-off or recurring.

The agent should not choose a connected agent, enable destructive or state-changing tests, enable Intercept, or turn on future automated scans or autofix unless you explicitly approve it.
{% endstep %}

{% step %}

### The agent validates, shows the effective configuration, then launches

`validate_scan_config` reviews a draft without saving or launching and reports blocking errors, warnings, and checks it could not perform. The agent saves the configuration with `save_scan_config`, can estimate runtime and credits with `get_scan_estimate`, shows you the effective settings, and launches within what you approved. Saving a configuration does not start a run.
{% endstep %}
{% endstepper %}

## Web Assessment

Example prompt:

> Set up an authenticated web assessment of `app.example.com` with a read-only customer account. Run Discovery first, then let me review before the attack phase. Keep the rate at 30 requests per minute.

### 1. Target and Scope

The agent lists existing `Domain` targets and the allowlist, then creates the target with `create_root_target` if needed and keeps the returned entity ID. Creating a target and allowing it are separate: `add_whitelist_domain` allows a domain, and `add_blacklist_domain` excludes one.

For API-level control, `add_trajectory_rule` adds host and path-regex allow or deny rules. `test_trajectory_rule` previews whether a given host and path will be tested. See [Trajectories](https://copilot-docs.bugbase.ai/enterprise/settings/trajectories.md) and [Domains](https://copilot-docs.bugbase.ai/enterprise/settings/domains.md).

Allowlisting a domain in Pentest Copilot does not change your WAF or firewall.

### 2. Domain Ownership

Where ownership verification is enforced, the agent reads `get_domain_verifications` and gives you the exact DNS TXT record. You publish it with your DNS provider, and the agent then calls `verify_domain_ownership`. If the challenge has expired, `refresh_domain_verification` issues a new one. Scans do not run until verification passes. See [Domain Verification](https://copilot-docs.bugbase.ai/enterprise/settings/domain-verification.md).

On shared-trial workspaces, verify ownership in the web app.

### 3. Egress

`get_egress_options` lists the locations scan traffic can leave from and the sandbox IPs to allow-list if your target sits behind an IP allow-list, firewall, or WAF. Recording, validation, and scanning should use compatible egress. See [Scan Noise and Safety](https://copilot-docs.bugbase.ai/enterprise/scan-noise-and-safety.md).

### 4. Login Sessions (Authenticated Coverage)

The agent first checks `get_browser_sessions` for a ready session it can reuse. Otherwise there are two ways to provide one:

**Record a login.** `start_browser_recording` returns a recorder URL that you open yourself:

1. Sign in to Pentest Copilot as the API key's owner if prompted.
2. Select **Start Auth** just before logging in, and complete every login step.
3. Set the **Verify URL** on a page only a logged-in user can see.
4. Select **Stop Auth**, optionally set the **Starting URL**, then **Done**.

Use **Auth Actions** for TOTP, email or SMS one-time codes, magic links, and supported captcha helpers instead of hard-coding expiring values. For OTP or magic-link logins, the agent picks an inbox with `list_email_identities` (or `create_email_identity`). The agent tracks the recording with `get_browser_recording`. Opening the URL is not completion, and `cancel_browser_recording` closes an abandoned recorder. See [Recording Browser Session](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-web-assessment/recording-browser-session.md), [Handling Captcha/Email/Mobile OTPs](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-web-assessment/handling-captcha-email-mobile-otps.md), and [Email Identities](https://copilot-docs.bugbase.ai/enterprise/settings/email-identities.md).

**Import a session.** `import_browser_session` accepts real Playwright `storage_state`, `session_storage`, login actions, and verification criteria. See [Importing Browser Session](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-web-assessment/importing-browser-session.md).

Every session must then pass `validate_browser_session`, which replays the login from the chosen egress and sends traffic to the target. The agent polls `get_browser_sessions` for the result. Failed, expired, or changed sessions are repaired and validated again, not skipped. Use one session per account role. See [Validating Browser Sessions](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-web-assessment/validating-browser-sessions.md).

### 5. Rate and Configuration

`calibrate_domain_rate_limit` optionally measures a sustainable request rate by sending controlled traffic, and `get_domain_rate_limit` reads the result. An estimate is not a calibration.

The agent then builds the scan configuration. The main choices are:

| Setting                                              | What to decide                                                         |
| ---------------------------------------------------- | ---------------------------------------------------------------------- |
| `authentication_types`                               | Public, authenticated, or both. Choose explicitly.                     |
| `browser_session_ids`                                | Validated sessions for authenticated coverage, one per role.           |
| `rate_limit_per_minute`                              | An agreed request rate.                                                |
| `attack_vectors`                                     | Approved categories, from `configuration_reference`.                   |
| `sandbox_egress_location`, residential proxy options | Locations from `get_egress_options`.                                   |
| `custom_headers`                                     | Only routing or test headers your target requires.                     |
| `selected_trajectory_ids`                            | Optional: limit the attack to specific discovered flows.               |
| `max_module_runtime`, concurrency caps               | Optional runtime and parallelism limits.                               |
| `scan_type`, `auto_run_web` (Discovery only)         | Discovery coverage, and whether the attack phase starts automatically. |

The full field list is in the manual and in [Configure Scan Settings for Web Assessment](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-web-assessment/configure-scan-settings-for-web-assessment.md).

### 6. Launch

* **Assessment only:** `start_web_assessment` with the target and saved `scan_config_id`.
* **Discovery, or Discovery then Assessment:** save a `WEB_DISCOVERY` configuration and call `start_web_discovery`. Set `auto_run_web: true` in the saved configuration only if the attack phase should start automatically. The `domains-only` scan type never starts the attack phase.

The agent returns the run IDs and monitors them (see [Monitor Runs and Read Results](#monitor-runs-and-read-results)).

## Network Assessment

Network assessments run through a **customer agent** installed on a host inside your network. See [How to Trigger a Network Assessment](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-network-assessment.md). Network and Cloud assessments, agents, and schedules are not available in shared-trial workspaces.

Example prompt:

> List my connected agents. Using the one on the build server, run discovery on 10.10.10.0/24 only. Don't start any attack yet.

1. **Choose the agent.** The agent calls `list_agents` and `get_agent_details`, shows you the connected agents with their hosts and reported subnets, and asks which to use. Platform SANDBOX and CLOUD workers are not customer agents.
2. **Install an agent if none is connected.** `get_agent_installation` (Admin) returns an expiring launcher. You run it on an authorized host that can reach the targets and your tenant, then the agent checks again until it connects. Treat the launcher as a secret. See [Download Agent](https://copilot-docs.bugbase.ai/enterprise/download-agent.md).
3. **Agree scope.** Which reported CIDRs, contained partial targets, exclusions, exploit categories, and limits. Discovery targets CIDR strings. Assessment targets the `Subnet` entities that discovery creates.
4. **Discover.** The agent validates and saves a `NETWORK_DISCOVERY` configuration, then calls `start_network_discovery` with the chosen agent.
5. **Review, then assess.** After you review the discovered hosts and failed jobs, the agent saves a `NETWORK_ASSESSMENT` configuration with explicit `allowed_exploits` and calls `start_network_assessment`. For Discovery then Assessment in one run, `auto_run_network: true` must be saved deliberately.

Start narrow. Intercept (responder) stays off unless approved, and needs the chosen agent's interfaces. Discuss Active Directory and certificate-service writes, credential access, relay, remote code execution, data copying, and cleanup separately. See [Network Assessment Destructive Actions](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-network-assessment/network-assessment-destructive-actions.md).

## Cloud Assessment

Cloud assessments use a customer agent running on a VM inside your cloud account, with a native cloud identity. Static cloud keys are not supported. See [Run a Cloud Assessment](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-cloud-assessment.md).

1. **Prepare the VM and identity outside Pentest Copilot.** Use a dedicated VM: EC2 in AWS, an Azure VM, or Compute Engine in GCP. Attach an instance role, managed identity, or service account with scoped read permissions, and enable the needed provider APIs. See [Cloud Assessment Prerequisites](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-cloud-assessment/configure-a-cloud-agent.md), [Set Up the Cloud Agent](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-cloud-assessment/provider-runbooks.md), and [Cloud Permissions](https://copilot-docs.bugbase.ai/enterprise/cloud-assessment-reference/cloud-permissions-reference.md).
2. **Confirm the agent and identity.** The agent uses `list_agents` and `get_agent_details`, which show the provider metadata the VM reports. Anything not reported is unverified, not passed.
3. **Discover.** Cloud uses `NETWORK_DISCOVERY` with `environment_mode: "cloud"`, the provider, and the account, subscription, or project. AWS also needs literal `resource_name_prefixes`. The discovered `CloudScope` is the target for the attack phase.
4. **Review coverage.** Discovery failures usually mean missing permissions or disabled APIs. Fix them in your cloud account and re-run discovery narrowly. Do not treat partial collection as full coverage.
5. **Assess.** The agent saves a `NETWORK_ASSESSMENT` configuration for the `CloudScope` with approved categories and calls `start_network_assessment`. Leave destructive impact, persistence, defense evasion, and workload execution off unless specifically approved. Grant only temporary active-test permissions, and agree stop conditions and a cleanup owner. See [Safety and Cleanup](https://copilot-docs.bugbase.ai/enterprise/cloud-assessment-reference/cloud-assessment-safety-and-cleanup.md).

For hybrid environments, review and launch each discovered `Subnet` and `CloudScope` separately.

## Code Assessment

Example prompt:

> Connect our GitHub org, then run a code assessment on the `main` branch of `acme/payments-api` with SBOM. Don't turn on PR or push scans.

1. **Connect GitHub.** `get_github_connection` shows the current state. If disconnected, `begin_github_connection` returns a GitHub App consent URL and a short-lived setup token. You approve the app for the repositories you authorize, then give the returned `installation_id` and `state` back to the agent, which calls `complete_github_connection` with the same API key within 15 minutes. See [Configure GitHub for Code Assessment](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-code-assessment/configure-github-for-code-assessment.md).
2. **Pick the repository.** `list_github_repositories` and `connect_code_repository` add the repository as a target. `set_repository_domain` can link it to a web target.
3. **Pick the code to scan.** `list_repository_refs` suggests branches, open pull requests, and recent commits. Confirm the exact branch, commit, or PR.
4. **Configure.** `get_code_scan_settings` and `update_code_scan_settings` set capabilities, SBOM, PR checks, and automation. Leave branch, PR, push, and autofix automation off unless you want future runs.
5. **Launch.** `start_code_assessment` with the scope and ref.

Findings appear as `Vulnerability` assets under the repository's `CodeSnapshot`. Dependency and AI inventories are read page by page with `get_asset` and `code_inventory: "sbom"` or `"ai_bom"`. See [Configure Scan Settings for Code Assessment](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-code-assessment/configure-scan-settings-for-code-assessment.md).

On shared-trial workspaces, Code assessment requires an active subscription.

## Schedules and Repeat Runs

* `list_scan_schedules` shows existing one-time and recurring runs. Check it before creating another.
* `create_scan_schedule` schedules a run from saved `scan_config_id` values. Confirm your timezone when the agent converts the time.
* `update_scan_schedule` changes timing only. Recreate a schedule to change scope.
* `delete_scan_schedule` stops future launches. It does not cancel a run already in progress.

Creating, updating, and deleting schedules requires an Admin key. Code PR and push automation lives in the repository's code-scan settings, not in schedules. See [Scheduling](https://copilot-docs.bugbase.ai/enterprise/activity/scheduling.md).

For a repeat run, the agent reads the saved configuration (`get_scan_config` or `get_code_scan_settings`) and the current session and agent state. It shows you what would change, revalidates changed credentials or scope, saves, and launches.

## Monitor Runs and Read Results

| Goal                        | Tools                                                                                               |
| --------------------------- | --------------------------------------------------------------------------------------------------- |
| Run status                  | `get_module_stats`, `get_jobs`, `get_submodule_status`, `get_job_status`                            |
| Pause, resume, cancel a run | `pause_assessment`, `resume_assessment`, `cancel_assessment` (one run at a time, by `module_refid`) |
| Stop or retry one step      | `cancel_submodule`, `rerun_submodule`                                                               |
| Findings and assets         | `list_assets`, `get_asset`, `search_graph`, `get_graph_node`, `get_graph_root_nodes`                |
| Activity                    | `get_attack_logs`                                                                                   |
| Reports                     | `generate_report`, `list_reports`                                                                   |

Cancellation stops remaining work. It does not undo changes a test already made. See [Analysing Scan Results](https://copilot-docs.bugbase.ai/enterprise/analysing-scan-results.md) and [Reports](https://copilot-docs.bugbase.ai/enterprise/reports.md).

## Steps Only a Person Can Do

The agent pauses and hands these to you, using the URLs and values the server returns:

* publish DNS TXT records for domain verification;
* add scanner egress IPs to a WAF or firewall allow-list;
* open the browser recorder and complete the login recording;
* run the agent launcher on an approved host;
* attach cloud identities and grant cloud permissions;
* approve the GitHub App installation.

The agent should never invent console links or embed API keys in URLs.

## Good Practice

* Read existing state before changing it, and reuse targets, sessions, and configurations.
* After a timeout, check whether the target, recording, configuration, schedule, or run was created before retrying.
* Treat validation as a snapshot. The launch re-checks live policy, and an accepted scan does not prove complete coverage.
* Keep secrets in session and configuration inputs, never in explanations, logs, or report text.
* When a plan, role, credit, or feature restriction blocks a step, report the blocker. Do not try to work around it.
