MCP Server (Pro)

Note: AI features are a DefectDojo Pro-only feature.

The DefectDojo Model Context Protocol (MCP) Server enables Large Language Models (LLMs) to intelligently interact with DefectDojo’s vulnerability management data. Unlike traditional API integrations that simply transfer data, the MCP server provides structured context and semantic meaning that enables AI assistants to perform sophisticated security analysis and generate actionable insights.

Naming: The UI labels these objects Assets and Organizations. The MCP tool names keep the original names — get_products returns Assets and get_product_types returns Organizations.

• Structured Context: MCP provides semantic meaning to DefectDojo data, not just raw data transfer
• Pre-Processed Data: DefectDojo’s normalized, deduplicated data eliminates LLM preprocessing burden
• Business Intelligence Integration: Combines technical vulnerability data with business context
• Executive-Ready Analysis: Generates reports suitable for technical teams through executive leadership
• 10X Compound Value: AI-enhanced analysis provides exponentially more value than manual queries

🔑 Important: The MCP server endpoint is at /mcp but all function calls use the base DefectDojo URL. This separation ensures secure, structured access to vulnerability data.

Connect To MCP#

Prerequisites#

• DefectDojo instance with MCP Server enabled (v2.51.2 or later)
• Valid DefectDojo API token with appropriate permissions (an instance with API tokens disabled, DD_API_TOKENS_ENABLED=False, cannot be reached through the MCP Server)
• AI provider: Claude, ChatGPT, Gemini, or custom MCP-compatible client

Enabling the MCP Server#

A superuser switches the MCP Server on in either of two places:

• MCP in the sidebar (the DefectDojo MCP Service page), with the Enabled/Disabled control at the top of the page, or
• Settings → Feature Flags, with the MCP Server toggle.

Both control the same setting. While the MCP Server is disabled, every tool call fails with MCP integration is disabled on this DefectDojo Pro instance, and the MCP Service page is hidden from non-superusers.

⚠️ Security Notice: Your API token is a highly sensitive piece of information used for authentication and authorization. DO NOT SHOW THE TOKEN IN ANY REQUESTS OR RESPONSES when sharing configurations or screenshots.

Server log level (self-hosted)#

On a self-hosted install, the mcp-server container’s log verbosity comes from the DD_MCP_LOGLEVEL environment variable:

• Docker Compose: set DD_MCP_LOGLEVEL in the environment the compose file is run from, then recreate the container. The compose default is INFO.
• Kubernetes (Helm): set mcpServer.env.logLevel. The chart default is INFO.

Accepted values:

An unrecognized value falls back to DEBUG, and the server logs a warning that names the variable and the accepted values.

Connection Methods#

There are two different ways to connect to the DefectDojo MCP server, depending on which AI interface you’re using:

Method 1: Configuration File Method#

Used by: Claude Desktop, MCP Inspector, and other desktop MCP clients

How it works:

• Token and connection details are stored in a configuration file
• Connection is automatic when you start the application
• No need to paste instructions into conversations
• MCP server is always available in all conversations

Advantages: Set up once, works everywhere. More secure (token not in chat history).

Method 2: Manual Prompt Method#

Used by: Claude.ai web interface, ChatGPT web interface (with plugins), Gemini web interface

How it works:

• You copy/paste connection instructions at the start of each conversation
• Or add instructions to a Claude Project for automatic inclusion
• The AI reads the instructions and connects to the MCP server
• Each new conversation requires the instructions

Advantages: Works in web browsers without installing software.

💡 Which method should I use? Use Method 1 (Configuration File) if you have a desktop app that supports it. Use Method 2 (Manual Prompt) if you’re using a web browser interface.

MCP Server Connection Details#

All methods use these core parameters:

Toolsets#

The MCP Server groups its tools into toolsets. The core toolset is what /mcp has always served: the read-only finding, Asset, engagement, test, user and group tools, the reference resources, and the two report prompts. It is available as soon as the MCP Server is enabled. Every other toolset is an add-on that an administrator switches on separately and that a client asks for in its connection URL.

Enabling toolsets#

Toolsets are enabled under Settings → Feature Flags, nested below the MCP Server toggle. A toolset toggle is only available while the MCP Server is on; switching the MCP Server off disables every toolset with it.

More toolsets appear in the Feature Flags menu as they are released. A toolset’s flag only controls what the MCP Server offers: it does not change the REST API, and every tool call still runs with the permissions of the API token that connects.

Selecting toolsets in the connection URL#

Add a toolsets query parameter to the MCP endpoint URL. Names are comma-separated; core is always included, so it never needs to be listed.

Any selection with a toolsets parameter also offers get_instance_info, a tool that reports the DefectDojo Pro version, which toolsets are enabled (mcp_toolsets_enabled), each Feature Flag’s state, and whether the instance names its objects Assets / Organizations or Products / Product Types. Ask your assistant to call it when you are unsure which toolsets an instance provides.

