MCP Server Documentation

The @apviso/mcp package connects your AI assistant to the APVISO penetration testing platform via the Model Context Protocol. Manage targets, run scans, review findings, and download reports without leaving your editor.

18 tools across 6 categories — quota, targets, scans, findings, reports, and schedules.

Installation

No installation needed — the package runs via npx. Just configure your AI tool with the correct settings below.

Configuration

Choose your AI tool and add the configuration below. You'll need an APVISO API key — generate one in Settings → API Keys.

Claude Code

Add the MCP server to Claude Code via the CLI. The server runs as a stdio transport.

bash
claude mcp add --transport stdio apviso \
  --env APVISO_API_KEY=apvk_your_key_here \
  -- npx -y @apviso/mcp

Claude Desktop

Add the following to your Claude Desktop configuration file (claude_desktop_config.json).

json
{
  "mcpServers": {
    "apviso": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@apviso/mcp"
      ],
      "env": {
        "APVISO_API_KEY": "apvk_your_key_here"
      }
    }
  }
}

Cursor

Add the following to your Cursor MCP configuration file (.cursor/mcp.json in your project root or ~/.cursor/mcp.json globally).

json
{
  "mcpServers": {
    "apviso": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@apviso/mcp"
      ],
      "env": {
        "APVISO_API_KEY": "apvk_your_key_here"
      }
    }
  }
}

Windsurf

Add the following to your Windsurf MCP configuration file (~/.codeium/windsurf/mcp_config.json).

json
{
  "mcpServers": {
    "apviso": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@apviso/mcp"
      ],
      "env": {
        "APVISO_API_KEY": "apvk_your_key_here"
      }
    }
  }
}

VS Code

Add the following to your VS Code settings.json (User or Workspace).

json
{
  "mcp": {
    "servers": {
      "apviso": {
        "type": "stdio",
        "command": "npx",
        "args": [
          "-y",
          "@apviso/mcp"
        ],
        "env": {
          "APVISO_API_KEY": "apvk_your_key_here"
        }
      }
    }
  }
}

Environment Variables

VariableRequiredDescription
APVISO_API_KEYYesYour API key (starts with apvk_). Generate in Settings → API Keys.
APVISO_API_URLNoAPI base URL. Defaults to https://apviso.com/api.

Tool Reference

All 18 tools available in the APVISO MCP server.

Quota & Credits

Check subscription usage and remaining credits.

get_quota

Returns your current subscription tier, the number of credits remaining for full scans and retests, and the start/end dates of the current billing period.

No parameters required.

Returns

Subscription tier name, total and remaining credits for full scans and retests, billing period start and end dates, and whether pay-as-you-go overage is enabled.

Example Input

json
{}

Example Output

json
{
  "tier": "professional",
  "billingPeriod": {
    "start": "2026-04-01T00:00:00Z",
    "end": "2026-05-01T00:00:00Z"
  },
  "fullScans": {
    "total": 20,
    "used": 7,
    "remaining": 13
  },
  "retests": {
    "total": 40,
    "used": 12,
    "remaining": 28
  },
  "paygEnabled": false
}

Targets

Register and manage scan targets.

list_targets

Returns a paginated list of all targets registered to your account, including their verification status and most recent scan date.

Parameters

NameTypeDescription
page
numberPage number for pagination.
limit
number
Default: 20
Number of targets per page.

Returns

Paginated array of targets with id, domain, verification status, created date, and last scan date.

Example Input

json
{
  "page": 1,
  "limit": 10
}

Example Output

