IDE Integration

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:

Make code changes
Call vulnzap_scan_diff
Continue coding (non-blocking)
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:

Call vulnzap_security_assistant with target directory
Receive session ID
Make code changes
Wait 10+ seconds for analysis
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

Call vulnzap_status with {latest: true, repo: "."}
Review any existing vulnerabilities
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

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

Pre-Push Phase

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

Continuous Monitoring (Alternative)

Call vulnzap_security_assistant with {path: "./src"}
Save session ID
Make code changes
Wait 10+ seconds
Call vulnzap_security_assistant_results
Review findings and fix issues
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

Getting Started

Core Features

Integration

Resources

IDE Integration

Overview

Supported IDEs

Cursor

Windsurf

Cline

VS Code

Model Context Protocol (MCP)

MCP Tools Reference

Tool 1: `vulnzap_scan_diff`

Tool 2: `vulnzap_status`

Tool 3: `vulnzap_full_scan`

Tool 4: `vulnzap_report`

Tool 5: `vulnzap_security_assistant`

Tool 6: `vulnzap_security_assistant_results`

Tool 7: `vulnzap_security_assistant_stop`

MCP Agent Workflow

Initialization Phase

Active Development Phase

Pre-Commit Phase

Pre-Push Phase

Continuous Monitoring (Alternative)

Configuration

IDE MCP Configuration

Cursor IDE

Windsurf IDE

Cline

Environment Variables

Next Steps

CLI Guide

CI/CD Integration

Dashboard Guide

​Overview

​Supported IDEs

Cursor

Windsurf

Cline

VS Code

​Model Context Protocol (MCP)

​MCP Tools Reference

​Tool 1: vulnzap_scan_diff

​Tool 2: vulnzap_status

​Tool 3: vulnzap_full_scan

​Tool 4: vulnzap_report

​Tool 5: vulnzap_security_assistant

​Tool 6: vulnzap_security_assistant_results

​Tool 7: vulnzap_security_assistant_stop

​MCP Agent Workflow

​Initialization Phase

​Active Development Phase

​Pre-Commit Phase

​Pre-Push Phase

​Continuous Monitoring (Alternative)

​Configuration

​IDE MCP Configuration

​Cursor IDE

​Windsurf IDE

​Cline

​Environment Variables

​Next Steps

CLI Guide

CI/CD Integration

Dashboard Guide

Overview

Supported IDEs

Model Context Protocol (MCP)

MCP Tools Reference

Tool 1: `vulnzap_scan_diff`

Tool 2: `vulnzap_status`

Tool 3: `vulnzap_full_scan`

Tool 4: `vulnzap_report`

Tool 5: `vulnzap_security_assistant`

Tool 6: `vulnzap_security_assistant_results`

Tool 7: `vulnzap_security_assistant_stop`

MCP Agent Workflow

Initialization Phase

Active Development Phase

Pre-Commit Phase

Pre-Push Phase

Continuous Monitoring (Alternative)

Configuration

IDE MCP Configuration

Cursor IDE

Windsurf IDE

Cline

Environment Variables

Next Steps