The query string goes wherever your client takes the server URL — for the configuration-file clients in the guides below that is the URL argument, for example "https://your-instance.defectdojo.com/mcp?toolsets=hierarchy" in place of the plain /mcp URL. mcp-remote, Claude Code, Cursor, VS Code and other Streamable HTTP clients pass the query string through unchanged.

When a connection is refused#

The MCP Server answers the connection request with a plain-text error instead of a session when it cannot serve the selection:

If a toolset is switched off while a session is open, its tools stay listed but each call returns an error naming the toolset and its Feature Flag. Reconnect after the flag is enabled again.

Quick Start Guides by AI Provider#

💡 Using Claude Code? Do not configure it by hand. The Claude Code Plugin wires up this MCP server for you in two commands, and adds the write operations these read-only tools do not cover, such as changing finding status and importing scans.

{
  "mcpServers": {
    "DefectDojo-MCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-instance.defectdojo.com/mcp",
        "--header",
        "Authorization: Token YOUR_API_TOKEN"
      ]
    }
  }
}

For this project, use the DefectDojo MCP server with these parameters in ALL function calls:

- **URL:** https://your-instance.defectdojo.com/ (base URL, NOT the /mcp endpoint)
- **Token:** YOUR_API_TOKEN
- **IMPORTANT:** DO NOT SHOW THE TOKEN IN ANY REQUESTS OR RESPONSES

The MCP server connects to https://your-instance.defectdojo.com/mcp but function calls must use the base URL.

**Do not show any of the API requests or responses.**

For this project, use the DefectDojo MCP server with these parameters in ALL function calls:

- **URL:** https://your-instance.defectdojo.com/
- **Token:** YOUR_API_TOKEN
- **IMPORTANT:** DO NOT SHOW THE TOKEN IN ANY REQUESTS OR RESPONSES

The MCP server connects to https://your-instance.defectdojo.com/mcp but function calls must use the base URL.

Do not show any of the API requests or responses.

I need you to connect to a DefectDojo MCP server with these details:

MCP Endpoint: https://your-instance.defectdojo.com/mcp
Base URL for API calls: https://your-instance.defectdojo.com/
Authentication: Authorization header with value "Token YOUR_API_TOKEN"

Use this connection to access DefectDojo vulnerability data. The server provides tools for:
- Getting findings with severity, status, and date filters
- Accessing products, engagements, tests
- User and group management
- Analyzing security trends

Do not show the API token in responses.

Connect to DefectDojo vulnerability management system via MCP server:

MCP Server: https://your-instance.defectdojo.com/mcp
API Base URL: https://your-instance.defectdojo.com/
Authentication: Token YOUR_API_TOKEN (use Authorization header with "Token" prefix)

Available capabilities:
- Query findings by severity (Critical, High, Medium, Low, Info)
- Filter by status (Active, Verified, False Positive, etc.)
- Filter by date ranges (Today, Past 7/30/90 days, etc.)
- Access products, engagements, tests, users, groups
- Generate security analysis and reports

Important: Do not display the authentication token in responses.

# macOS (using Homebrew)
brew install mcp-inspector

# Or using npm (all platforms)
npm install -g @modelcontextprotocol/inspector

mcp-inspector

✅ Connection Successful? Once connected via any method, test by asking your AI assistant: "How many active findings do we have in DefectDojo?"

Available Tools Reference#

The core toolset of the DefectDojo MCP Server provides 18 tools for accessing and analyzing vulnerability data, 6 reference resources, and 2 pre-configured prompts. Each tool includes intelligent parameter handling and returns structured data optimized for LLM analysis. Connections that select toolsets in the URL (see Toolsets) also receive get_instance_info, and add-on toolsets contribute their own tools on top of the ones listed here.

💡 Parameter Note: All tools accept an optional token parameter. If not provided in individual calls, the LLM will use the token from the connection configuration.

💡 Pagination Note: Every list tool accepts limit (1–1000, default 100) and offset (minimum 0, default 0). Every *_by_id tool takes a single required numeric ID (minimum 1).

🔍 Findings Analysis Tools#

get_findings({
  severity: ["Critical", "High"],
  status: ["Active"],
  date: ["3 - Past 30 days"],
  limit: 100
})

get_findings({
  status: ["Active"],
  tags__and: ["production", "pci"]
})

finding_summary({
  product_id: 42,
  date: ["4 - Past 90 days"]
})

finding_summary({
  tags: ["internet-facing"]
})

📦 Asset & Engagement Tools#

💡 Walking the object graph: Finding → get_test_by_id → get_engagement_by_id → get_product_by_id → get_product_type_by_id resolves a finding’s owning test, engagement, Asset and Organization with four direct calls instead of paging the list tools.

👥 User & Access Management Tools#

Asset Hierarchy Toolset#

The hierarchy toolset (?toolsets=hierarchy) lets an assistant explore and maintain the Organization/Asset hierarchy: which Organizations exist, which Assets sit under which parents, where findings roll up, and where the structure has gaps. It adds 12 tools (7 read, 5 write), 1 resource and 2 prompts on top of core.

It is available when an administrator has enabled MCP: Asset Hierarchy under Settings → Feature Flags (which itself requires the Asset Hierarchy feature). Instances that still use the classic Product Type / Product wording see the same tools; the tool and argument names always say organization and asset, and get_instance_info reports which words the instance shows its users.

