Troubleshooting and FAQ

Troubleshooting and FAQ

Diagnostics first

When anything looks wrong, run the built-in doctor:

security-mcp doctor   # alias: security-mcp verify

It checks that Node is at least 20 and that your editor MCP configs are wired correctly.

Install issues

Node too old. The tool requires Node >= 20. Upgrade Node, then re-run the installer. doctor reports the detected version.

Editor did not pick up the server. The installer auto-detects and writes to:

Editor	Config
Claude Code	~/.claude/settings.json
Cursor	~/.cursor/mcp.json or project .cursor/mcp.json
VS Code	User settings.json under the mcp.servers key
Windsurf	~/.windsurf/mcp.json

If your editor still does not list the tools, re-run security-mcp install (or install-global), confirm the config path above was written, and fully restart the editor. Run doctor to confirm the config is valid. Codex, Replit, and other MCP editors can be pointed at the server manually using the same serve command.

Permissions on .mcp/. Artifacts are written 0o600. If a run cannot write, check that the process owner can create files under the repo's .mcp/ directory.

Connection issues

Tools listed but calls fail with an auth error. You have SECURITY_MCP_SHARED_SECRET set. Call authenticate first, ensure the secret is at least 32 bytes, and remember three failed attempts lock the caller out. Sessions expire after 8 hours by default (SECURITY_SESSION_TTL_MS).

Server starts then exits. Run security-mcp serve directly in a terminal to see the startup error, then doctor.

Gate issues

Gate fails on a finding you have accepted. Add a signed exception (see Configuration and Policy). Remember: no self-approval, 365-day max expiry, and expired exceptions block again.

Gate reports a coverage gap as HIGH. A check module crashed or a required scanner is missing. Install the missing scanner (gitleaks, semgrep, trivy, osv-scanner, checkov, conftest, zaproxy) or check the run log for the failing module. Coverage gaps are intentionally loud.

Diff scope looks wrong in CI. Use fetch-depth: 0 so the gate has full history, and set SECURITY_GATE_BASE_REF and SECURITY_GATE_HEAD_REF correctly. See CI/CD Integration.

Policy seems to be ignored or floored to HIGH/CRITICAL. The policy is unsigned or its signature failed. Sign it with security-mcp sign-policy (key >= 32 bytes) and commit the .hmac sidecar.

Attestation refuses to write. The result was not a clean PASS. Attestation will not sign a failing or incomplete run. Resolve the blocking findings, or, only for a genuine emergency, use the documented break-glass variable.

FAQ

Does my code leave my machine? No. The server runs locally and your source stays on disk. The only outbound calls are optional npm, GitHub, and threat-intel lookups, and only when permitted. Set SECURITY_OFFLINE to disable all egress. Private scoped package names are never sent to public endpoints.

Do I need a security background? No. The senior security engineer is built for non-specialists: it explains findings and writes the fixes. Its mandate is 90% fixing, 10% advisory.

Is this a replacement for a penetration test? It is continuous coverage that runs on every change. For deep, adversarial assurance before a major release, run the CISO Orchestrator, which includes a dedicated pentest team and compliance synthesis.

What AI models does it use? It is model-agnostic. security-mcp is an MCP server that works with whatever provider your editor or client is configured with. Its router selects cost-appropriate models per task and tracks spend.

Editor and platform support? Claude Code, Cursor, VS Code / Copilot, Windsurf, Codex, Replit, and any MCP-capable editor.

How do I report a vulnerability in the tool itself? Use GitHub private vulnerability reporting; see SECURITY.md in the repo.