FAQ & Troubleshooting

Yes — you must have a project folder open in your IDE before Veilguard will work. MCP servers run in the context of the active project directory. Without an open project there are no files to scan, and your IDE has no working directory to attach the MCP server to.

If Veilguard appears unresponsive or your AI agent doesn't recognise the scanner tools, the most common cause is opening your IDE without a project folder. Close and reopen your IDE with the project folder — not just a single file.

You have to ask. Veilguard does not automatically scan on every file save or code change — that behaviour depends on how each AI agent interprets its rules file, and it is not reliable across all IDEs. To run a scan, tell your AI agent directly: "scan this file for secrets", "check my API routes for injection vulnerabilities", or "audit my Supabase RLS policies". The agent will invoke the correct Veilguard scanner tool.

Check your IDE's MCP panel:

• Cursor: Settings → Tools & MCPs — Veilguard should appear in the tool list with a green status.
• VS Code: Open the MCP Servers view in the sidebar — Veilguard should show as running.
• Windsurf: Click the MCP icon in the bottom status bar — Veilguard should be listed.
• Claude Code: Run claude mcp list in your terminal — veilguard should appear.

If it's not listed, check that your MCP config file has no JSON syntax errors and that you restarted your IDE after adding the config.

The MCP server must be both installed and running before your AI agent can call any Veilguard tools. Confirm the server appears in your IDE's MCP panel (see above). If it's listed but the agent still doesn't use it, try explicitly naming the tool: "use scan_secrets to check this file". If it's not listed at all, the MCP config JSON is likely malformed or in the wrong location — recheck the installation guide for your IDE.

Yes. Open the project in your IDE, confirm Veilguard is connected, then ask your agent to scan the areas you're concerned about. A good starting point is to ask for a scan_secrets across the whole codebase, then check_git for anything that leaked into your git history. Pro users can run full_audit to get a graded report across all 14 scanners at once.

Veilguard scans whatever you direct your AI agent to look at. You can ask it to scan a specific file, a directory, a category of files (e.g. "all API routes"), or your entire project. There is no background watcher — scans are always initiated through a conversation with your AI agent.

It means the files and scanners you triggered found no issues. It does not mean your entire codebase is secure — only the specific files and checks that were run are covered. For broader confidence, ask your agent to scan different areas of the project or run a full audit (Pro).

No. Veilguard only reads files and reports findings — it never writes to your code. Fixes are always suggestions. You can ask your AI agent to apply a suggested fix, but the agent does that, not Veilguard itself. This keeps Veilguard's role clear: detect only, never change.

Secret detection (scan_secrets) and git history scanning (check_git) work on any file type — API keys look the same in Python, Go, or Ruby. The injection and webhook scanners are currently optimised for JavaScript/TypeScript codebases (Node.js, Next.js, Express). Supabase RLS and Firebase audits target their respective config formats and work regardless of your frontend language.

Most scanners are fully offline — they read files locally and match patterns locally. Two exceptions: the dependency CVE checker (scan_dependencies) sends package names (never code) to Google's OSV.dev API, and Pro license validation checks in with veilguard.dev once per 24 hours. After a successful validation, Pro features work offline for the remainder of that 24-hour window.

Check three things in order: (1) A project folder is open — not just a file. (2) The MCP config JSON has no syntax errors — paste it into a JSON validator to check. (3) You restarted your IDE after adding the config. If all three are confirmed, check your IDE's MCP panel to see if the Veilguard server shows as running or errored.

Veilguard requires Node.js 18 or later. The error usually means your IDE is spawning the MCP process from a shell environment where Node is not in the PATH — common when using nvm or fnm. Run node --versionin your IDE's integrated terminal. If it fails there but works in a regular terminal, you need to configure your shell to load nvm/fnm before your IDE starts.

Confirm the key starts with vg_live_, has no leading or trailing spaces, and is placed in the VEILGUARD_KEY field of your MCP config's env block — not in the args array. Restart your IDE fully after adding it. If it still fails, your network may be blocking the one-time validation call to veilguard.dev.

Create a .veilguardignore file in the root of your project:

# .veilguardignore
# Ignore a specific file entirely
src/tests/mocks.ts

# Ignore a specific scanner rule across everything
- scan_secrets: stripe_test_key

No. The full_audit tool runs unlimited on Pro, and all 14 individual scanners run without any limit on any tier — you can run them as often as you like.

The Pro license is per user, not per project. One key covers all your personal projects running on a single machine. Add the same VEILGUARD_KEYto the MCP config in each project's IDE setup.

No. All scanning happens locally on your machine. The only outbound network calls are: (1) OSV.dev — receives only package names and versions, never source code, to check for known CVEs. (2) veilguard.dev — receives only your license key for Pro validation, once per 24 hours. Your source code never leaves your machine.

The Veilguard CLI and core scanners are source-available — you can read exactly what runs on your machine on GitHub. The backend grading engine and Pro license validation are proprietary.