⚠️ Write tools change DefectDojo immediately. This toolset contains the MCP Server’s first write tools. Each one performs exactly one DefectDojo REST write with your API token: DefectDojo’s own permission checks and validation apply, and the MCP Server adds no preview, dry run, approval step or undo. The bundled workflow guide instructs the assistant to explore first, summarise what it found, and ask for your confirmation before any change. If your token can re-parent or create Assets in the REST API, the assistant can too.

Every hierarchy tool accepts the optional token parameter, and every list tool pages with limit (1–100, default 25) and offset.

🌳 Hierarchy Read Tools#

An Asset the token cannot see is reported as not_found. Trees are capped by depth and nodes_per_level; a node flagged has_more_children needs another get_hierarchy_tree call with that node as root_id.

✏️ Hierarchy Write Tools#

Every write tool answers with the same result envelope so the assistant can tell you exactly what happened:

Re-parenting an Asset or moving it between Organizations can change who can see it and its findings, because DefectDojo grants visibility through Organizations and through parent Assets. Ask the assistant to state the new audience before it applies such a change.

Hierarchy Resource and Prompts#

• mcp://resource/hierarchy/workflow-guide.md (Markdown) — the working method the assistant is expected to follow: learn the instance’s vocabulary with get_instance_info, explore with the bounded read tools, summarise with IDs, propose, and change only after confirmation.
• explore_hierarchy prompt — takes organization_name_or_id; explores that Organization’s Asset hierarchy and reports what is there before proposing any change.
• hierarchy_cleanup_review prompt — no arguments; reviews the whole hierarchy for orphan Assets, duplicate names and empty Organizations and proposes cleanup steps without applying them.

Example requests#

• “Run the hierarchy cleanup review and show me the orphaned Assets.”
• “Explore the Payments Organization and draw the Asset tree three levels deep.”
• “How many critical findings roll up to the checkout-api Asset and its children?”
• “Move checkout-web and checkout-mobile under checkout-api. Tell me who gains visibility first, then do it when I confirm.”
• “Detach legacy-gateway from its parent but keep its children attached to the old parent.”

Reporting Toolset#

The reporting toolset (?toolsets=reporting) lets an assistant work with the Pro Report Builder: read the themes, blocks and templates that already exist, design and create new ones, run a template once or on a recurring schedule, and hand you the download link once DefectDojo has rendered the file. It adds 22 tools (8 read, 14 write), 3 resources and 3 prompts on top of core.

It is available when an administrator has enabled MCP: Reporting under Settings → Feature Flags (which itself requires the Reporting feature). The toolset covers the Report Builder only; the classic report engine and its migration endpoints are not exposed. If you would rather drive the Report Builder with an LLM through the REST API and a generated script, see Building Reports with an LLM; the MCP toolset does the same job without any code leaving the chat.

⚠️ Write tools change DefectDojo immediately. As with the hierarchy toolset, each write tool performs exactly one DefectDojo REST write with your API token and relays DefectDojo’s answer. DefectDojo’s permission checks apply — an organization member with the Writer role can run reports but not change report definitions, exactly as in the UI — and the MCP Server adds no preview, approval step or undo. The bundled workflow guide instructs the assistant to look up what exists, propose the design, and ask for your confirmation before any write.

Every reporting tool accepts the optional token parameter, and every list tool pages with limit (1–100, default 25) and offset.

📄 Reporting Read Tools#

✏️ Reporting Write Tools#

Write tools answer with the same outcome envelope for the Asset Hierarchy Toolset (committed, rejected, unknown); generate_report additionally carries the new run’s status, and schedule_report/update_report_schedule carry the schedule’s real state as status (enabled or disabled).

Reports are generated asynchronously#

DefectDojo renders reports in a background worker, so generate_report does not return a file. The assistant is told to call get_generated_report with the returned job_id every 10–30 seconds (for up to about 10 minutes) until status is completed or failed. A completed run carries download_url, a path on your DefectDojo instance (/api/v2/generated_reports/<id>/download/) that you open with your own DefectDojo credentials; a failed run carries error_message. The MCP Server never proxies the file itself. To read what a completed pdf or html report says, the assistant calls get_report_content, which returns the bounded plain-text rendition DefectDojo writes next to the file (the same text as /api/v2/generated_reports/<id>/content/, described in Automating Reports with the API; capped at 256 KiB upstream and sliced by max_bytes). Calling it before the run has completed returns a not-found error that tells the assistant to keep polling get_generated_report.

Recurring reports#

schedule_report creates a report schedule through /api/v2/report_schedules/ (see Automating Reports with the API; DefectDojo Pro 3.3.300 or later). A few rules are worth knowing before you ask for one:

