> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vulnzap.com/llms.txt
> Use this file to discover all available pages before exploring further.
# IDE Integration
> Set up real-time security scanning in Cursor, Windsurf, Cline, and VS Code via MCP protocol
## 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
Full MCP support with agent-aware scanning
Real-time inline detection and AI guardrails
Agentic workflow protection
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**:
```typescript theme={null}
{
repo: string; // Repository path (default: ".")
since?: string; // Commit/ref to diff against (default: "HEAD")
paths?: string[]; // Optional glob patterns to limit scope
}
```
**Response**:
```typescript theme={null}
{
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**:
```typescript theme={null}
{
repo: string; // Repository path
scan_id?: string; // Specific scan to check
latest?: boolean; // Get latest scan for repo
}
```
**Response (Completed)**:
```typescript theme={null}
{
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)**:
```typescript theme={null}
{
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**:
```typescript theme={null}
{
repo: string; // Repository path (default: ".")
}
```
**Response**:
```typescript theme={null}
{
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**:
```typescript theme={null}
{
repo: string; // Repository path
scan_id: string; // Scan to generate report for
}
```
**Response**:
```typescript theme={null}
{
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**:
```typescript theme={null}
{
path: string; // Directory path to monitor
}
```
**Response**:
```typescript theme={null}
{
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**:
```typescript theme={null}
{
session: string; // Session ID from security_assistant
wait?: number; // Optional wait time in seconds
}
```
**Response (Success)**:
```typescript theme={null}
{
response: {
findings: Array;
summary: string;
scannedFiles: string[];
}
}
```
**Response (Error)**:
```typescript theme={null}
{
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**:
```typescript theme={null}
{
session: string; // Session ID to stop
}
```
**Response (Success)**:
```typescript theme={null}
{
message: string;
nextSteps: string;
response: {
findings: Array;
summary: string;
}
}
```
**Response (Error)**:
```typescript theme={null}
{
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`
```json theme={null}
{
"mcpServers": {
"VulnZap": {
"command": "npx",
"args": ["vulnzap", "mcp"],
"env": {
"VULNZAP_API_KEY": "your_api_key"
}
}
}
}
```
#### Windsurf IDE
File: `.codeium/windsurf/mcp_config.json`
```json theme={null}
{
"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
Master command-line scanning
Automate security in pipelines
Manage findings centrally