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:

Generate credentials at: Huntress Dashboard > Settings > API Credentials

Environment Variables:

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

Available MCP Tools

Navigation

Navigation here is stateless discovery, not a cursor. There is no current resource and no history, so there is no "back" tool — every tool below is callable directly at any time, and huntress_navigate is never a prerequisite for calling one.

Through Conduit, huntress_navigate is refused for every caller by the discovery-tool suppression gate, so a workflow that begins by calling it will fail at step one. Read the catalog below instead.

Account

Agents

Organizations

Incidents

Escalations

Reports

Signals

Users

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

Error Response Format

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

Best Practices

• Use organization filters to scope queries to specific clients
• Cache account/org info to reduce API calls
• Do not build workflows on navigation state — there is none. Call the tool you need directly; use huntress_status only to confirm credentials and reachability before a batch run

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