IRONSCALES API Patterns

Ironscales MCP Tools & API Patterns

Overview

The Ironscales MCP server provides AI tool integration with the Ironscales anti-phishing platform. It exposes tools for listing and triaging phishing incidents, classifying emails, taking remediation actions, managing sender allowlists, and accessing company-wide phishing statistics. Authentication uses an API key and company ID passed as request headers.

Connection & Authentication

API Key + Company ID

Ironscales uses a static API key combined with a company ID for authentication. The MCP Gateway injects these via headers:

| Header | Description | |--------|-------------| | X-Ironscales-API-Key | Your Ironscales API key | | X-Ironscales-Company-ID | Your Ironscales company (tenant) ID |

Generate credentials at: Ironscales Platform > Settings > API

Environment Variables (self-hosted):

export IRONSCALES_API_KEY="your-api-key"
export IRONSCALES_COMPANY_ID="your-company-id"

IMPORTANT: Never hardcode credentials. Always use environment variables or the MCP Gateway.

The Company ID scopes all API requests to a specific tenant. MSPs managing multiple clients require a separate API key and company ID per client.

Available MCP Tools

Incidents

| Tool | Description | |------|-------------| | ironscales_list_incidents | List phishing incidents with status and type filters | | ironscales_get_incident | Get detailed information for a specific incident | | ironscales_classify_email | Classify an incident's email as phishing, spam, or legitimate | | ironscales_remediate_incident | Take a remediation action on a confirmed incident |

Statistics & Reporting

| Tool | Description | |------|-------------| | ironscales_get_company_stats | Get company-wide phishing statistics and dashboard metrics |

Allowlist Management

| Tool | Description | |------|-------------| | ironscales_manage_allowlist | Add, remove, or list sender allowlist entries |

Pagination

The Ironscales API uses offset-based pagination:

• Pass offset and limit parameters to paginate results
• Default limit is typically 50 records per page
• The response includes total — the total number of matching records

Example response with pagination:

{
  "incidents": [...],
  "total": 148,
  "offset": 0,
  "limit": 50
}

Pagination workflow:

1. Call with offset=0 and limit=50
2. If total > offset + limit, call again with offset=50
3. Continue incrementing offset by limit until all records are retrieved

Rate Limiting

Ironscales enforces per-endpoint rate limits.

• HTTP 429 responses indicate rate limiting
• Use exponential backoff before retrying
• Use status and date filters to limit result volumes
• Avoid unnecessary polling

Error Handling

Common Error Codes

| Code | Meaning | Resolution | |------|---------|------------| | 400 | Bad Request | Check required parameters and classification values | | 401 | Unauthorized | Verify API key and company ID | | 403 | Forbidden | API key lacks permissions for this operation | | 404 | Not Found | Incident ID or resource does not exist | | 429 | Rate Limited | Wait and retry with exponential backoff | | 500 | Server Error | Retry; contact Ironscales support if persistent |

Error Response Format

{
  "error": "INVALID_API_KEY",
  "message": "The provided API key is invalid.",
  "code": 401
}

Best Practices

• Always include companyId in all requests (handled automatically by the MCP server)
• Use status filters (open, closed) to focus on actionable incidents
• Combine offset pagination with status filters to efficiently process large incident backlogs
• Verify incident status before attempting classification — closed incidents cannot be reclassified
• Check ironscales_get_company_stats weekly to track phishing trends and identify anomalies

Related Skills

• [incidents](../incidents/SKILL.md) - Incident lifecycle, classification, and remediation