> 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.md).

# API Keys & MCP Server

Create a Pentest Copilot API key and connect an AI agent or MCP client to the platform MCP server to set up and run assessments.

Pentest Copilot exposes the platform through two interfaces that use the same API keys:

* the **REST API**, for scripts and CI pipelines;
* the **platform MCP server**, for AI agents and MCP clients such as Claude Code, Cursor, VS Code, or your own agent.

Through MCP, an agent can do what you do in the web app: add targets, verify domains, record or import browser sessions, configure and launch Web, Network, Cloud, and Code assessments, monitor runs, read findings, and generate reports. It is held to the same permissions, plan limits, scope controls, and launch checks as the web app.

This page covers keys and connecting a client. The child pages cover the rest:

* [Configure a Tenant with MCP](https://copilot-docs.bugbase.ai/enterprise/settings/api-keys-and-mcp-server/configure-tenant-with-mcp.md): step-by-step assessment setup through an agent.
* [Agentic Testing with MCP](https://copilot-docs.bugbase.ai/enterprise/settings/api-keys-and-mcp-server/agentic-testing-with-mcp.md): let your own agent explore an application and prove findings through the platform.
* [MCP Tool Reference](https://copilot-docs.bugbase.ai/enterprise/settings/api-keys-and-mcp-server/mcp-tool-reference.md): every tool, with the roles and plans that can use it.

## Create an API Key

You need permission to manage API keys in your workspace or organization.

1. Open **Settings -> API Keys + MCP** in Pentest Copilot.
2. Select **Create API key**.
3. Enter a name that identifies the integration, such as `Claude Code - laptop` or `CI pipeline`.
4. Copy the raw key when it is shown.

The raw key is only shown once, when you create or rotate it. If the key is lost or exposed, rotate it from the same page.

A key has the **role of the user who created it**, and it is limited to that user's workspace or organization. MCP tools and REST endpoints enforce the same access controls as the web app. To give an agent less access, have a user with a narrower role create its key:

| Creator's role                           | What an agent using the key can do                                                                                                                                                                                |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Viewer**                               | Read only: assets, graph, jobs, logs, statistics, reports, the domain allowlist, scan egress options, and the setup manual. It cannot change anything or start scans.                                             |
| **Operator**                             | Everything a Viewer can, plus manage targets, scope rules, domain verification, browser sessions, scan configurations, and agents, and start, pause, or cancel scans.                                             |
| **Admin**                                | Everything an Operator can, plus agentic testing, organization settings, agent installers, and scan schedules.                                                                                                    |
| **Trial user** (shared-trial workspaces) | Web targets, scope rules, browser sessions, scan configurations, Web scans, and agentic testing within the trial workspace. Code assessment needs an active subscription. Verify domain ownership in the web app. |

See [MCP Tool Reference](https://copilot-docs.bugbase.ai/enterprise/settings/api-keys-and-mcp-server/mcp-tool-reference.md) for the exact tool list per role and plan.

## REST API Usage

Send API keys to REST endpoints with the `X-API-Key` header.

```bash
curl \
  -H "X-API-Key: <your-api-key>" \
  https://<your-pentest-copilot-host>/api/auth/me
```

The OpenAPI schema is available at:

```
https://<your-pentest-copilot-host>/api/docs
```

## MCP Server Endpoint

|                |                                                                                     |
| -------------- | ----------------------------------------------------------------------------------- |
| Endpoint       | `https://<your-pentest-copilot-host>/mcp/`                                          |
| Transport      | Streamable HTTP                                                                     |
| Authentication | `Authorization: Bearer <your-api-key>` (recommended) or `X-API-Key: <your-api-key>` |

{% hint style="warning" %}
Keep the trailing slash. `https://<your-pentest-copilot-host>/mcp` (no slash) answers with a redirect, and many MCP clients fail to connect instead of following it.
{% endhint %}

The server authenticates with your API key in a request header. It does not offer an OAuth sign-in flow, so use a client that lets you set custom headers.

## Connect an MCP Client

Replace `<your-pentest-copilot-host>` with your tenant's host name and `<your-api-key>` with the key you created. Prefer your client's secret storage or an environment variable over pasting the key into shared files.

### Claude Code

```bash
claude mcp add --transport http pentest-copilot \
  https://<your-pentest-copilot-host>/mcp/ \
  --header "Authorization: Bearer <your-api-key>"
```

Add `--scope user` to make the server available in every project. Run `/mcp` inside Claude Code to confirm it shows as connected.

### Cursor

Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "pentest-copilot": {
      "url": "https://<your-pentest-copilot-host>/mcp/",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}
```

### VS Code (agent mode)

Add `.vscode/mcp.json`. The `inputs` block makes VS Code prompt for the key and store it securely instead of saving it in the file:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "pentest-copilot-key",
      "description": "Pentest Copilot API key",
      "password": true
    }
  ],
  "servers": {
    "pentest-copilot": {
      "type": "http",
      "url": "https://<your-pentest-copilot-host>/mcp/",
      "headers": {
        "Authorization": "Bearer ${input:pentest-copilot-key}"
      }
    }
  }
}
```

### Claude Desktop and Other stdio-Only Clients

Clients that only launch local (stdio) servers can reach the platform through the `mcp-remote` bridge. Node.js must be installed:

```json
{
  "mcpServers": {
    "pentest-copilot": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<your-pentest-copilot-host>/mcp/",
        "--header",
        "Authorization:${PENTEST_COPILOT_AUTH}"
      ],
      "env": {
        "PENTEST_COPILOT_AUTH": "Bearer <your-api-key>"
      }
    }
  }
}
```

Connectors that require OAuth, such as custom connectors added in a browser-based chat app, cannot use this server because it authenticates with an API-key header.

### Your Own Agent

Any MCP client library that supports Streamable HTTP and custom headers works. For example, with the Python `fastmcp` client:

```python
import asyncio
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

transport = StreamableHttpTransport(
    "https://<your-pentest-copilot-host>/mcp/",
    headers={"Authorization": "Bearer <your-api-key>"},
)

async def main():
    async with Client(transport) as client:
        tools = await client.list_tools()
        print(sorted(tool.name for tool in tools))
        manual = await client.call_tool("get_setup_information", {})
        print(manual.content[0].text[:500])

asyncio.run(main())
```

## Verify the Connection

1. List the server's tools in your client. The list depends on the key's role and plan, so a Viewer key shows far fewer tools than an Admin key.
2. Ask the agent to call `get_setup_information`. It takes no arguments and only reads; nothing is created or scanned.

If both work, the client is connected and authorized.

## Start Here: `get_setup_information`

`get_setup_information` returns the platform's built-in setup manual. It covers prerequisites, the questions to settle before configuring anything, the ordered tool sequence for Web, Network, Cloud, and Code assessments, every configuration field, examples, and the steps a person must do outside the agent.

It also returns a `configuration_reference` generated from the running server: accepted values, defaults, and limits for scan settings, attack vectors, network exploit categories, cloud providers, and code-scan options. These always match your tenant's version, so prefer them over copied lists.

A typical first prompt to your agent:

> Connect to Pentest Copilot, read `get_setup_information`, list my existing targets, and tell me what is needed to run an authenticated web assessment on `app.example.com`.

The full walkthrough is in [Configure a Tenant with MCP](https://copilot-docs.bugbase.ai/enterprise/settings/api-keys-and-mcp-server/configure-tenant-with-mcp.md).

## What You Can Do Through MCP

| Area                 | Examples                                                                                                                                                                                                             |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Targets and scope    | `list_assets`, `create_root_target`, `add_whitelist_domain`, `add_blacklist_domain`, `add_trajectory_rule`, `get_domain_verifications`, `verify_domain_ownership`                                                    |
| Login and sessions   | `list_email_identities`, `start_browser_recording`, `get_browser_recording`, `import_browser_session`, `validate_browser_session`, `get_browser_sessions`                                                            |
| Configure and launch | `get_egress_options`, `validate_scan_config`, `save_scan_config`, `get_scan_estimate`, `start_web_discovery`, `start_web_assessment`, `start_network_discovery`, `start_network_assessment`, `start_code_assessment` |
| Agents and cloud     | `list_agents`, `get_agent_details`, `get_agent_installation`                                                                                                                                                         |
| Code                 | `begin_github_connection`, `complete_github_connection`, `list_github_repositories`, `connect_code_repository`, `update_code_scan_settings`                                                                          |
| Run control          | `get_module_stats`, `get_jobs`, `pause_assessment`, `resume_assessment`, `cancel_assessment`, `cancel_submodule`, `rerun_submodule`                                                                                  |
| Schedules            | `list_scan_schedules`, `create_scan_schedule`, `update_scan_schedule`, `delete_scan_schedule`                                                                                                                        |
| Results              | `search_graph`, `get_graph_node`, `get_asset`, `get_attack_logs`, `generate_report`, `list_reports`                                                                                                                  |
| Agentic testing      | `list_trajectories`, `create_trajectory`, `run_test`, `get_submodule_status`, `create_oob_url`                                                                                                                       |

Your client only shows the tools the key may call. A tool missing from the list is not available to that key's role or plan. See [MCP Tool Reference](https://copilot-docs.bugbase.ai/enterprise/settings/api-keys-and-mcp-server/mcp-tool-reference.md).

## Scan Launch Requirements

API keys and MCP clients cannot bypass scan launch policy. Starting discovery or assessment through MCP is subject to the same checks as starting a scan in the web app:

* The workspace or organization must have scan usage available.
* Plan, payment, and credit restrictions still apply.
* The API key must be scoped to an active workspace or organization.
* The target must belong to the API key's workspace or organization.
* Web assessments require the domain to be in scope and, where enforced, ownership-verified. See [Domain Verification](https://copilot-docs.bugbase.ai/enterprise/settings/domain-verification.md).
* Authenticated runs require validated browser sessions owned by the same workspace.
* Network and Cloud assessments require the network assessment feature and a connected customer agent.

If any of these checks fail, the tool returns an error instead of starting the scan. A saved scan configuration is not a run, and an accepted launch does not guarantee full coverage. Check run status and results afterwards.

## Limits

* One request can carry up to 2 MiB. One response can return up to 8 MiB. Narrow filters or paginate when you hit the response limit.
* Some setup calls time out after 120 seconds. After a timeout the outcome is unknown, so read the current state before retrying anything that creates or changes data.
* Requests are rate limited per client. Pause and retry if requests are rejected for rate.

## Rotate or Revoke Keys

Rotate a key when it is exposed, when a user leaves, or when an integration owner changes.

Revoke keys that are no longer used. Revocation takes effect immediately for both REST API calls and MCP calls.

## Troubleshooting

`301` redirect or the client cannot connect : Use the endpoint with the trailing slash, `https://<your-pentest-copilot-host>/mcp/`.

`401 Missing API key` : The MCP or REST request did not include an API key.

`401 Invalid API key` : The key is incorrect, revoked, or belongs to a workspace that no longer matches the request.

`403 User is disabled` : The user who created the key has been disabled. Create a key from an active user.

`403 API key is not bound to a workspace; please re-create it.` : The key is missing workspace scope. Create a new key from **Settings -> API Keys + MCP**.

A tool is missing from the client, or `Insufficient role` : The key's role does not allow the tool. Use a key created by a user with the needed role.

`... is only available in the enterprise deployment` : The feature is not included in this plan. See [MCP Tool Reference](https://copilot-docs.bugbase.ai/enterprise/settings/api-keys-and-mcp-server/mcp-tool-reference.md#plan-availability).

`Not found` for a target you can see in another workspace : Each workspace only sees its own targets, sessions, runs, and results. Use a key from the workspace that owns the target.

Payment, credit, usage, verification, or scope errors : The scan was blocked by the same launch requirements enforced in the web app. Confirm the domain is in scope and verified, and that the workspace has scan usage available.

Agent availability errors : Network and Cloud assessments require a connected customer agent. Web assessments may be temporarily unavailable when scanning capacity is unavailable.

## Security Best Practices

* Use one API key per MCP client or integration, and name it after that client.
* Give each agent the narrowest role that fits its job. A reporting agent only needs a Viewer key.
* Store keys in a secrets manager, an environment variable, or the MCP client's secure configuration.
* Do not commit keys to source control, tickets, chat, or documentation, and do not paste them into an agent's conversation.
* Rotate keys regularly and immediately after exposure. Revoke old keys instead of reusing them across tools.
* Treat MCP clients as privileged automation. Depending on the key's role, a client can start scans that send traffic to your targets, change scope, cancel runs, and read attack data, including findings and stored session details.
* Review what an agent proposes before it launches a scan, enables active or destructive test categories, or turns on recurring or automated runs.
