Step-by-Step Guide
A complete walkthrough for connecting SafeWeave to your AI code editor. Pick your editor, paste one config snippet, and start scanning — the entire process takes under two minutes.
Make sure you have the following ready. No SafeWeave account is required for the free tier.
Required
Node.js v18+
SafeWeave runs via npx. Any Node.js version from 18 upward works. Run node --version to check.
Required
AI Code Editor
Cursor, Claude Code, VS Code with Copilot, or Windsurf. Any editor that supports the Model Context Protocol.
Time
~2 Minutes
One config file or one CLI command. No build steps, no Docker, no CI pipeline changes needed.
Find your editor below and follow the instructions. Each guide shows the exact config file path and JSON you need — copy, paste, and go.
Create a file called .cursor/mcp.json in your project root (or your home directory for global access). Cursor will detect the MCP server on its next restart.
{
"mcpServers": {
"safeweave": {
"command": "npx",
"args": ["-y", "safeweave-mcp"],
"env": {
"SAFEWEAVE_LICENSE_KEY": "sw_free_xxx"
}
}
}
}Note: Omit the env block entirely to use the free tier — no license key needed.
Claude Code supports adding MCP servers directly from the command line. Run a single command and Claude picks it up immediately — no file editing, no restart.
# Add SafeWeave as an MCP server (free tier — no key needed)
$ claude mcp add safeweave -- npx -y safeweave-mcp
# With a license key for paid-plan features
$ claude mcp add safeweave \
-e SAFEWEAVE_LICENSE_KEY=sw_free_xxx \
-- npx -y safeweave-mcpNote: Run claude mcp list to verify SafeWeave appears in the active servers.
Create .vscode/mcp.json in your workspace root. VS Code with GitHub Copilot agent mode will detect it automatically. Works with any Copilot-enabled extension.
{
"servers": {
"safeweave": {
"command": "npx",
"args": ["-y", "safeweave-mcp"],
"env": {
"SAFEWEAVE_LICENSE_KEY": "sw_free_xxx"
}
}
}
}Note: Requires VS Code 1.99+ with GitHub Copilot agent mode enabled.
Windsurf reads MCP configuration from a global config file in your home directory. Create or edit the file at ~/.codeium/windsurf/mcp_config.json.
{
"mcpServers": {
"safeweave": {
"command": "npx",
"args": ["-y", "safeweave-mcp"],
"env": {
"SAFEWEAVE_LICENSE_KEY": "sw_free_xxx"
}
}
}
}Note: Restart Windsurf after saving the config to load the new MCP server.
Under the Hood
SafeWeave uses the Model Context Protocol (MCP) to bridge your AI assistant and the security scanners. On Free, every scanner runs locally and your code never leaves your machine; results flow back through the same MCP channel. With a Cloud key, editor scans run on SafeWeave's servers by default.
You (AI Editor)
│
▼ natural-language prompt
┌─────────────────────────────┐
│ AI Model (LLM) │
│ recognizes "scan" intent │
└─────────────┬───────────────┘
│ MCP tool call
▼
┌─────────────────────────────┐
│ SafeWeave MCP Server │ ← runs locally (npx safeweave-mcp)
│ routes to scanner engine │
└─────────────┬───────────────┘
│ parallel dispatch
┌───────┼───────┐
▼ ▼ ▼
┌──────┐┌──────┐┌──────┐
│ SAST ││Secret││ Deps │ ...up to 8 scanners
└──┬───┘└──┬───┘└──┬───┘
│ │ │
└───────┼───────┘
▼
┌─────────────────────────────┐
│ Structured JSON findings │
│ severity · file · line · │
│ CWE · remediation │
└─────────────┬───────────────┘
│ MCP response
▼
┌─────────────────────────────┐
│ AI explains findings and │
│ offers to fix them inline │
└─────────────────────────────┘Type a natural-language prompt like "scan this project for vulnerabilities" in your editor. No special syntax needed.
Your editor sends the request over the Model Context Protocol to the SafeWeave MCP server running locally on your machine.
SafeWeave dispatches up to 8 scanners simultaneously — SAST, Secrets, Dependencies, IaC, Container, DAST, License, and Posture. Each scanner processes your codebase independently.
Structured JSON findings — severity, file path, line number, CWE ID, and remediation guidance — are sent back through MCP to your AI assistant.
Your AI already has the code context. It explains each finding in plain English and can apply fixes directly — no context switching, no dashboard tab.
Performance
Scanners execute in parallel, not sequentially. A typical project with 500 files completes a full 8-scanner sweep in roughly 12 seconds. The no-signup trial (SAST, secrets and dependencies) usually finishes in under 5 seconds. Results are streamed as each scanner completes, so your AI can start explaining findings before the full scan is done.
Troubleshooting
Most setup problems fall into one of these categories. Click any item to expand the solution.
This usually means Node.js is not installed or is below the required version. SafeWeave needs Node.js v18 or later. Run node --version to check. If it is outdated, install the latest LTS from nodejs.org. You can also try clearing the npm cache with npm cache clean --force and then running npx safeweave-mcp again.
Verify your key starts with sw_free_ (Free), sw_cloud_ (Cloud), or sw_cloudplus_ (Cloud Plus). Keys are case-sensitive and must not include trailing whitespace. If you copied it from an email, paste it into a plain-text editor first to strip any hidden characters. If your subscription has lapsed, renew it at safeweave.dev/account to reactivate the key instantly.
For repositories with more than 10,000 files, scans can take longer than the default timeout. Create a .safeweave-ignore file in your project root (same syntax as .gitignore) to exclude directories like node_modules/, dist/, .next/, and vendor/. This dramatically reduces scan time. You can also run individual scanners instead of a full scan — ask your AI to "run only SAST" or "check just dependencies".
Possibly! But first, check which tier you are on. The no-signup trial runs SAST, secrets and dependencies. A free account adds IaC, container, license and posture; DAST runs on Cloud. Also verify the scan completed successfully by asking your AI "what scanners ran and what was the result?" — you should see a summary with scanner names and statuses.
The MCP server runs as a local process managed by your editor. If the connection drops, try restarting your editor. On macOS, also check that your terminal has permission to execute npx (System Settings > Privacy & Security > Developer Tools). If the problem persists, run npx safeweave-mcp manually in a terminal to see any error output — this often reveals missing dependencies or permission issues.
The first 10 scans need no account. A free account runs 7 scanners with unlimited local scans; DAST is on Cloud.