Huntress API Patterns

Huntress MCP Tools & API Patterns

Overview

The Huntress MCP server provides AI tool integration with the Huntress managed threat detection and response platform. It exposes tools covering account management, endpoint agents, organizations, incidents, escalations, billing, signals, and user management. The API uses HTTP Basic Auth with an API key and secret.

Connection & Authentication

HTTP Basic Auth

Huntress authenticates using an API key and secret passed as HTTP headers:

Header	Description
X-Huntress-API-Key	Your Huntress API key
X-Huntress-API-Secret	Your Huntress API secret

Generate credentials at: Huntress Dashboard > Settings > API Credentials

Environment Variables:

export HUNTRESS_API_KEY="your-api-key"
export HUNTRESS_API_SECRET="your-api-secret"

IMPORTANT: Never hardcode credentials. Always use environment variables.

Available MCP Tools

Navigation

Tool	Description
huntress_navigate	Navigate to a specific resource
huntress_status	Get current navigation status
huntress_back	Navigate back to previous resource

Account

Tool	Description
huntress_accounts_get	Get account details
huntress_accounts_actor	Get current authenticated actor info

Agents

Tool	Description
huntress_agents_list	List endpoint agents with filters
huntress_agents_get	Get details for a specific agent

Organizations

Tool	Description
huntress_organizations_list	List all organizations
huntress_organizations_get	Get organization details
huntress_organizations_create	Create a new organization
huntress_organizations_update	Update an organization
huntress_organizations_delete	Delete an organization

Incidents

Tool	Description
huntress_incidents_list	List incidents with filters
huntress_incidents_get	Get incident details
huntress_incidents_resolve	Resolve an incident
huntress_incidents_remediations	List remediations for an incident
huntress_incidents_remediation_get	Get specific remediation details
huntress_incidents_bulk_approve	Bulk approve remediations
huntress_incidents_bulk_reject	Bulk reject remediations

Escalations

Tool	Description
huntress_escalations_list	List escalations
huntress_escalations_get	Get escalation details
huntress_escalations_resolve	Resolve an escalation

Reports

Tool	Description
huntress_billing_reports_list	List billing reports
huntress_billing_reports_get	Get a specific billing report
huntress_summary_reports_list	List summary reports
huntress_summary_reports_get	Get a specific summary report

Signals

Tool	Description
huntress_signals_list	List security signals
huntress_signals_get	Get signal details

Users

Tool	Description
huntress_users_list	List users
huntress_users_get	Get user details
huntress_users_create	Create a user
huntress_users_update	Update a user
huntress_users_delete	Delete a user

Pagination

The Huntress API uses token-based pagination:

• Pass page_token to retrieve the next page of results
• The response includes next_page_token if more results are available
• Continue fetching pages until next_page_token is absent or null

Example workflow:

1. Call huntress_agents_list with no page_token
2. If response includes next_page_token, call again with that token
3. Repeat until no next_page_token is returned

Rate Limiting

Huntress enforces 60 requests per minute.

• HTTP 429 responses indicate rate limit exceeded
• Wait before retrying — use exponential backoff
• Batch operations where possible
• Use filters to reduce result set sizes

Error Handling

Common Error Codes

Code	Meaning	Resolution
401	Unauthorized	Check API key and secret
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist or wrong ID
429	Rate Limited	Wait and retry after delay
500	Server Error	Retry; contact support if persistent

Error Response Format

{
  "error": {
    "code": 401,
    "message": "Invalid API credentials"
  }
}

Best Practices

• Always paginate through full result sets for completeness
• Use organization filters to scope queries to specific clients
• Cache account/org info to reduce API calls
• Handle rate limits gracefully with backoff
• Log API errors with request context for debugging
• Use the navigation tools (huntress_navigate, huntress_status, huntress_back) to manage stateful workflows

Related Skills

• agents - Endpoint agent management
• organizations - Organization CRUD operations
• incidents - Incident lifecycle management
• escalations - Escalation handling
• billing - Billing and summary reports
• signals - Security signals monitoring