Skip to main content

​
deadfall serve

Start the Honey-MCP server that receives trap triggers and provides honeypot tools.

​
Usage

deadfall serve [flags]

​
Description

The serve command starts Deadfall’s Model Context Protocol (MCP) server. This server:
  1. Receives trap triggers — The deadfall_ping tool is called when AI agents read trapped files
  2. Provides honeypot tools — Enticing tools like admin_get_secrets that attract malicious agents
  3. Correlates tokens — Links triggered tokens to their source files for detailed alerts

​
Flags

FlagDescription
-v, --verboseEnable verbose/debug output

​
MCP Configuration

To use the Honey-MCP server, configure your MCP client:

​
Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json: 
{
  "mcpServers": {
    "deadfall": {
      "command": "deadfall",
      "args": ["serve"]
    }
  }
}

​
Cursor

Add to ~/.cursor/mcp.json: 
{
  "mcpServers": {
    "deadfall": {
      "command": "deadfall",
      "args": ["serve"]
    }
  }
}

​
Auto-Configuration

Use deadfall init --mcp to automatically configure detected MCP clients.

​
Honeypot Tools

The Honey-MCP server provides these honeypot tools that trigger alerts when called:
ToolSeverityDescription
deadfall_pingCriticalTrap receiver — agents call this when reading trapped files
admin_get_secretsCriticalHoneypot for secret access attempts
db_full_dumpCriticalHoneypot for database exfiltration attempts
export_all_secretsCriticalHoneypot for bulk secret export
get_ssh_keysCriticalHoneypot for SSH key theft
execute_shell_commandCriticalHoneypot for command execution
read_private_filesWarningHoneypot for file access
bypass_permission_checkCriticalHoneypot for privilege escalation
get_api_keysCriticalHoneypot for API key theft
All honeypot tools return “Access Denied” errors while triggering security alerts.

​
Alerts

When a tool is triggered, Deadfall:
  1. Logs to console — Structured log output with alert details
  2. Logs to file — deadfall_alerts.log with timestamp and context
  3. Desktop notification — Cross-platform system notification
  4. Webhook — Optional HTTP webhook delivery (if configured)

​
Example

deadfall serve
The server runs via stdio (standard MCP transport) and waits for tool calls from connected AI agents.