Skip to main content

​
Overview

VulnZap integrates with modern IDEs through the Model Context Protocol (MCP), providing real-time vulnerability detection as you code and when AI assistants generate code.

​
Supported IDEs

Cursor

Full MCP support with agent-aware scanning

Windsurf

Real-time inline detection and AI guardrails

Cline

Agentic workflow protection

VS Code

Via MCP extension (beta)

​
Model Context Protocol (MCP)

VulnZap exposes seven MCP tools for AI agent integration. These tools enable autonomous security scanning during development workflows.

​
MCP Tools Reference

​
Tool 1: vulnzap_scan_diff

Performs fast, non-blocking incremental scan on git diff. Purpose: Scan only changed files since a specific commit reference. Designed for frequent use during active development. Input Schema: 
{
  repo: string;              // Repository path (default: ".")
  since?: string;            // Commit/ref to diff against (default: "HEAD")
  paths?: string[];          // Optional glob patterns to limit scope
}
Response: 
{
  scan_id: string;           // Unique scan identifier
  queued: boolean;           // Scan queued status
  eta_ms: number;            // Estimated completion time
  next_hint: string;         // Suggested next action
  summary: {
    files_considered: number;
    mode: "diff";
  }
}
Usage Pattern: 
1. Make code changes
2. Call vulnzap_scan_diff
3. Continue coding (non-blocking)
4. Poll vulnzap_status before next commit

​
Tool 2: vulnzap_status

Retrieve scan results for a specific scan ID or latest scan. Purpose: Check completion status and retrieve vulnerability findings. Primary mechanism for agents to discover security issues. Input Schema: 
{
  repo: string;              // Repository path
  scan_id?: string;          // Specific scan to check
  latest?: boolean;          // Get latest scan for repo
}
Response (Completed): 
{
  ready: true;
  findings: Array<{
    id: string;
    severity: "critical" | "high" | "medium" | "low";
    path: string;
    range: {
      start: { line: number; col: number; }
    };
    description: string;
  }>;
  next_hint: string;
}
Response (In Progress): 
{
  ready: false;
  poll_after_ms: number;     // Suggested polling interval
}
Polling Strategy:
  • Initial poll: 5 seconds
  • Subsequent polls: 5-30 seconds with exponential backoff
  • Do not poll continuously

​
Tool 3: vulnzap_full_scan

Comprehensive repository-wide security scan. Purpose: Baseline security analysis of entire codebase. Reserved for pre-deployment or pre-push workflows. Input Schema: 
{
  repo: string;              // Repository path (default: ".")
}
Response: 
{
  scan_id: string;           // Unique scan identifier
  queued: boolean;           // Scan queued status
  eta_ms: number;            // Estimated completion (typically 180000ms)
}
Performance Characteristics:
  • Significantly slower than diff scans
  • Scans entire repository history
  • Use sparingly (pre-push, pre-deploy only)
  • Poll results via vulnzap_status

​
Tool 4: vulnzap_report

Generate human-readable scan report in markdown format. Purpose: Create formatted vulnerability reports for PR descriptions, documentation, or audit logs. Input Schema: 
{
  repo: string;              // Repository path
  scan_id: string;           // Scan to generate report for
}
Response: 
{
  report: string;            // Markdown-formatted report
}
Report Contents:
  • Vulnerability summary
  • Severity breakdown
  • Affected files and line numbers
  • Remediation recommendations
  • Reference links

​
Tool 5: vulnzap_security_assistant

Start file watcher for incremental security analysis. Purpose: Monitor directory for changes and perform continuous security scanning. Designed for active development sessions. Input Schema: 
{
  path: string;              // Directory path to monitor
}
Response: 
{
  message: string;
  nextSteps: string;         // Instructions for retrieving results
  sessionId: string;         // Session identifier (in nextSteps)
}
Workflow: 
1. Call vulnzap_security_assistant with target directory
2. Receive session ID
3. Make code changes
4. Wait 10+ seconds for analysis
5. Call vulnzap_security_assistant_results with session ID
Session Management:
  • Automatic timeout: 60 seconds of inactivity
  • Timeout resets on each file change
  • Session data cached in .vulnzap/client/sessions/

