MCP Server | DefectDojo Documentation

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.

🔑 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

⚠️ 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.

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:

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:

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:

Parameter Value Notes
Transport Type Streamable HTTP ⚠️ SSE (Server-Sent Events) is deprecated
MCP Endpoint URL https://[YOUR-INSTANCE].defectdojo.com/mcp Used for establishing MCP connection
Base URL for Functions https://[YOUR-INSTANCE].defectdojo.com/ Used in all tool function calls
Authentication Authorization: Token [YOUR_API_TOKEN] ⚠️ Use “Token” prefix, not “Bearer”

Quick Start Guides by AI Provider

🖥️ Claude Desktop (Method 1: Configuration File)

Step 1: Locate your configuration file

Step 2: Edit the configuration file

Add or update the mcpServers section with your DefectDojo instance details:

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

⚠️ Critical: The --header flag with authentication is required. Replace YOUR_API_TOKEN with your actual DefectDojo API token.

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop for the changes to take effect.

Step 4: Verify Connection

Start a new conversation and ask: "Can you connect to DefectDojo?"

If successful, Claude will confirm it has access to the DefectDojo MCP server tools.

✅ Done! The DefectDojo MCP server is now available in all conversations. No need to paste instructions.

🌐 Claude.ai Web Interface (Method 2: Manual Prompt)

The Claude.ai web interface doesn’t support configuration files. You’ll need to provide connection instructions in each conversation or use a Claude Project.

Option A: Paste Instructions Per Conversation

Step 1: Copy the instructions below

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.**

Step 2: Start a new conversation

Paste the instructions at the beginning of your conversation, then ask your security questions.

Step 3: Repeat for each new conversation

These instructions must be included at the start of each new conversation.

Option B: Use a Claude Project (Recommended)

Step 1: Create a Claude Project

Step 2: Add Custom Instructions to the Project

In Project Settings → Custom Instructions, paste:

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.

Step 3: Use the Project for all DefectDojo conversations

All conversations within this project will automatically have access to DefectDojo MCP server.

✅ Done! When working in this Project, Claude automatically has DefectDojo MCP access.

💬 ChatGPT (Method 2: Manual Prompt)

⚠️ Note: ChatGPT’s MCP support is limited compared to Claude. Native MCP integration may require ChatGPT Plus or Enterprise and specific plugin configurations.

Step 1: Check MCP Plugin Availability

In ChatGPT, check if MCP or API connector plugins are available in your plugin store. MCP support varies by subscription tier.

Step 2: Copy connection instructions

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.

Step 3: Paste at the start of each conversation

Include these instructions when starting a new conversation about DefectDojo security analysis.

Alternative: Use Custom GPT

If you have ChatGPT Plus, create a Custom GPT with DefectDojo connection details in its instructions for reusable access.

💎 Google Gemini (Method 2: Manual Prompt)

⚠️ Note: Gemini’s MCP support is evolving. Native integration may be limited. Consider using Gemini API with MCP client libraries for full functionality.

Step 1: Copy connection instructions

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.

Step 2: Start conversation with instructions

Begin each new Gemini conversation with these instructions when working with DefectDojo data.

For Advanced Users:

Consider using the Gemini API with MCP client libraries (Python, JavaScript) for programmatic access with full MCP protocol support.

🔍 MCP Inspector (Testing & Validation)

Use Case: Test your DefectDojo MCP connection, explore available tools, and validate configuration before using with AI assistants.

Step 1: Install MCP Inspector

# macOS (using Homebrew)
brew install mcp-inspector

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

Step 2: Run MCP Inspector

mcp-inspector

This will start a local web server (usually at http://localhost:6274)

Step 3: Configure connection in the web interface

Step 4: Click “Connect”

Once connected, you can explore:

✅ Perfect for: Verifying your configuration works before setting up AI assistants, exploring tool capabilities, and troubleshooting connection issues.

Available Tools Reference

The DefectDojo MCP Server provides 12 tools for accessing and analyzing vulnerability data. Each tool includes intelligent parameter handling and returns structured data optimized for LLM analysis.

🔍 Findings Analysis Tools

get_findings

Description: Retrieve findings from DefectDojo with sophisticated filtering capabilities. This is the most powerful and frequently used tool for vulnerability analysis.

Parameters:

severity (Optional)

status (Optional)

date (Optional)

limit (Optional)

offset (Optional)

💡 Best Practice: For risk assessment queries, always use status: ["Active"] to focus on current, unresolved vulnerabilities rather than historical data.

Example Query:

User asks: “Show me all Critical and High severity active findings from the past 30 days”

LLM calls:

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

get_finding_by_id

Description: Retrieve detailed information about a specific finding using its unique identifier.

Parameters:

finding_id (Required)

Example Query:

User asks: “Get details for finding #1234”

LLM calls:get_finding_by_id({ finding_id: 1234 })

📦 Product & Engagement Tools

get_products

Description: Retrieve all products from DefectDojo. Products represent applications, services, or systems being tested.

Parameters:

limit (Optional)

offset (Optional)

get_product_types

Description: Retrieve product type categories from DefectDojo. Product types help organize products into logical groupings.

Parameters: Same as get_products

get_engagements

Description: Retrieve security testing engagements. Engagements represent specific testing activities or time periods for a product.

Parameters: Same as get_products

get_tests

Description: Retrieve security tests from DefectDojo. Tests contain scan results from specific security tools or manual testing.

Parameters: Same as get_products

👥 User & Access Management Tools

get_users

Description: Retrieve all users from DefectDojo for stakeholder analysis and accountability mapping.

Parameters:

limit (Optional)

offset (Optional)

get_user_by_id

Description: Retrieve detailed information about a specific user.

Parameters:

user_id (Required)

get_groups

Description: Retrieve user groups for organizational structure analysis and permission mapping.

Parameters: Same as get_users

get_group_by_id

Description: Retrieve detailed information about a specific group.

Parameters:

group_id (Required)

get_dojo_group_members

Description: Retrieve all members of a specific group for team analysis.

Parameters:

group_id (Required)

limit (Optional)

offset (Optional)

get_roles

Description: Retrieve role definitions from DefectDojo for understanding permission structures.

Parameters: Same as get_users

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:

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:

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”

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 - Product vulnerability distribution
  5. get_engagements - Recent testing activities

Generated Output: Executive-level HTML report with vulnerability trends, risk exposure by product, 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 products/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.