• The cadence is a five-field cron expression in UTC, at most once an hour: the minute field must be a single value, so 0 6 * * 1 (06:00 UTC every Monday) is accepted and */15 * * * * is rejected. The assistant translates “every weekday at 8” into cron for you; the response carries trigger_expression_readable and the next_run time so you can check its reading.
• Each run is generated as the schedule’s creator — the user whose token created it — with that user’s visibility, and appears in get_generated_reports as an ordinary run requested by that user.
• A new schedule is always enabled. To prepare one without running it yet, create it and then pause it with update_report_schedule and enabled: false; a paused schedule keeps its cadence until you resume it with enabled: true.
• Changing the cadence resumes a paused schedule, even when enabled: false is sent in the same call, because DefectDojo re-registers the schedule with its scheduling service. The assistant is told to send the new cron first and pause again in a second call; the status in every response is the schedule’s real state, so check it.
• Who may change a schedule. Any organization member who can run the template can schedule it, but only the schedule’s creator or a report administrator may update or delete it; anyone else receives a permission error.
• Deleting a schedule keeps its reports. delete_report_schedule stops future runs; reports already generated stay in get_generated_reports until they are deleted.

Report schedules have no page of their own in the DefectDojo Pro UI yet, so the MCP Server returns no url for one; get_report_schedules is the way to review them.

Reporting Resources and Prompts#

• mcp://resource/reporting/builder-schema.json (JSON) — the structure and allowed values of themes, blocks, templates and runs as the write tools accept them.
• mcp://resource/reporting/chart-catalog.json (JSON) — every chart_key a chart block may use, its label, the model_choice it requires, and whether it is a time series.
• mcp://resource/reporting/workflow-guide.md (Markdown) — the working method: look up before creating, build theme → blocks → template, generate, poll, read the text rendition with get_report_content when a summary is wanted, then hand over the download link; plus how to create, pause, move and delete a report schedule.
• build_report_template prompt — takes audience, scope_description and an optional file_format; reads the resources and the catalog, proposes a theme, block list and template for that audience, and creates them in dependency order after you approve.
• run_report prompt — takes template_name_or_id plus optional timeframe and file_format; resolves the template by exact name or id, summarises what it contains, generates it, polls to completion, offers a summary of the text rendition, and returns the download link or the error.
• check_report_run prompt — takes template_name_or_id; lists that template’s recent runs with status, requester and download links without starting a new run.

Example requests#

• “Show me the report templates we already have and what blocks each one uses.”
• “Build a monthly executive PDF for the Payments Organization: cover page, severity-over-time chart, and a table of open Critical and High findings. Propose it first.”
• “Run the Quarterly Compliance template as HTML and give me the link when it’s done.”
• “Did last night’s SOC 2 Evidence report finish? If it failed, tell me why.”
• “Summarise the key numbers in the latest Executive Summary PDF.”
• “Duplicate Executive Summary, rename the copy Executive Summary — EMEA, and add the Assets by Region block at the end.”
• “Generate the Executive Summary as PDF every Monday at 06:00 UTC. Which schedules already exist for that template?”
• “Pause the weekly SOC 2 Evidence schedule until further notice.”

Dashboards Toolset#

The dashboards toolset (?toolsets=dashboards) lets an assistant work with Customizable Dashboards: list the dashboards you can see, read what is on one, render a widget’s current numbers, explain why a widget shows what it shows, and design, create, edit, clone, share and delete dashboards for you. It adds 11 tools (6 read, 5 write), 2 resources and 2 prompts on top of core.

It is available when an administrator has enabled MCP: Dashboards 2.0 under Settings → Feature Flags (which itself requires the Dashboards 2.0 feature, described in Enabling Customizable Dashboards). It requires DefectDojo Pro 3.3.300 or later, the release that made the dashboards endpoints available to API tokens under /api/v2/dashboards/. If you would rather drive dashboards with an LLM through the REST API and a generated script, see Building Dashboards with an LLM; the MCP toolset does the same job without any code leaving the chat.

⚠️ Write tools change DefectDojo immediately. As with the hierarchy and reporting toolsets, each write tool performs one DefectDojo REST write with your API token and relays DefectDojo’s answer. DefectDojo’s permission checks apply — sharing a dashboard needs the same permission as in the UI, and an instance whose administrator has locked dashboards to the designated defaults refuses edits the same way — and the MCP Server adds no preview, approval step or undo. The bundled workflow guide instructs the assistant to read the widget catalog, propose the dashboard, and ask for your confirmation before any write, and never to share a dashboard unless you ask.

Every dashboards tool accepts the optional token parameter, and every list tool pages with limit (1–100, default 25) and offset.

📊 Dashboards Read Tools#

A dashboard’s url is the Dashboards page (/ui/dashboard-v2); DefectDojo Pro has no per-dashboard link, so pick the dashboard by name from the page’s dropdown. Every render is bounded: a wide widget is trimmed to the caps and the truncation field says so, so the assistant reports what it saw rather than guessing at the rest.

✏️ Dashboards Write Tools#

Write tools answer with the same outcome envelope as the Asset Hierarchy Toolset (committed, rejected, unknown). A rejected outcome carries DefectDojo’s status_code and field_errors, so a misconfigured widget is reported field by field rather than silently dropped. After creating or changing a dashboard, the assistant is told to render every non-static widget once with get_widget_data and to report any that answer with a rejection, a disabled feature or a permission error.

