API Keys & MCP Server

Pentest Copilot API keys let external tools call the REST API and the platform MCP server

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 Desktop, Cursor, 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.

API keys are scoped to your workspace or organization. A key inherits the permissions of the user that created it, so MCP tools and REST endpoints enforce the same access controls as the web app.

REST API Usage

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

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 Usage

Use the MCP endpoint for external MCP clients:

https://<your-pentest-copilot-host>/mcp

Most MCP clients should send the key as a bearer token:

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

The MCP server also accepts X-API-Key: <your-api-key>, but the bearer-token form is the recommended MCP client configuration.

Available MCP Workflows

The exact tools shown to a client depend on the API key's permissions and enabled product features. Common MCP workflows include:

• Asset management: list_assets, get_asset, create_root_target, delete_root_target

• Graph exploration: search_graph, get_graph_node, get_graph_root_nodes

• Scan orchestration: start_external_discovery, start_external_assessment, start_internal_discovery, start_internal_assessment

• Scan job control: get_jobs, cancel_submodule, rerun_submodule

• Settings and reporting: get_settings, update_settings, generate_report, list_reports

• Logs and stats: get_attack_logs, get_module_stats

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.

• External scans require the requested domain to be in the workspace or organization scope.

• Internal scans require the internal assessment feature and a connected agent.

• The requested target must belong to the API key's workspace or organization.

If any of these checks fail, the MCP tool returns an error instead of starting the scan.

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

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

403 role or feature errors : The key's permissions or plan do not allow the requested tool.

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

Agent availability errors : Internal scans require a connected agent. External scans may be temporarily unavailable if required scanning capacity is unavailable.

Security Best Practices

• Use one API key per MCP client or integration.

• Store keys in a secrets manager or the MCP client's secure configuration.

• Do not commit keys to source control, tickets, chat, or documentation.

• 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, modify targets, cancel submodules, generate reports, and read attack data.