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"

IMPORTANT: Never hardcode credentials. Always use environment variables.

Available MCP Tools

Navigation

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

• 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