MCP Server

Vulnotes includes a built-in MCP (Model Context Protocol) server that exposes your pentest reports, findings, templates, and more to AI assistants like Claude.

The MCP server is hosted alongside your Vulnotes instance at /mcp, no additional installation required.

Generating an API Key

1. Log in to Vulnotes as an administrator
2. Go to Settings > API & MCP
3. Click Create API Key
4. Give it a descriptive name (e.g., "Claude MCP")
5. Copy the generated key

Setup with Claude Code

Run the following command to add the Vulnotes MCP server to Claude Code:

claude mcp add --transport http vulnotes https://your-instance.vulnotes.app/mcp \
--header "Authorization: Bearer vuln_sk_your_api_key_here"

Replace your-instance.vulnotes.app with your actual Vulnotes domain and vuln_sk_your_api_key_here with your API key.

Available Tools

Reports

Tool	Description
list_reports	List all reports with optional filtering by status or search
get_report	Get detailed report including findings and content
create_report	Create a new report from a template with scope entries
update_report	Update report metadata (title, status, dates, scope)
update_report_content	Update a specific content section (e.g., executive summary)
delete_report	Permanently delete a report
export_report_json	Export a report as JSON
export_report_pdf	Export a report as PDF (server-side rendered)

Findings

Tool	Description
list_findings	List all findings in a report (large HTML truncated)
get_finding	Get a single finding with full content (no truncation)
get_finding_fields	Get expected fields from the vulnerability template -call this before add_finding
add_finding	Add a new vulnerability finding (fields are validated against the template)
update_finding	Update an existing finding (deep merge, preserves other languages)
delete_finding	Remove a finding from a report
reorder_findings	Change the order of findings in a report

TIP

Findings have dynamic fields defined by the vulnerability template. Always call get_finding_fields first to understand what fields are expected, their types, and which are required. Field IDs and value types are strictly validated.

Templates & Companies

Tool	Description
list_templates	List available report templates
get_template	Get template details including fields
list_companies	List all companies/clients
get_company	Get company details
create_company	Create a new company with contacts
update_company	Update company name or contacts
delete_company	Delete a company

Vulnerability Library

Tool	Description
search_vulnerabilities	Search the vulnerability library
get_vulnerability	Get vulnerability details
create_vulnerability	Create a new vulnerability in the library
update_vulnerability	Update an existing vulnerability
delete_vulnerability	Delete a vulnerability from the library

Notes

Tool	Description
list_notes	List all notes for a report
create_note	Create a markdown note with tags and pin support
get_note	Get a specific note
update_note	Update a note
delete_note	Delete a note
toggle_note_pin	Pin or unpin a note

Images & Attachments

Tool	Description
upload_image	Upload an image for use in richtext fields
upload_attachment	Upload a file attachment (PDF, evidence, etc.)
list_attachments	List all attachments for a report
delete_attachment	Delete an attachment

Content Sections

Tool	Description
list_content_sections	List template-defined sections (executive summary, methodology, etc.)
get_content_section	Get a specific content section

Workflow Example

A typical workflow for creating a report with findings:

1. List templates -list_templates to see available templates (ensure it has a vulnerability template linked)
2. Create report -create_report with the chosen template ID, scope entries, and dates
3. Get finding fields -get_finding_fields to understand what the vulnerability template expects
4. Add findings -add_finding with the proper field IDs and values (validated against the template)
5. Upload images -upload_image to get image paths, then embed in richtext with <img src="path" />
6. Write sections -update_report_content to fill in executive summary, methodology, etc.
7. Export -export_report_pdf to generate the final PDF

INFO

Templates must have a linked vulnerability template to support findings. Templates without one are for content-only reports.

Field Types

When adding findings, field values depend on their type:

Type	Format	Example
richtext	HTML string	"<p>A SQL injection was found...</p>"
text	Plain string	"Simple text"
cvss	Object with vector and score	{"vector": "CVSS:3.1/AV:N/AC:L/...", "score": 9.8}
tags	String array	["sql-injection", "owasp-top-10"]
dropdown	One of the allowed options	"High"
number	Numeric value	42
checkbox	Boolean	true
date	ISO date string	"2024-01-15"
customscore	Score object	{"score": 8.5, "criteriaValues": {...}}

WARNING

Field IDs and value types are validated. Unknown field IDs, wrong types, or invalid dropdown values will be rejected with an explicit error. CVSS vectors are validated for the correct version prefix (3.1 vs 4.0).

Scope Entries

When creating or updating a report, you can define structured scope entries:

{
  "scopeDescription": "External penetration test",
  "scopeEntries": [
    { "type": "ip", "value": "192.168.1.0/24" },
    { "type": "url", "value": "https://app.example.com" },
    { "type": "domain", "value": "example.com" }
  ]
}

Report Status Values

Valid status values for update_report:

Status	Description
draft	Report is being written
waiting-for-review	Submitted for review
under-review	Currently being reviewed
completed	Finalized report

Example Prompts

Once configured, you can ask Claude:

• "List all my penetration testing reports"
• "Show me the findings for report XYZ"
• "Using this information from my nmap scan create an informative vulnerability on report X"
• "Create a new pentest report for Acme Corp using the Standard template"
• "What fields do I need for findings in this report?"
• "Add an SQL Injection finding to the Acme Corp report with a CVSS score of 9.8"
• "Update the executive summary to add the customer name for the latest report"
• "Search for XSS vulnerabilities in the library"
• "Upload this screenshot and add it to the finding description"
• "Reorder the findings by severity, critical first"
• "Create a company called TechStart with contact John Doe"
• "Export the report as PDF"

Troubleshooting

Connection refused

1. Verify your Vulnotes instance is running and accessible
2. Check that the URL doesn't have a trailing slash
3. Ensure your network/firewall allows the connection

Permission denied

Your API key may not have sufficient permissions. Ensure the user who created the key has the necessary role permissions in Vulnotes.

Token expired or invalid

API keys can be deactivated by an administrator. Check that your key is still active in Settings > API & MCP.

Field validation errors

When adding or updating findings, you may get validation errors like:

• Unknown field - The field ID doesn't match the vulnerability template. Call get_finding_fields to see valid IDs.
• Wrong type - The value type doesn't match (e.g., passing a number where a string is expected).
• Missing required field - A required field was not provided when creating a finding.
• Invalid dropdown value - The value is not in the allowed options list.