Huntress MCP Server

A Model Context Protocol (MCP) server for interacting with the Huntress security platform, featuring a decision tree architecture for efficient tool loading.

Architecture

This MCP server uses a hierarchical tool loading approach instead of exposing all tools upfront:

1. Navigation Phase: Initially exposes only a navigation tool (huntress_navigate)
2. Domain Selection: User selects a domain from the 14 available domains
3. Domain Tools: Server exposes domain-specific tools after selection
4. Lazy Loading: Domain handlers are loaded on-demand

This architecture provides:

• Reduced cognitive load (fewer tools to choose from)
• Faster initial load times
• Better organization of related operations
• Clear navigation state

Installation

npm install @avantguardllc/mcp-huntress

Configuration

Set the following environment variables:

| Variable | Required | Description | |----------|----------|-------------| | HUNTRESS_AUTH_HEADER | One of | Pre-encoded Authorization header value, including the Basic prefix (e.g. Basic dXNlcjpwYXNz). Use this when you already have the header available from another service. | | HUNTRESS_API_KEY | these | Huntress API Key — combined with HUNTRESS_API_SECRET to build Basic base64(key:secret) automatically. | | HUNTRESS_API_SECRET | two | Huntress API Secret — required when using HUNTRESS_API_KEY. |

Usage

Running Standalone

# Option A: pre-encoded auth header (includes "Basic " prefix)
export HUNTRESS_AUTH_HEADER="Basic <your-base64-encoded-key:secret>"

# Option B: raw key + secret
export HUNTRESS_API_KEY="your-api-key"
export HUNTRESS_API_SECRET="your-api-secret"

# Run the server
npx @avantguardllc/mcp-huntress

Claude Desktop Configuration

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "huntress": {
      "command": "npx",
      "args": ["@avantguardllc/mcp-huntress"],
      "env": {
        "HUNTRESS_API_KEY": "your-api-key",
        "HUNTRESS_API_SECRET": "your-api-secret"
      }
    }
  }
}

Docker

docker run -e HUNTRESS_API_KEY=*** -e HUNTRESS_API_SECRET=*** ghcr.io/avantguardllc/mcp-huntress

Available Domains

Accounts

View current account info and manage sub-accounts.

Tools:

• huntress_get_current_account - Get details for the authenticated account
• huntress_list_accounts - List all accounts accessible to the API key
• huntress_get_account - Get details for a specific account
• huntress_create_account - Create a new account
• huntress_update_account - Update an existing account
• huntress_delete_account - Delete an account

Actor

Get information about the authenticated API key owner.

Tools:

• huntress_get_actor - Get the current authenticated actor (API key owner info)

Agents

View and manage Huntress agents installed on endpoints.

Tools:

• huntress_list_agents - List agents with optional filters
• huntress_get_agent - Get details for a specific agent

Escalations

View escalated threats requiring attention.

Tools:

• huntress_list_escalations - List escalations
• huntress_get_escalation - Get details for a specific escalation
• huntress_resolve_escalation - Mark an escalation as resolved

External Ports

View external ports detected across endpoints.

Tools:

• huntress_list_external_ports - List external ports with optional filters
• huntress_get_external_port - Get details for a specific external port entry

Identities

Manage identities tracked by Huntress identity protection.

Tools:

• huntress_list_identities - List identities with optional filters (org, tenant type, risk level, MFA status, etc.)
• huntress_get_identity - Get details for a specific identity

Incidents

View and manage security incident reports and remediations.

Tools:

• huntress_list_incidents - List incident reports with optional filters
• huntress_get_incident - Get details for a specific incident report
• huntress_resolve_incident - Mark an incident report as resolved
• huntress_list_remediations - List remediations for an incident report
• huntress_get_remediation - Get details for a specific remediation
• huntress_bulk_approve_remediations - Bulk approve remediations for an incident
• huntress_bulk_reject_remediations - Bulk reject remediations for an incident

Invoices

View invoices and billing for the current account.

Tools:

• huntress_list_invoices - List invoices with optional filters
• huntress_get_invoice - Get details for a specific invoice

Memberships

Manage agent/organization membership associations.

Tools:

• huntress_list_memberships - List memberships with optional filters
• huntress_create_membership - Create a new membership
• huntress_get_membership - Get details for a specific membership
• huntress_update_membership - Update a membership
• huntress_delete_membership - Delete a membership

Organizations

Manage organizations (clients) in Huntress.

Tools:

• huntress_list_organizations - List all organizations
• huntress_get_organization - Get details for a specific organization
• huntress_create_organization - Create a new organization
• huntress_update_organization - Update an existing organization
• huntress_delete_organization - Delete an organization

Reports

Retrieve summary and detail reports.

Tools:

• huntress_list_reports - List available reports
• huntress_get_report - Get details for a specific report

Reseller

Manage reseller invoices, subscriptions, and usage.

Tools:

• huntress_list_reseller_invoices - List reseller invoices
• huntress_get_reseller_invoice - Get details for a specific reseller invoice
• huntress_list_reseller_invoice_account_usage - List account usage line items for a reseller invoice
• huntress_list_reseller_invoice_org_usage - List organization usage line items for a reseller invoice
• huntress_list_reseller_subscriptions - List reseller subscriptions
• huntress_get_reseller_subscription - Get details for a specific subscription
• huntress_create_reseller_subscription - Create a new subscription
• huntress_update_reseller_subscription - Update a subscription
• huntress_upgrade_reseller_subscription - Upgrade a subscription

SIEM

Query SIEM event data in Huntress.

Tools:

• huntress_siem_query - Query SIEM data/events with filters (query string, time range, organization)

Signals

View threat detection signals.

Tools:

• huntress_list_signals - List signals with optional filters
• huntress_get_signal - Get details for a specific signal

Known VPNs

List VPN providers tracked by Huntress, used in conjunction with unwanted access rules.

Tools:

• huntress_list_known_vpns - List known VPN providers tracked by Huntress

Unwanted Access Rules

Manage rules that define conditions under which access is considered unwanted (e.g., logins from specific countries or VPN providers).

Tools:

• huntress_list_unwanted_access_rules - List unwanted access rules with optional filters
• huntress_get_unwanted_access_rule - Get details for a specific unwanted access rule
• huntress_create_unwanted_access_rule - Create a new unwanted access rule
• huntress_update_unwanted_access_rule - Update an existing unwanted access rule
• huntress_delete_unwanted_access_rule - Delete an unwanted access rule

Navigation Tools

Always available:

• huntress_navigate - Select a domain to work with
• huntress_status - Show current state and credential status
• huntress_back - Return to main menu (when in a domain)

Example Workflow

User: Check my security incidents
Claude: [calls huntress_navigate with domain="incidents"]
       -> Navigated to incidents domain. Available tools: ...

User: List open incidents
Claude: [calls huntress_list_incidents]
       -> [incident list results]

User: Now show me agents
Claude: [calls huntress_back]
       -> Navigated back to main menu.
       [calls huntress_navigate with domain="agents"]
       -> Navigated to agents domain.

License

Apache-2.0