MCP Server

Connect an MCP client to BotScope so agents can authenticate, generate API keys, start scans, wait for completion, and retrieve results.

Docs

Authentication

MCP clients can use BotScope browser connect. The user signs in through BotScope, approves the connection, and receives an MCP-scoped mcp_... token. Existing dxk_... API keys can also authenticate directly as Bearer tokens.

Hosted endpoint: /mcp.

List tools
curl -sS -X POST "$API_ORIGIN/mcp" \
  -H "Authorization: Bearer dxk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Tools

create_api_keyCreate a standard dxk_ API key when an agent needs HTTP API access.
create_scanStart a full scan for a monitored URL or enroll a new Growth URL slot.
get_scan_statusRead scan status, failure reason, and path-run progress.
wait_for_scan_resultsPoll server-side until completion, failure, or timeout.
get_scan_findingsReturn scan findings.
get_scan_reportReturn the assembled public scan report.
list_monitoring_subscriptionsList monitored URLs for the workspace.

Agent workflow

  1. Connect BotScope MCP from the customer's agent client.
  2. Use browser sign-in to issue an MCP-scoped token.
  3. Call create_api_key only if standard HTTP API access is needed.
  4. Call create_scan.
  5. Call wait_for_scan_results.
  6. Call get_scan_findings or get_scan_report.
Create scan tool call
{
  "tool": "create_scan",
  "arguments": {
    "target_url": "https://example.com",
    "enroll_monitoring": true
  }
}
Wait for results tool call
{
  "tool": "wait_for_scan_results",
  "arguments": {
    "scan_job_id": "scan_job_id_from_create_scan",
    "timeout_seconds": 120,
    "poll_interval_seconds": 2
  }
}

Growth URL rules

Growth agents can scan URLs already covered by active monitoring. To add a new monitored URL, call create_scan with enroll_monitoring: true while the workspace has an open slot. Enterprise agents can scan and monitor without URL caps.

Starter, cancelled, and past-due workspaces are rejected for agent scan and monitoring operations.

API key generation

The create_api_key tool returns a standard dxk_... secret once. Use it for HTTP API calls, CI systems, or internal tools that do not speak MCP.