json
{
  "data": [
    {
      "id": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
      "domain": "example.com",
      "verified": true,
      "verificationMethod": "dns_txt",
      "createdAt": "2026-03-15T10:30:00Z",
      "lastScanAt": "2026-04-08T14:22:00Z"
    },
    {
      "id": "019560a4-9e10-7a1b-bc4d-e5f6a7b8c9d0",
      "domain": "staging.example.com",
      "verified": false,
      "verificationMethod": null,
      "createdAt": "2026-04-09T08:15:00Z",
      "lastScanAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1
  }
}
get_target

Returns full details for a single target, including verification status, scan history summary, and associated domain metadata.

Parameters

NameTypeDescription
targetIdrequired
stringUUIDv7 identifier of the target.

Returns

Target object with id, domain, verification details, scan count, and timestamps.

Example Input

json
{
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9"
}

Example Output

json
{
  "id": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
  "domain": "example.com",
  "verified": true,
  "verificationMethod": "dns_txt",
  "verifiedAt": "2026-03-15T11:02:00Z",
  "totalScans": 5,
  "lastScanAt": "2026-04-08T14:22:00Z",
  "createdAt": "2026-03-15T10:30:00Z"
}
create_target

Registers a new target domain. The target must be verified before you can start any scans against it.

After creating a target, use get_verification_instructions to see how to verify ownership, then call verify_target once the verification record is in place.

Parameters

NameTypeDescription
domainrequired
stringFully qualified domain name to register (e.g. example.com or app.example.com).

Returns

Newly created target object with id, domain, and verification instructions.

Example Input

json
{
  "domain": "app.example.com"
}

Example Output

json
{
  "id": "019560a5-1b40-7d2c-ae3f-b6c7d8e9f0a1",
  "domain": "app.example.com",
  "verified": false,
  "verificationToken": "apviso-verify=a1b2c3d4e5f6",
  "createdAt": "2026-04-10T09:00:00Z"
}
verify_target

Triggers a verification check for the specified target and method. The appropriate DNS record, file, or meta tag must already be in place before calling this tool.

Parameters

NameTypeDescription
targetIdrequired
stringUUIDv7 identifier of the target to verify.
methodrequired
string
dns_txtfilemeta_tag
Verification method to attempt.

Returns

Updated target object with verified status set to true on success, or an error message describing what went wrong.

Example Input

json
{
  "targetId": "019560a5-1b40-7d2c-ae3f-b6c7d8e9f0a1",
  "method": "dns_txt"
}

Example Output

json
{
  "id": "019560a5-1b40-7d2c-ae3f-b6c7d8e9f0a1",
  "domain": "app.example.com",
  "verified": true,
  "verificationMethod": "dns_txt",
  "verifiedAt": "2026-04-10T09:05:00Z"
}
get_verification_instructions

Returns the verification token and step-by-step instructions for each supported verification method (DNS TXT, file upload, and meta tag).

Parameters

NameTypeDescription
targetIdrequired
stringUUIDv7 identifier of the target.

Returns

Verification token and detailed instructions for dns_txt, file, and meta_tag methods.

Example Input

json
{
  "targetId": "019560a5-1b40-7d2c-ae3f-b6c7d8e9f0a1"
}

Example Output

json
{
  "token": "apviso-verify=a1b2c3d4e5f6",
  "methods": {
    "dns_txt": {
      "type": "TXT",
      "host": "_apviso.app.example.com",
      "value": "apviso-verify=a1b2c3d4e5f6",
      "instructions": "Add a TXT record for _apviso.app.example.com with the value shown above."
    },
    "file": {
      "path": "/.well-known/penterep-verify.txt",
      "content": "apviso-verify=a1b2c3d4e5f6",
      "instructions": "Create a file at https://app.example.com/.well-known/penterep-verify.txt containing the token."
    },
    "meta_tag": {
      "tag": "<meta name=\"apviso-verification\" content=\"apviso-verify=a1b2c3d4e5f6\">",
      "instructions": "Add the meta tag to the <head> section of your site's homepage."
    }
  }
}
delete_target

Permanently deletes a target. This will fail if the target has any associated scans. Remove all scans first if you need to delete the target.

Cannot delete a target that has associated scans. This is irreversible.

Parameters

NameTypeDescription
targetIdrequired
stringUUIDv7 identifier of the target to delete.

Returns

Confirmation message on success.

Example Input

json
{
  "targetId": "019560a4-9e10-7a1b-bc4d-e5f6a7b8c9d0"
}

Example Output

json
{
  "message": "Target deleted successfully."
}

Scans

Start and monitor penetration test scans.

list_scans

Returns a paginated list of scans, optionally filtered by status. Includes scan id, target domain, status, timestamps, and finding counts.

Parameters

NameTypeDescription
page
numberPage number for pagination.
limit
number
Default: 20
Number of scans per page.
status
string
queuedprovisioningrunningcompletedfailedcancelled
Filter scans by status.

Returns

Paginated array of scans with id, target info, status, timing, and finding summary.

Example Input

json
{
  "status": "completed",
  "limit": 5
}

Example Output

json
{
  "data": [
    {
      "id": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3",
      "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
      "targetDomain": "example.com",
      "status": "completed",
      "isRetest": false,
      "modelPreset": "high",
      "findingsSummary": {
        "critical": 1,
        "high": 3,
        "medium": 7,
        "low": 4,
        "info": 12
      },
      "startedAt": "2026-04-08T14:22:00Z",
      "completedAt": "2026-04-08T15:48:00Z",
      "createdAt": "2026-04-08T14:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 1,
    "totalPages": 1
  }
}
get_scan

Returns detailed information about a specific scan, including its current status, configuration, timing, and high-level finding counts.

Parameters

NameTypeDescription
scanIdrequired
stringUUIDv7 identifier of the scan.

Returns

Full scan object with id, target, status, model preset, timing, and findings summary.

Example Input

json
{
  "scanId": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3"
}

Example Output

json
{
  "id": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3",
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
  "targetDomain": "example.com",
  "status": "completed",
  "isRetest": false,
  "parentScanId": null,
  "modelPreset": "high",
  "findingsSummary": {
    "critical": 1,
    "high": 3,
    "medium": 7,
    "low": 4,
    "info": 12
  },
  "startedAt": "2026-04-08T14:22:00Z",
  "completedAt": "2026-04-08T15:48:00Z",
  "createdAt": "2026-04-08T14:20:00Z"
}
create_scan

Creates a new penetration test scan against a verified target. This is a billable action that consumes one full scan or retest credit from your quota. Check your remaining credits with get_quota before calling this tool.

This action is billable. Always check get_quota first to confirm you have remaining credits. The target must be verified before scanning.

Parameters

NameTypeDescription
targetIdrequired
stringUUIDv7 identifier of a verified target to scan.
isRetest
boolean
Default: false
Set to true to run a retest instead of a full scan. Retests focus on previously found vulnerabilities.
parentScanId
stringUUIDv7 of the original scan when running a retest. Required if isRetest is true.
findingIds
string[]Array of finding UUIDv7 IDs to retest. When omitted during a retest, all findings from the parent scan are retested.
modelPreset
string
freelowmediumhighultra
AI model quality preset. Higher presets use more capable models and consume more credits.
promoCode
stringPromotional code for discounted or free scans.

Returns

Newly created scan object with id, status (queued), and estimated start time.

Example Input

json
{
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
  "modelPreset": "high"
}

Example Output

json
{
  "id": "019560c8-5d70-7f8a-c1b2-d3e4f5a6b7c8",
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
  "targetDomain": "example.com",
  "status": "queued",
  "isRetest": false,
  "modelPreset": "high",
  "estimatedStartAt": "2026-04-10T09:12:00Z",
  "createdAt": "2026-04-10T09:10:00Z"
}

Findings

View and manage vulnerability findings.

list_findings

Returns a paginated list of vulnerability findings for a given scan. Descriptions are truncated to 500 characters; use get_report for the full details.

Descriptions are truncated to 500 characters. Use get_report for complete vulnerability details, reproduction steps, and remediation guidance.

Parameters

NameTypeDescription
scanIdrequired
stringUUIDv7 identifier of the scan.
page
numberPage number for pagination.
limit
number
Default: 20
Number of findings per page.
severity
string
criticalhighmediumlowinfo
Filter by severity level.
userStatus
string
openin_progressfixedaccepted_riskfalse_positive
Filter by remediation status.

Returns

Paginated array of findings with id, title, severity, CVSS score, user status, and truncated description.

Example Input

json
{
  "scanId": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3",
  "severity": "critical"
}

Example Output

json
{
  "data": [
    {
      "id": "019560d1-8e90-7b3c-d4e5-f6a7b8c9d0e1",
      "scanId": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3",
      "title": "SQL Injection in /api/users endpoint",
      "severity": "critical",
      "cvssScore": 9.8,
      "cvssVector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
      "userStatus": "open",
      "description": "A SQL injection vulnerability was identified in the /api/users endpoint. The 'id' parameter is directly concatenated into a SQL query without proper sanitization or parameterized queries. An unauthenticated attacker can extract, modify, or delete arbitrary data from the database, including user credentials and session tokens...",
      "cweId": "CWE-89",
      "affectedUrl": "https://example.com/api/users?id=1",
      "createdAt": "2026-04-08T14:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}
update_finding_status

Updates the remediation status of a finding to track your progress. Use this to mark findings as in progress, fixed, accepted risk, or false positive.

Parameters

NameTypeDescription
findingIdrequired
stringUUIDv7 identifier of the finding.
userStatusrequired
string
openin_progressfixedaccepted_riskfalse_positive
New remediation status for the finding.

Returns

Updated finding object with the new user status.

Example Input

json
{
  "findingId": "019560d1-8e90-7b3c-d4e5-f6a7b8c9d0e1",
  "userStatus": "in_progress"
}

Example Output

json
{
  "id": "019560d1-8e90-7b3c-d4e5-f6a7b8c9d0e1",
  "title": "SQL Injection in /api/users endpoint",
  "severity": "critical",
  "userStatus": "in_progress",
  "updatedAt": "2026-04-10T09:30:00Z"
}

Reports

Access full penetration test reports.

get_report

Returns the full penetration test report for a completed scan in Markdown format, along with a signed URL to download the PDF version. Reports include an executive summary, detailed findings with reproduction steps, remediation guidance, and risk ratings. May return HTTP 202 if the report is still being generated.

If the report is still generating, the response will have status 'generating' with an estimated completion time. Poll again after a short wait.

Parameters

NameTypeDescription
scanIdrequired
stringUUIDv7 identifier of the scan to retrieve the report for.

Returns

Full Markdown report content, PDF download URL, and generation metadata.

Example Input

json
{
  "scanId": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3"
}

Example Output

json
{
  "scanId": "019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3",
  "status": "ready",
  "format": "markdown",
  "content": "# Penetration Test Report\\n\\n## Executive Summary\\n\\nA penetration test was conducted against example.com on April 8, 2026. The assessment identified 27 findings: 1 critical, 3 high, 7 medium, 4 low, and 12 informational...\\n\\n## Critical Findings\\n\\n### 1. SQL Injection in /api/users endpoint\\n\\n**Severity:** Critical (CVSS 9.8)\\n**CWE:** CWE-89\\n\\n#### Description\\n\\nA SQL injection vulnerability was identified...",
  "pdfUrl": "https://storage.apviso.com/reports/019560b2-3a50-7e4d-bf60-c8d9eaf1b2c3.pdf?sig=abc123&exp=1712750400",
  "pdfExpiresAt": "2026-04-10T12:00:00Z",
  "generatedAt": "2026-04-08T16:02:00Z"
}

Schedules

Manage recurring scan schedules. Requires Business tier or higher.

list_schedules

Returns all scan schedules configured on your account, including their frequency, next run time, and enabled status.

No parameters required.

Returns

Array of schedule objects with id, target, frequency, timing, enabled status, and next run time.

Example Input

json
{}

Example Output

json
{
  "data": [
    {
      "id": "019560e4-a1b0-7c5d-e6f7-a8b9c0d1e2f3",
      "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
      "targetDomain": "example.com",
      "frequency": "weekly",
      "hour": 2,
      "minute": 0,
      "dayOfWeek": 1,
      "dayOfMonth": null,
      "modelPreset": "high",
      "allowPayg": false,
      "enabled": true,
      "nextRunAt": "2026-04-14T02:00:00Z",
      "lastRunAt": "2026-04-07T02:00:00Z",
      "createdAt": "2026-03-20T15:00:00Z"
    }
  ]
}
get_schedule

Returns full details for a specific scan schedule, including its configuration and execution history summary.

Parameters

NameTypeDescription
scheduleIdrequired
stringUUIDv7 identifier of the schedule.

Returns

Schedule object with full configuration, timing, and recent execution history.

Example Input

json
{
  "scheduleId": "019560e4-a1b0-7c5d-e6f7-a8b9c0d1e2f3"
}

Example Output

json
{
  "id": "019560e4-a1b0-7c5d-e6f7-a8b9c0d1e2f3",
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
  "targetDomain": "example.com",
  "frequency": "weekly",
  "hour": 2,
  "minute": 0,
  "dayOfWeek": 1,
  "dayOfMonth": null,
  "modelPreset": "high",
  "allowPayg": false,
  "enabled": true,
  "nextRunAt": "2026-04-14T02:00:00Z",
  "lastRunAt": "2026-04-07T02:00:00Z",
  "totalRuns": 3,
  "createdAt": "2026-03-20T15:00:00Z",
  "updatedAt": "2026-04-07T02:01:00Z"
}
create_schedule

Creates a new recurring scan schedule for a verified target. Requires Business tier or higher. Scans run automatically at the specified time and frequency.

Requires Business tier or higher. The schedule will skip execution if quota is exhausted and allowPayg is false.

Parameters

NameTypeDescription
targetIdrequired
stringUUIDv7 identifier of a verified target.
frequencyrequired
string
dailyweeklybiweeklymonthly
How often the scan should run.
hourrequired
numberHour of day to run the scan (UTC).
minute
number
Default: 0
Minute of the hour to run the scan (UTC).
dayOfWeek
numberDay of week for weekly/biweekly schedules. 0 = Sunday, 6 = Saturday.
dayOfMonth
numberDay of month for monthly schedules. Limited to 1-28 to avoid month-length issues.
modelPreset
string
lowmediumhighultra
AI model quality preset for scheduled scans.
allowPayg
boolean
Default: false
Allow pay-as-you-go overage charges if quota is exhausted when the scheduled scan runs.

Returns

Newly created schedule object with id, configuration, and next run time.

Example Input

json
{
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
  "frequency": "weekly",
  "hour": 2,
  "minute": 0,
  "dayOfWeek": 1,
  "modelPreset": "high"
}

Example Output

json
{
  "id": "019560f5-b2c0-7d6e-f8a9-b0c1d2e3f4a5",
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
  "targetDomain": "example.com",
  "frequency": "weekly",
  "hour": 2,
  "minute": 0,
  "dayOfWeek": 1,
  "dayOfMonth": null,
  "modelPreset": "high",
  "allowPayg": false,
  "enabled": true,
  "nextRunAt": "2026-04-14T02:00:00Z",
  "createdAt": "2026-04-10T09:45:00Z"
}
update_schedule

Updates an existing scan schedule. You can modify the frequency, timing, model preset, or enable/disable the schedule. Only provided fields are updated.

Parameters

NameTypeDescription
scheduleIdrequired
stringUUIDv7 identifier of the schedule to update.
frequency
string
dailyweeklybiweeklymonthly
New frequency for the schedule.
hour
numberNew hour of day (UTC).
minute
numberNew minute of the hour (UTC).
dayOfWeek
numberNew day of week (0 = Sunday, 6 = Saturday).
dayOfMonth
numberNew day of month (1-28).
enabled
booleanSet to false to pause the schedule without deleting it.
modelPreset
string
lowmediumhighultra
New model quality preset.
allowPayg
booleanAllow pay-as-you-go overage when quota is exhausted.

Returns

Updated schedule object reflecting the changes.

Example Input

json
{
  "scheduleId": "019560e4-a1b0-7c5d-e6f7-a8b9c0d1e2f3",
  "enabled": false
}

Example Output

json
{
  "id": "019560e4-a1b0-7c5d-e6f7-a8b9c0d1e2f3",
  "targetId": "019560a4-7c30-7f3a-8b2e-d4f5a6b7c8d9",
  "targetDomain": "example.com",
  "frequency": "weekly",
  "hour": 2,
  "minute": 0,
  "dayOfWeek": 1,
  "dayOfMonth": null,
  "modelPreset": "high",
  "allowPayg": false,
  "enabled": false,
  "nextRunAt": null,
  "updatedAt": "2026-04-10T10:00:00Z"
}
delete_schedule

Permanently deletes a scan schedule. Any currently queued or running scan from this schedule will still complete, but no future scans will be created.

This is irreversible. In-flight scans spawned by this schedule will not be cancelled.

Parameters

NameTypeDescription
scheduleIdrequired
stringUUIDv7 identifier of the schedule to delete.

Returns

Confirmation message on success.

Example Input

json
{
  "scheduleId": "019560e4-a1b0-7c5d-e6f7-a8b9c0d1e2f3"
}

Example Output

json
{
  "message": "Schedule deleted successfully."
}
Back to Knowledge Base