MCP Server

Overview

The MCP server exposes DFIRe's case management, evidence tracking, IOC, and incident response functionality as structured tools that AI agents can call. Administrative functions such as user management, access control, and file attachment handling are not available through MCP. The server implements the Streamable HTTP transport over JSON-RPC 2.0 with no external dependencies beyond the DFIRe backend itself.

Key design principles:

• Full RBAC enforcement: Every tool call runs with the authenticated user's permissions. Case team membership, role-based access, and write protection rules apply exactly as they do in the web interface.
• Activity-based tools: Tools are designed around activities rather than atomic CRUD operations, keeping the total tool count optimized for agent performance.
• Audit trail: All actions performed via MCP are logged in the audit system with the API key prefix and an mcp: marker, distinguishing agent actions from direct API or UI usage.
• No external dependencies: The MCP server is built into DFIRe. No sidecar services, proxies, or additional infrastructure are required.

Prerequisites

1. Enable the MCP server

   Go to Settings > Integrations > MCP Server and toggle the server on. This requires superuser access.

2. Create an API key

   The MCP server authenticates exclusively via DFIRe API keys. Create one from the user menu > API Keys (see API Access for details). The key must belong to a user with appropriate group memberships and case team assignments for the work the agent will perform.

3. Configure your MCP client

   Add the DFIRe MCP server to your client's configuration using the endpoint URL and API key. See Client Configuration below.

Client Configuration

The MCP endpoint is available at /mcp/ on your DFIRe instance. Add it to your MCP client's configuration file:

{
    "mcpServers": {
        "dfire": {
            "serverUrl": "https://your-dfire-instance.com/mcp/",
            "headers": {
                "Authorization": "Bearer dfire_ak_your_api_token_goes_here",
                "Content-Type": "application/json"
            }
        }
    }
}

Replace the URL with your DFIRe instance address and the token with a valid API key. The configuration format above is compatible with Claude Code, Google Antigravity, and other MCP clients that support the Streamable HTTP transport with header-based authentication.

Tool Groups

DFIRe exposes 48 tools organized into 9 groups. Each group can be individually enabled or disabled in the MCP settings. Tools marked as destructive include a destructiveHint annotation that prompts MCP clients to confirm before executing.

Group	Tools	Description
Cases	8	Create, update, close/reopen, escalate cases, assign teams, dashboard stats, full case data dump
Items	5	Create and manage evidence items with status tracking, flags, and parent-child hierarchy
Notes	1	Add, list, and delete notes on cases or evidence items
Actions	7	Manage incident response actions, assignments, phase transitions, and workflow decision trees
Indicators	12	IOC registry management, enrichment, lifecycle (publish/revoke), correlation, and text extraction
Timeline	3	Timeline events and incident phase changes
Timers	2	Compliance timer lifecycle (start, complete, reset, delete)
Reports	4	Investigation reports with QA workflow and CAN (Conditions, Actions, Needs) status reports
Search	6	Global search, reference data lookups, user information, and legal entity management

Consolidated Tool Design

Many tools consolidate multiple related operations into a single tool using a discriminator parameter. For example, manage_notes handles adding, listing, and deleting notes through an action parameter rather than requiring three separate tools. This keeps the total tool count within the recommended range for optimal agent performance while preserving full functionality.

Reference Data Lookup

The get_reference_data tool provides a single entry point for discovering all configurable entities in the system. Agents use it to look up IDs before performing operations:

• Case types — available case type IDs and schemas
• Item types — evidence item type IDs and schemas
• Investigation steps — evidence status progression steps
• Item flags — flags that can be toggled on evidence items
• Incident phases — configured incident response phases
• Compliance timers — timer definitions with frameworks and durations
• Users — user accounts (filterable by group and active status)
• Groups — permission groups
• Legal entities — persons, organizations, and other entities
• Projects — case grouping projects

Resources