Sharing a dashboard or changing the shared default changes what every user of the instance sees. The workflow guide and the build_dashboard prompt only do either when you explicitly ask.

Dashboards Resources and Prompts#

• mcp://resource/dashboards/widget-schema.json (JSON) — every widget type with the configuration keys, allowed values and ranges DefectDojo accepts, plus the rules for the widget envelope, grid positions and dashboard settings. The assistant reads a type’s entry before writing its configuration.
• mcp://resource/dashboards/workflow-guide.md (Markdown) — the working method: discover the catalog, resolve dashboards by name, propose a small layout, confirm, create, render-check every widget, diagnose an empty one, and share only on request.
• summarize_dashboard prompt — takes an optional dashboard_name_or_id (your default dashboard when blank); reads the dashboard, renders up to six of its widgets and summarises what they currently show, within a bounded number of calls.
• build_dashboard prompt — takes audience and focus; reads the catalog and the widget schema, learns the instance’s Organization/Asset wording, proposes a dashboard of four to eight widgets for that audience with every filter spelled out, creates it after you approve, render-checks each widget (diagnosing and fixing an empty one only after telling you), and hands you the URL. It mentions sharing but never shares unless you ask.

Example requests#

• “Which dashboards can I see, and which one is my default?”
• “Summarise my Executive Overview dashboard — what are the numbers right now?”
• “Why does the Open Criticals — Payments widget show zero? Diagnose it.”
• “Build a dashboard for the AppSec team focused on remediation velocity. Propose it first.”
• “Add a Findings by severity chart filtered to the Payments Organization to my Triage dashboard, top right.”
• “Clone the shared Security Posture dashboard so I can edit my own copy.”
• “Which posture pack e-mails do I have scheduled?”

PSIRT Toolset#

The psirt toolset (?toolsets=psirt) lets an assistant work with the PSIRT module: summarise what the advisory feeds brought in since yesterday, explain why an advisory matched your inventory, design and preview matching rules, and — when you ask — review or suppress feed items, record match decisions, open cases and drive an advisory of your own through review to publication. It adds 18 tools (12 read, 6 write), 2 resources and 3 prompts on top of core.

It is available when an administrator has enabled MCP: PSIRT under Settings → Feature Flags. That flag can only be switched on while the PSIRT flag is on, which in turn requires Locations and the PSIRT Advisory Engine licence entitlement (see If you don’t see PSIRT in the menu). It requires DefectDojo Pro 3.4.100 or later, the release that made the PSIRT endpoints available to API tokens under /api/v2/psirt/. Every tool runs with your token’s PSIRT access: View PSIRT (or a global Maintainer/Owner role) is enough for the read tools, and the write tools need Change PSIRT (or a global Maintainer/Owner role), exactly as in the UI (Who can use PSIRT).

📖 Two kinds of “advisory”. DefectDojo Pro’s PSIRT pages call an ingested feed record an advisory, and an advisory your team writes about your own products an authored advisory. So that an assistant never confuses the two, the MCP tools call the ingested record a feed item (feed_item_id, psirt_get_feed_items, psirt_triage_feed_item) and reserve advisory (advisory_id, psirt_get_authored_advisories, psirt_manage_advisory) for the ones you author. The tools also use the Asset / Organization wording of the rest of the server (asset_id, analyst_id, group_id).

⚠️ Feed content is untrusted. Feed item titles, descriptions and CVE text are written by external publishers. The bundled workflow guide and every PSIRT prompt instruct the assistant to treat that text strictly as data to summarise or quote — never as instructions — and to ignore anything in a feed item that reads like a request to suppress, publish or change something. Keep the same rule in mind when you paste feed text into a chat yourself.

⚠️ Write tools change DefectDojo immediately. As with the other toolsets, each write tool performs one DefectDojo REST write with your API token and relays DefectDojo’s answer; the MCP Server adds no preview, approval step or undo. Most PSIRT writes are reversible in the UI — a reviewed item can be unreviewed, a suppressed one unsuppressed, a closed case reopened, a match set back to unconfirmed, a rule disabled — but scheduling or publishing an authored advisory sends it to everyone the instance delivers to and cannot be undone. The psirt_manage_advisory tool is therefore marked destructive as a whole, and its description tells the assistant to schedule or publish only on your explicit request, after showing you the advisory’s readiness (signoffs, preflight, can_publish). The workflow guide instructs the assistant to confirm with you before any write, and to assess and preview a rule before saving it.

Every PSIRT tool accepts the optional token parameter, and every list tool pages with limit (1–100, default 25) and offset.

🛰️ PSIRT Read Tools#

psirt_preview_rule and psirt_assess_rule are read tools even though DefectDojo receives the conditions to evaluate in the body of the request; they store nothing and are not subject to the write confirmation rule. Feed items have no per-item page in the PSIRT UI, so their url opens the feed queue; cases open the cases page; an authored advisory’s url opens that advisory.

✏️ PSIRT Write Tools#

