MCP Server Reference

Overview

Every HailBytes SAT instance ships with a built-in Model Context Protocol (MCP) server. AI assistants speak to it directly: create groups, generate templates, launch campaigns, and pull results without ever opening the dashboard. The MCP server uses Streamable HTTP transport, is stateless, and authenticates with the same API key as the REST API.

Authentication

Pull your API key from the HailBytes SAT dashboard at Settings → API Key. Every MCP request must carry it in an Authorization: Bearer header. The MCP endpoint sits behind the same RequireAPIKey middleware as the REST API and inherits the user's role-based permissions.

# Verify the endpoint is reachable
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://sat.example.com:3333/api/mcp/

Client Setup

Claude Desktop / Claude Code

Add the following to your Claude Desktop or Claude Code MCP settings (~/.config/claude/mcp.json on Linux, ~/Library/Application Support/Claude/mcp.json on macOS):

{
  "mcpServers": {
    "hailbytes-sat": {
      "transport": "http",
      "url": "https://sat.example.com:3333/api/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor / Windsurf

{
  "mcp": {
    "servers": {
      "hailbytes-sat": {
        "url": "https://sat.example.com:3333/api/mcp/",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"
        }
      }
    }
  }
}

Anthropic SDK (Python)

from anthropic import Anthropic

client = Anthropic()
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    mcp_servers=[{
        "type": "url",
        "url": "https://sat.example.com:3333/api/mcp/",
        "name": "hailbytes-sat",
        "authorization_token": "YOUR_API_KEY",
    }],
    messages=[{
        "role": "user",
        "content": "Launch a phishing campaign against the Marketing group using the Q2 template.",
    }],
)

Tool Reference

All 14 tools, grouped by resource. Required parameters are marked with *.

Campaign Tools

Email Template Tools

Landing Page Tools

Target Group Tools

Sending Profile (SMTP) Tools

Example: End-to-End Campaign in One Conversation

With the MCP server connected, an operator can run an entire engagement in conversation:

Permissions & Audit

• MCP requests inherit the API key owner's role and permissions. A read-only user can list and get, but cannot create or complete.
• Every tool call is captured in the audit log alongside the originating user, IP, and user agent.
• Rate limiting and request-body limits apply to MCP just as they do to the REST API.

Troubleshooting

Next Steps