​
Tool 6: vulnzap_security_assistant_results

Retrieve results from active security assistant session. Purpose: Fetch vulnerability findings from incremental scan session. Input Schema: 
{
  session: string;           // Session ID from security_assistant
  wait?: number;             // Optional wait time in seconds
}
Response (Success): 
{
  response: {
    findings: Array<Vulnerability>;
    summary: string;
    scannedFiles: string[];
  }
}
Response (Error): 
{
  error: string;             // Error description
}
Best Practices:
  • Wait 10+ seconds after code changes before calling
  • Use wait parameter to add additional delay if needed
  • Session must be active (not timed out)

​
Tool 7: vulnzap_security_assistant_stop

Terminate security assistant session and retrieve final results. Purpose: Explicitly stop file watching and get final scan results. Input Schema: 
{
  session: string;           // Session ID to stop
}
Response (Success): 
{
  message: string;
  nextSteps: string;
  response: {
    findings: Array<Vulnerability>;
    summary: string;
  }
}
Response (Error): 
{
  error: string;
}
Use Cases:
  • Manual session termination
  • Retrieve final results before timeout
  • Clean up resources after development session

​
MCP Agent Workflow

Recommended integration pattern for AI agents:

​
Initialization Phase

1. Call vulnzap_status with {latest: true, repo: "."}
2. Review any existing vulnerabilities
3. Fix critical issues before proceeding

​
Active Development Phase

1. Make code changes
2. Call vulnzap_scan_diff with {repo: ".", since: "HEAD"}
3. Continue development (non-blocking)
4. Periodically call vulnzap_status to check results
5. If vulnerabilities found:
   a. Fix issues
   b. Call vulnzap_scan_diff again
   c. Verify fixes with vulnzap_status

​
Pre-Commit Phase

1. Call vulnzap_status to ensure no pending issues
2. If clean, proceed with commit
3. If issues found, fix and rescan

​
Pre-Push Phase

1. Call vulnzap_full_scan with {repo: "."}
2. Poll vulnzap_status until ready: true
3. Review all findings
4. Fix critical and high severity issues
5. Call vulnzap_report for documentation
6. Attach report to PR description

​
Continuous Monitoring (Alternative)

1. Call vulnzap_security_assistant with {path: "./src"}
2. Save session ID
3. Make code changes
4. Wait 10+ seconds
5. Call vulnzap_security_assistant_results
6. Review findings and fix issues
7. Call vulnzap_security_assistant_stop when done

​
Configuration

​
IDE MCP Configuration

​
Cursor IDE

File: .cursor/mcp.json 
{
  "mcpServers": {
    "VulnZap": {
      "command": "npx",
      "args": ["vulnzap", "mcp"],
      "env": {
        "VULNZAP_API_KEY": "your_api_key"
      }
    }
  }
}

​
Windsurf IDE

File: .codeium/windsurf/mcp_config.json 
{
  "mcpServers": {
    "VulnZap": {
      "command": "npx",
      "args": ["vulnzap", "mcp"],
      "env": {
        "VULNZAP_API_KEY": "your_api_key"
      }
    }
  }
}

​
Cline

Configured via vulnzap connect --ide cline. Manual configuration requires setting MCP server command to npx vulnzap mcp with VULNZAP_API_KEY environment variable.

​
Environment Variables

  • VULNZAP_API_KEY: Authentication key for API access
  • VULNZAP_DEBUG: Enable debug logging for MCP server

​
Next Steps

CLI Guide

Master command-line scanning

CI/CD Integration

Automate security in pipelines

Dashboard Guide

Manage findings centrally