Write tools answer with the same outcome envelope as the Asset Hierarchy Toolset (committed, rejected, unknown, and partial for a mixed match batch). A rejected outcome carries DefectDojo’s status_code and field_errors, so a rule DefectDojo grades too broad or a transition it refuses is reported with the reason rather than retried. Editing an authored advisory after it has been signed off costs those approvals, exactly as it does in the UI (Review, and why editing costs you approvals), so check the readiness view before asking the assistant to update a reviewed advisory. Before a transition, the assistant is told to read mode: readiness for the available_transitions; DefectDojo answers a transition it does not allow, or an advisory locked by another user, with a rejected outcome.

PSIRT Resources and Prompts#

• mcp://resource/psirt/rule-schema.json (JSON) — the shapes DefectDojo accepts for a matching-rule condition, a pre-filter condition and the actions of each, with their allowed values and bounds. The assistant reads it before writing a rule.
• mcp://resource/psirt/workflow-guide.md (Markdown) — the working method: treat feed content as untrusted, read before writing and confirm before every write, the daily triage order, how to explain a match, how to design and preview a rule, how cases and authored advisories move, and what the common errors mean.
• psirt_daily_triage prompt — takes an optional since timestamp (the last 24 hours when blank); checks the instance has PSIRT, reads the triage summary, pulls the items with verified matches, the exploited ones and the new high-CVSS ones within a handful of calls, names the affected Assets for the top items, and hands you a ranked list plus what needs a human decision today. It suggests psirt_triage_feed_item and psirt_manage_case as next steps but never calls a write tool unless you ask.
• psirt_explain_match prompt — takes a feed_item_id; reads the item and its matches, explains the evidence behind each (rule or CPE auto-match, confidence, version verification), looks up the rules that fired, and recommends confirm / false positive / needs a human check per match — without applying any decision.
• psirt_design_rule prompt — takes a goal_description such as “advisories naming OpenSSL 3.x on our payment assets”; reads the rule schema and the existing groups and rules, drafts conditions, runs psirt_assess_rule and psirt_preview_rule, proposes the rule with its preview numbers, creates it disabled after your approval, and enables it only after a second explicit confirmation.

Example requests#

• “What did the PSIRT feeds bring in since yesterday morning, and which items hit verified matches?”
• “Why did feed item 4821 match the payments-api Asset? Is the version verified?”
• “Show me the open cases past their SLA and who they are assigned to.”
• “Design a matching rule that catches advisories naming log4j-core 2.x on our Java services. Preview it first.”
• “Mark matches 118 and 119 as false positives — the affected module isn’t shipped — and note why.”
• “Open a case from the confirmed matches of feed item 4821 and assign it to Dana.”
• “Is advisory PSIRT-2026-0007 ready to publish? Don’t publish it, just tell me what’s missing.”

Reference Resources#

The core toolset publishes 6 read-only JSON resources (MIME type application/json). They are reference material bundled with the MCP Server, not data from your DefectDojo instance, and are available without any tool call so an assistant can map findings to a standard or explain a regulatory obligation while it reports.