The MCP server provides contextual documentation as resources that agents can read to understand DFIRe's data model and workflows. Resources are served via the standard MCP resources/list and resources/read methods.

Static Documentation Resources

Resource URI	Description
dfire://docs/case-workflow	Case lifecycle, statuses, modes, write protection, escalation, and team roles
dfire://docs/ioc-management	IOC types, classifications, TLP levels, enrichment, lifecycle, and publication rules
dfire://docs/incident-phases	NIST-based incident response phases, transitions, and timeline integration
dfire://docs/actions-workflows	Action management, workflow decision trees, and resolution process
dfire://docs/compliance-timers	Compliance timer lifecycle, breach tracking, and definitions
dfire://docs/reports	Investigation reports (QA workflow, versioning) and CAN reports

Dynamic Configuration Resources

Resource URI	Description
dfire://config/case-types	Currently configured case types with schemas and action templates
dfire://config/item-types	Currently configured item types with schemas

Prompt Templates

DFIRe provides pre-built prompt templates that MCP clients can use as starting points for common incident response workflows. Prompts are served via the standard MCP prompts/list and prompts/get methods.

Prompt	Arguments	Description
incident-response	incident_description (required), severity	Guided workflow for creating and managing a security incident from detection through response phases
ioc-triage	ioc_text (required), case_id	Extract IOCs from text, check the registry, create indicators, classify, enrich, and publish
case-handoff	case_id (required)	Prepare a comprehensive case summary for handoff to another analyst

Security

Authentication

The MCP endpoint accepts only API key authentication (Authorization: Bearer dfire_ak_...). Session-based authentication (browser cookies) is not supported because MCP clients are external processes. All brute-force protections that apply to API key authentication also apply to MCP requests.

Permission Enforcement

Every tool call enforces the full DFIRe permission model:

• Capability checks: The user must have the required Django permission (e.g., core.add_case) via group membership
• Case team checks: Case-scoped tools verify the user is a lead investigator, investigator, or viewer on the case
• Write protection: Closed and archived cases enforce the same write restrictions as the web interface
• Viewer restrictions: Users with viewer-only access on a case cannot perform write operations

Audit Trail

All MCP tool calls are logged in the audit system with two distinguishing markers:

• The API key prefix (e.g., dfire_ak_a1b2...) identifies which key was used
• An mcp: prefix on the auth method distinguishes MCP-originated actions from direct REST API calls

This allows administrators to filter audit logs specifically for MCP activity and trace actions back to the agent and API key used.

Destructive Operations

Tools that delete data or change case status are annotated with destructiveHint: true in the MCP tool schema. Well-behaved MCP clients will prompt the user for confirmation before executing these tools. Destructive tools include: closing/reopening cases, deleting evidence items, deleting notes, deleting actions, deleting timeline events, managing indicator lifecycle (publish/revoke), and deleting indicators.

Configuration

MCP server settings are managed in Settings > Integrations > MCP Server (requires superuser access).

Setting	Description
Enable MCP Server	Global toggle. When disabled, the /mcp/ endpoint returns an error for all requests.
Tool Groups	Individual toggles for each of the 9 tool groups. Disabled groups are hidden from tools/list and their tools reject calls. All groups are enabled by default.

The settings page also displays the endpoint URL for easy copying and provides connection instructions.

Protocol Details

The MCP server implements the following protocol methods:

Method	Description
initialize	Returns server capabilities (tools, resources, prompts)
ping	Health check
tools/list	Lists available tools filtered by enabled groups
tools/call	Executes a tool with the provided arguments
resources/list	Lists available documentation and configuration resources
resources/read	Reads a specific resource by URI
prompts/list	Lists available prompt templates
prompts/get	Returns a prompt template with resolved arguments

The transport is Streamable HTTP: a single POST /mcp/ endpoint that accepts and returns JSON-RPC 2.0 messages. Server-Sent Events (SSE) and session management are not used. The maximum request body size is 2 MB.