MCP server

Connect Claude Desktop, Claude Code, Cursor or any MCP client to your Vulnsy workspace so an AI assistant can read, draft and export reports using your API key.

The Vulnsy MCP server (vulnsy-mcp) implements the Model Context Protocol on top of the REST API. Once connected, an assistant can browse your clients, projects and reports, search both finding libraries, add and edit findings on a report, import scanner output, and export the finished DOCX, all inside the conversation.

It runs on your machine and talks only to your workspace. It keeps no state and sees only what your API key is allowed to see.

Requirements

Node.js 20 or newer on the machine running the assistant.
A workspace on the Business plan or above, or a self-hosted install whose licence includes the API.
An API key. Use a read-only key to explore and export; give it write scope when you want the assistant to author.

Set up

Two environment variables configure the server:

Variable	Value
`VULNSY_URL`	Your workspace origin, e.g. `https://acme.vulnsy.com`, or your self-hosted URL
`VULNSY_API_KEY`	The `vulnsy_sk_…` key

Claude Desktop

Add the server to claude_desktop_config.json (Settings → Developer → Edit Config) and restart Claude:

{
  "mcpServers": {
    "vulnsy": {
      "command": "npx",
      "args": ["-y", "vulnsy-mcp"],
      "env": {
        "VULNSY_URL": "https://acme.vulnsy.com",
        "VULNSY_API_KEY": "vulnsy_sk_..."
      }
    }
  }
}

Claude Code

claude mcp add vulnsy \
  -e VULNSY_URL=https://acme.vulnsy.com \
  -e VULNSY_API_KEY=vulnsy_sk_... \
  -- npx -y vulnsy-mcp

Cursor, Windsurf and others

Any client that launches stdio MCP servers works with the same command, args and env as the Claude Desktop example above.

The key sits in your assistant's configuration file in plain text. Treat that file like a password, use a key with an expiry, and revoke it from Profile → API keys if the machine is lost.

What the assistant can do

Area	Tools
Browse	`list_clients`, `list_projects`, `list_reports`, `get_report`, `list_users`
Findings	`search_findings`, `get_finding`, `create_finding`, `update_finding`, `delete_finding`
Libraries	`search_finding_templates`, `add_template_to_report`, `list_report_styles`, `get_report_style_markdown`
Compose a report	`create_report`, `update_report`, `create_tab`, `update_tab`, `link_finding_to_report`, `move_finding`, `unlink_finding`, `reorder_findings`
Evidence	`list_evidence`, `get_evidence_image` (view or save a screenshot), `upload_evidence` (local image → embed snippet), `delete_evidence`
Import	`import_scan` (Nessus, Burp, Nmap, Nuclei), `import_markdown_report`
Export	`export_report` (DOCX or CSV to a local file, Markdown inline), `list_export_templates`
Set up	`create_client`, `create_project`, `delete_report`, `delete_tab`

A typical request looks like "Open the Acme external report, add the SQL injection template from the library to the Web tab with these three URLs as affected assets, then export the DOCX." The assistant reads the report, finds the template, creates the finding with an idempotency key, and writes the DOCX to a file it tells you about.

How it behaves

Retries are safe. Every creating call carries an Idempotency-Key, so a repeated tool call cannot create a duplicate.
No silent overwrites. Edits pass the updatedAt the assistant last read; if a colleague changed the item in the meantime the API refuses with 409 and the assistant is told to re-read and retry.
Deletes are marked destructive. MCP clients that honour tool annotations ask before running delete_finding, delete_tab, delete_report or unlink_finding. Finding and tab deletes are permanent; report deletes go to the workspace trash.
Files stay local. Exports are written to a path you choose (or a temp folder) and uploads are read from your disk; scan files and images are capped at 4 MB.
Errors are explained. A 403 tells the assistant whether it is the key's scope, your role or the client allow-list (which gates edits, deletes and evidence uploads); a 429 includes how long to wait.

Self-hosted installs

Point VULNSY_URL at your install's hostname. The server needs nothing else from the internet, so it works in an air-gapped network as long as the machine running the assistant can reach the install.

MCP server

On this page