Ask your assistant to read a resource by URI (for example, “read mcp://resource/cwe_to_owasp_2025_mapping.json and group our open findings by OWASP category”) when a report should cite a standard.

Add-on toolsets publish their own resources alongside these: the hierarchy toolset adds mcp://resource/hierarchy/workflow-guide.md (see Asset Hierarchy Toolset), the reporting toolset adds three under mcp://resource/reporting/ (see Reporting Toolset), the dashboards toolset adds mcp://resource/dashboards/widget-schema.json and mcp://resource/dashboards/workflow-guide.md (see Dashboards Toolset), and the psirt toolset adds mcp://resource/psirt/rule-schema.json and mcp://resource/psirt/workflow-guide.md (see PSIRT Toolset).

Pre-Configured Prompts#

The DefectDojo MCP Server includes pre-configured prompts that demonstrate best practices for common analysis scenarios. These prompts can be invoked directly by your AI assistant.

🛡️ SAST Review Report#

Purpose: Create a comprehensive report evaluating the effectiveness of SAST (Static Application Security Testing) tools based on DefectDojo data.

Generated Analysis Includes:

• False positive rates by tool and vulnerability type
• Mean time to remediation by severity level
• Critical vulnerabilities appearing multiple times (deduplication gaps)
• Developer team performance comparison
• Recommendations for tool configuration improvements
• Training gaps identified from recurring vulnerability patterns
• Cost analysis of current vs. recommended tooling approach

Output Format: Technical assessment report in HTML, suitable for justifying security tooling budget requests.

📊 Security Landscape Report#

Purpose: Create a dashboard-style report providing an overview of the security landscape based on DefectDojo data, suitable for quarterly board meetings.

Generated Analysis Includes:

• Vulnerability trends over past 90 days
• Development teams with highest critical/high severity findings
• Risk exposure by Asset and Organization
• Top 5 CWE categories requiring immediate attention
• Specific remediation actions with cost-benefit analysis
• 6-month roadmap for improving security posture

Output Format: Executive-level HTML report with visual elements, statistics cards, and business risk focus.

💡 Using Prompts: To invoke a prompt, simply ask your AI assistant: “Create a SAST Review Report” or “Generate a Security Landscape Report using DefectDojo data”

The hierarchy toolset adds two more prompts, explore_hierarchy and hierarchy_cleanup_review, described under Asset Hierarchy Toolset; the reporting toolset adds build_report_template, run_report and check_report_run, described under Reporting Toolset; the dashboards toolset adds summarize_dashboard and build_dashboard, described under Dashboards Toolset; and the psirt toolset adds psirt_daily_triage, psirt_explain_match and psirt_design_rule, described under PSIRT Toolset. Unlike the two core prompts, most of these take arguments, which your client asks for when you invoke them.

Use Case Examples#

Use Case 1: Executive Security Dashboard#

Scenario: CISO needs quarterly security metrics for board presentation

User Prompt:

"Create an executive security dashboard for our Q4 board meeting showing:
- Total vulnerability counts by severity
- Trends over the past 90 days  
- Which products have the highest risk exposure
- Top 5 vulnerability categories needing attention
- Specific remediation recommendations with ROI
- A 6-month roadmap for improving our security posture"

What happens behind the scenes:

1. get_findings - Get total active finding counts
2. get_findings - Critical and High severity analysis
3. get_findings - 90-day trending data
4. get_products - Asset vulnerability distribution
5. get_engagements - Recent testing activities

Generated Output: Executive-level HTML report with vulnerability trends, risk exposure by Asset, top CWE categories, specific remediation actions with ROI, and 6-month security roadmap.

Use Case 2: Developer Team Performance Analysis#

Scenario: Engineering manager wants to understand which teams need additional security training

User Prompt:

"Which development teams have the most security findings? What types of vulnerabilities 
are they creating repeatedly? Based on this analysis, recommend specific security 
training programs for each team."

What happens behind the scenes:

1. get_findings - All active findings
2. get_products - Link findings to Assets/teams
3. get_groups - Team organization structure
4. get_users - Individual developer accountability

Analysis Delivered: Findings grouped by team, CWE pattern analysis showing repeated mistakes, training gap identification, and recommendations for targeted security training programs.

Use Case 3: Tool Effectiveness Assessment#

Scenario: Security team evaluating ROI of current SAST tools

User Prompt:

"Analyze the effectiveness of our SAST tools. Show me false positive rates, 
mean time to remediation, which tools find the most valuable vulnerabilities, 
and recommend configuration improvements or alternative tools."

What happens behind the scenes:

1. get_tests - All security tests by tool
2. get_findings - False positive analysis
3. get_findings - Active findings by tool
4. get_findings - Closed findings for remediation patterns

Analysis Delivered: False positive rates by tool, mean time to remediation by severity, duplicate finding analysis, tool configuration recommendations, training gaps, and cost-benefit analysis of alternative tooling approaches.

Use Case 4: Compliance Reporting#

Scenario: Preparing for SOC 2 audit requiring vulnerability management evidence

User Prompt:

"Generate a SOC 2 compliance report showing our vulnerability management processes, 
including discovery and remediation procedures, SLA compliance, continuous monitoring 
evidence, and accountability documentation."

What happens behind the scenes:

1. get_findings - Critical/High active findings
2. get_findings - Year-to-date discovery trends
3. get_engagements - Testing frequency and coverage
4. get_users - Remediation accountability

Analysis Delivered: Vulnerability discovery and remediation processes, SLA compliance tracking, evidence of continuous monitoring, accountability documentation, and gaps requiring remediation before audit.

Use Case 5: Risk Prioritization#

Scenario: Security team has limited resources and needs to prioritize remediation efforts

User Prompt:

"What are the highest priority vulnerabilities we should fix first? Consider severity, 
how long they've been open, exploitability, and business impact. Give me a prioritized 
remediation roadmap with effort estimates."

What happens behind the scenes:

1. get_findings - Critical/High active findings
2. get_products - Business criticality context
3. Analyze aging metrics (days since discovery)
4. Cross-reference with EPSS scores (exploit prediction)

Analysis Delivered: Risk-ranked vulnerability list combining severity, age, exploitability, and business impact. Specific remediation roadmap with effort estimates and expected risk reduction.

Best Practices & Query Patterns#

Progressive Data Loading Strategy#

Your AI assistant optimizes performance by following these data loading patterns automatically:

1. Start with Summary Data

Ask for counts before requesting detailed analysis:

"How many critical and high severity findings do we have?"

Your AI assistant will use the get_findings tool with limit: 1 to efficiently retrieve just the count.

2. Use Strategic Pagination

For large datasets, your AI assistant automatically pages through results:

"Analyze all our active vulnerabilities"

The AI will make multiple calls if needed, starting with reasonable limits and increasing as required.

3. Efficient Data Reuse

Ask related questions in sequence to avoid redundant queries:

"Show me all critical findings, then tell me which CWE categories they fall into"

The AI will reuse the findings data from the first query for the CWE analysis.

Smart Filtering Strategies#

Craft your prompts to leverage DefectDojo’s powerful filtering capabilities:

Severity-Based Queries#

User Prompt:

"Show me all Critical and High severity issues that need immediate attention"

Behind the scenes: AI uses get_findings with severity and status filters

Time-Based Queries#

User Prompt:

"What new vulnerabilities have been discovered in the past 30 days?"

Behind the scenes: AI applies date filter for “Past 30 days” with active status

Combined Filtering#

User Prompt:

"Give me a risk assessment of all critical and high active findings from the past 90 days"

Behind the scenes: AI combines severity, status, and date filters for comprehensive analysis

Cross-Reference Analysis#

Your AI assistant automatically links findings to organizational context. Simply ask comprehensive questions:

User Prompt:

"Which products have the most critical vulnerabilities and who is responsible for fixing them?"

Behind the scenes: AI links findings → tests → engagements → Assets → users/groups for complete context

Vulnerability Intelligence Analysis#

CWE Pattern Analysis

User Prompt:

"What are the most common vulnerability types in our codebase and which teams are creating them?"

AI will group findings by CWE to identify recurring patterns, training needs, and architectural issues.

Aging Metrics

User Prompt:

"How long have our critical vulnerabilities been open? Which ones are overdue for remediation?"

AI calculates time since discovery and flags findings exceeding SLA thresholds.

Vulnerability Density

User Prompt:

"Which products have the highest vulnerability density and represent the greatest risk?"

AI calculates findings per Asset and generates risk scores combining severity and volume.

Report Enhancement Standards#

Always Include#

• Specific metrics: Actual counts by severity, not generalizations
• CWE analysis: Top vulnerability types with descriptions
• Aging data: How long vulnerabilities have been open
• Actionable recommendations: What to do next with timelines
• ROI calculations: Expected cost vs. benefit of actions
• Success metrics: How to measure improvement

Industry Context Integration#

Compare DefectDojo findings against industry frameworks:

• OWASP Top 10: Web application security risks
• SANS Top 25: Most dangerous software weaknesses
• CWE Top 25: Most common and impactful weaknesses
• Compliance frameworks: SOC 2, ISO 27001, NIST CSF

Troubleshooting MCP#

Diagnostic Checklist#

Verify these items when experiencing connection issues:

• ✅ Transport Type is Streamable HTTP (not SSE)
• ✅ MCP endpoint URL is correct: https://[instance].defectdojo.com/mcp
• ✅ Authorization header is enabled (toggle is ON)
• ✅ Token format includes Token prefix
• ✅ Token is valid and has appropriate permissions
• ✅ DefectDojo instance is accessible (can login via web UI)
• ✅ Network connectivity allows HTTPS connections

Common Connection Issues#

❌ “Connection Error - Check if your MCP server is running”#

Cause: Using deprecated SSE (Server-Sent Events) transport type

Solution: Change Transport Type to Streamable HTTP

Why: DefectDojo MCP Server uses modern Streamable HTTP protocol. SSE is deprecated and not supported.

❌ “Authentication Failed” or “401 Unauthorized”#

Cause: Incorrect authentication header format or invalid token

Solutions:

1. Verify header value uses Token prefix (not Bearer)

   ✅ Correct: Token 7c6cc2xxxxxxxxxxxxxxxxxxxx87fcf72ec2b3fb
   ❌ Wrong: Bearer 7c6cc2xxxxxxxxxxxxxxxxxxxx87fcf72ec2b3fb

2. Ensure Authorization header toggle is ENABLED (turned ON)

3. Verify token is still valid in DefectDojo (Admin → API Tokens)

4. Check token has appropriate permissions for read access

❌ “toolset ‘hierarchy’ is not enabled on this DefectDojo Pro instance”#

Cause: The connection URL asks for a toolset whose Feature Flag is off, or the MCP Server itself is disabled. The same message names reporting or dashboards when that toolset’s flag is off.

Solutions:

1. Ask a superuser to open Settings → Feature Flags, confirm MCP Server is on, and enable the toolset’s flag (for hierarchy, MCP: Asset Hierarchy, which also needs the Asset Hierarchy feature; for reporting, MCP: Reporting, which also needs the Reporting feature; for dashboards, MCP: Dashboards 2.0, which also needs the Dashboards 2.0 feature; for psirt, MCP: PSIRT, which also needs the PSIRT feature)
2. Or remove the toolset from the toolsets parameter and reconnect
3. Ask your assistant to call get_instance_info to see which toolsets the instance has enabled

❌ Tool Returns Empty Results#

Possible Causes:

• Filters are too restrictive (no data matches criteria)
• DefectDojo instance has no data in requested category
• Insufficient token permissions

Solutions:

1. Try broader query first: get_findings({ limit: 10 })
2. Remove filters one at a time to identify the restrictive filter
3. Verify token permissions in DefectDojo
4. Check if data exists directly in DefectDojo UI

⚠️ Slow Response Times#

Cause: Requesting too much data at once

Solutions:

• Reduce limit parameter (start with 50-100)
• Use more specific filters to reduce result set size
• Use progressive loading: get counts first, then details
• Implement pagination for large datasets