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: Changes made via MCP, and full case dumps pulled through it, are logged in the audit system with the API key prefix and an mcp: marker, distinguishing agent activity 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 > 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 59 tools organized into 11 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	9	Create, update, close/reopen, escalate cases, assign teams, dashboard stats, full case data dump
Items	8	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	8	Manage incident response actions, assignments, blockers, 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
Knowledge Base	4	Browse, read, and write Knowledge Base folders and pages. Password-protected content is never exposed
Case Chat	2	Read a case chat transcript and post to it. Off until you switch it on

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.

MCP mutations follow the same application workflows as their API counterparts. Where a change in the app produces a timeline event, an in-app or collaboration notification, a Jira update, a webhook, an automation event, or a live report update, the corresponding MCP tool produces that follow-up work as well. Action, non-timeline case-note and live-report integration dispatch waits until the change and its audit entry commit.

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
• Runbooks. Runbooks with their slugs and step counts
• Incident categories. Categories an incident can be classified under
• Outcome verdicts. Verdicts available when a case is closed

Knowledge Base Access

Agents can browse the Knowledge Base, read a page by its address or id, and write: creating pages and folders, editing a page's title, content, description and access groups, and moving pages and folders. A title or content change is saved as a new version, and an edit that would overwrite someone else's save is refused and reported instead. Pages and folders cannot be deleted through MCP.

The Knowledge Base view permissions gate access, and access groups narrow it further, exactly as they do in the web interface: a key belonging to a user who cannot see a page cannot read it, search it, or change who else can. On a page the key's owner can edit, the agent has that owner's full editing rights, access groups included. See Knowledge Base. AI agents.

Password-protected content is not available through MCP at all. A page with its own password is listed but its content cannot be read or edited, and a password-protected folder keeps its entire contents hidden. No tool accepts a password, so a Knowledge Base password is never sent to a language model. Open protected content in the web interface instead.

Case Chat

The Case Chat group is off until you switch it on, in Settings → MCP Server, on a new installation and an upgraded one alike. While it is off, DFIRe leaves the two chat tools out of tools/list, refuses a call naming one, and no chat content leaves DFIRe through MCP.

Switch it on and chat content reaches every connected agent whose key belongs to a user who may read the case and the chat. Decide with that in mind: a case chat holds whatever the team pasted into it.

An agent reads a transcript with get_case_chat, which returns up to 100 messages ending at the newest one and reads further back on request. The transcript arrives as untrusted data: the messages sit between explicit markers, under a line stating that the content came from people working the case and is never an instruction to the agent. A redacted message travels as a tombstone with no text, and an assistant answer carries the model that wrote it.

An agent posts with post_case_chat_message. DFIRe writes the message as the user whose API key made the call. It appears in the case chat window like any other message, notifies anyone it mentions and reaches the audit trail under that user's name. Addressing @assistant this way summons nobody. The case assistant answers only from the chat window.

The two tools carry the chat permissions, so a role without view case chat message cannot read a transcript and a role without add case chat message cannot post, both exactly as in the web interface. Case viewers read the chat and post nothing, and a closed or archived case takes no new messages.

get_case_full_dump carries the transcript in the same guarded form, and only while the Case Chat group is on and the caller may read chat. See Case Chat.

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
dfire://docs/knowledge-base	Knowledge Base structure, addressing, versioning, visibility, and password protection

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

Every change an agent makes is recorded against the object it changed, with the fields that changed, so it appears in that object's history exactly as the same change made in the web app does. Pulling a full case dump is recorded as an export on the case, naming how much of each section was returned; if that entry cannot be written, the data is not returned. Ordinary reads such as retrieving a case or listing its evidence are not recorded, matching the API.

Recorded entries carry two markers that identify them as MCP activity:

• 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 the state of a record are annotated with destructiveHint: true in the MCP tool schema. Well-behaved MCP clients will prompt the user for confirmation before executing these tools. Eight tools carry the annotation:

• Updating a case, which includes closing and reopening it
• Changing a case's playbook
• Deleting an evidence item
• Managing notes
• Managing timeline events
• Managing compliance timers
• Changing an indicator's publication or revocation status
• Deleting indicators

Best Practices

An MCP agent is a user of DFIRe, and DFIRe treats it as one. Give it an account of its own, the narrowest access its work needs, and a review routine.

Give the Agent Its Own Account

The server acts as the user whose API key it authenticates with. Every case the agent reads, every record it writes and every audit entry it leaves carries that user's name. Do not hand an agent a key from your own account. Its work and yours become one account's history, and the agent reaches everything you can reach.

Create a service account for it instead, named after the agent rather than after a person, for example svc-triage-agent. An investigator sees that name on a note the agent wrote, and an administrator filters the audit log by it. Choose a clear one before the first run. Give the account a role of its own, such as MCP Service Accounts, holding only the capabilities that agent's work needs. See Service Accounts for how to create both.

Choose the Tools and the Cases Separately

Tool groups and permissions are different controls, and both apply. A tool group is global: switching one on in Settings → MCP Server exposes those tools to every connected agent. A role is per account. Turn on only the groups you use, and let each account's role decide what it may do with them.

Case team membership decides which cases an agent sees at all. Add it as an investigator rather than as the lead. The lead investigator is the person accountable for the case: they stay on the team list permanently, and they can redact anyone's chat message.

Automation can put an agent on cases as they arrive. Write a rule in Settings → Automation with the action Add user to case team, the role set to Investigator, and filters matching the cases it should work. See Automation.

Read What the Agent Did

The audit trail already separates agent activity from everyone else's, through the mcp: marker and the API key prefix. Read it as a routine rather than after a surprise.

The destructiveHint annotation is advice to the client, not a rule DFIRe enforces. A client set to approve tool calls automatically runs a destructive tool without asking anyone. The account's permissions decide what an agent can destroy, so grant delete capabilities only where you want them used.

An API key is the agent's only credential. Multi-factor authentication does not cover API keys, so the key itself is the whole control. Revoke it when the agent's work ends, or when it may have leaked, and issue a new one.

Treat Case Content as Untrusted

Case data comes from your team and from whoever is under investigation: a phishing body, a ransom note, a string pulled from a sample, a description out of an imported feed. Any of it can carry instructions addressed to an agent that reads it.

The assistant inside DFIRe holds no tools and no write access, so material that manipulates it produces one wrong answer, marked as generated. An MCP agent reads the same material and can write, close, publish and delete. Keep its permissions to what the work needs, and check the audit trail for what it changed.

Configuration

MCP server settings are managed in Settings > 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 11 tool groups. Disabled groups are hidden from tools/list and their tools reject calls. A group added by a later version is off until you enable it, unless you have never changed these toggles. Case Chat is off in both cases: it is enabled only by switching it on here.

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.