MCP Server (AI Integration)

PhishSpot ships an MCP (Model Context Protocol) server, so an AI client such as Claude can drive PhishSpot on your behalf — using natural language, against the same data and rules as the web app. The tool surface now mirrors most of what a human can do in the admin app: browse the template library, build and schedule campaigns, upload hosted images, manage contacts/groups/courses/domains/webhooks/autopilots, and read every result and trend.

29.1 Endpoint

The MCP server is available at:

https://platform.phishspot.com/mcp

It speaks JSON-RPC over HTTP. Point any MCP-capable client at that URL using the HTTP transport.

29.2 Authentication

The MCP server reuses PhishSpot API tokens. A token must be explicitly granted MCP access.

1. Go to Settings → API Tokens → New Token.
2. Give it a name and tick Allow MCP access.
3. Copy the token value (shown once).

Note

A token can act on every account you belong to, and MCP write actions require an admin or editor role in the target account. Treat the token like a password.

29.3 Connecting Claude

For Claude Code, run (replace YOUR_TOKEN):

claude mcp add --transport http phishspot https://platform.phishspot.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

For Claude Desktop or another client, add a server entry:

{
  "mcpServers": {
    "phishspot": {
      "type": "http",
      "url": "https://platform.phishspot.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

29.4 Safety: what sends and what doesn’t

Almost everything the AI can do is read-only or build-only. The build_*, create_* and set_* campaign tools prepare a campaign up to the review step and never send email to recipients — a person launches each campaign from the PhishSpot UI.

A small, clearly-labelled set of action tools can trigger real email, so an AI can run a campaign end-to-end when you ask it to. Their descriptions open with a warning, and they require an admin/editor role:

Action tool	Effect
schedule_campaign	Sends real email — schedules a ready campaign to actually launch at a given time.
reschedule_campaign	Sends real email — moves a scheduled campaign to a new send time.
start_autopilot	Starts a live program — activates an autopilot that generates and sends recurring campaigns on a schedule.

cancel_schedule, pause_autopilot and stop_autopilot are the safe counterparts — they stop sends. Adding a sending domain provisions it and returns nameservers to set at your registrar; it does not register or buy the domain.

Tip

If you want the AI to never send on its own, simply don’t ask it to schedule or start anything — every other tool leaves a human in control of the launch button.

29.5 Available tools

Almost every account-scoped tool takes an account_id (acct_…). Call whoami first to discover the accounts and roles your token can use. Tools are grouped below by capability.

Identity & sending domains

Tool	What it does
whoami	List the authenticated user and the accounts/roles the token can act on.
list_sending_domains	List active and provisioning sending domains for an account.
provision_sending_domain	Add a BYOD sending domain and return the nameservers to set at the registrar.
check_sending_domain	Poll a sending domain’s delegation, mail records, and whether it is sendable.
list_platform_domains	List every domain visible to the account (shared + BYOD) with state and sendability.
get_platform_domain	Full detail for one domain: verification status, expected DNS records, diagnostics, block reason.

Contacts & groups

Tool	What it does
list_contacts	List contacts in an account (paginated).
import_contacts	Import contacts from CSV or JSON; the groups column models waves/segments.
update_contact	Update a contact’s fields and/or replace its group membership.
delete_contacts	Delete contacts (skips any locked by an active campaign).
list_groups	List contact groups in an account.
create_group	Create a new contact group.
delete_group	Delete a group (unless it is locked by an active campaign).
add_contacts_to_group	Add contacts to a group (skips duplicates).
remove_contacts_from_group	Remove contacts from a group.

Phishing template library

Tool	What it does
list_phishing_templates	List curated or custom templates, filterable by category and search.
get_phishing_template	Get one template’s full email + landing HTML/CSS and post-click action.
list_phishing_categories	List the template category tree (only leaf categories hold templates).
build_campaign_from_template	Build a draft campaign from a template; optionally add all contacts and stop at review. Never sends.

E-learning courses

Tool	What it does
list_courses	List courses usable by the account (own + global) with block counts and completion stats.
get_course	Get one course’s details and an ordered summary of its blocks.

Media library (image hosting)

Tool	What it does
upload_media	Upload an image or CSS file (from a URL or base64) and get a hosted URL for emails/landings.
list_media	List the account’s hosted media.
delete_media	Delete a media file.

Tip

Email clients (Gmail, Outlook) strip data: image URIs, so embed upload_media’s hosted URL in campaign HTML rather than inlining base64.

Campaign building

Tool	What it does
list_campaigns	List campaigns with state and wizard progress.
get_campaign	Full status of one campaign, including what still blocks launch.
create_campaign	Create a draft campaign (settings).
set_campaign_email	Set the email subject and HTML body.
set_campaign_landing	Set the landing page and sending/landing domain.
set_campaign_post_click	Set the post-click action (training, awareness page, or redirect).
add_campaign_recipients	Add recipients (all, a group, or specific contacts). Leaves the campaign at review.
build_campaign_from_spec	Build a whole draft campaign in one call (settings → recipients).
duplicate_campaign	Duplicate a campaign into a fresh draft (with recipients). Never sends.

Campaign scheduling

Tool	What it does
schedule_campaign	⚠ Sends real email — schedule a ready campaign to launch at a given time.
reschedule_campaign	⚠ Sends real email — move a scheduled campaign to a new send time.
cancel_schedule	Cancel a pending scheduled send, returning the campaign to draft.

Results & reporting (read-only)

Tool	What it does
get_campaign_results	Engagement funnel plus per-group and per-department breakdowns.
get_campaign_recipients	Per-recipient delivery stage, training status and reply flag (filterable).
get_recipient_timeline	Chronological event timeline for one contact in a campaign.
get_campaign_replies	Replies recipients sent back to the phishing email.
list_account_trends	Phishing-susceptibility trends across campaigns over a date range.
list_events	Raw engagement events, filterable by campaign / contact / type.
list_reported_messages	Suspicious emails employees reported (sender/subject metadata only).

Webhooks

Tool	What it does
list_webhook_endpoints	List outbound webhook endpoints.
get_webhook_endpoint	One endpoint plus its recent deliveries (signing secret masked).
create_webhook_endpoint	Create a (disabled) endpoint; returns the signing secret once.
update_webhook_endpoint	Update an endpoint’s name, URL or event subscriptions.
delete_webhook_endpoint	Delete an endpoint and its delivery history.
toggle_webhook_endpoint	Enable or disable an endpoint.
list_webhook_event_types	List the event types you can subscribe to (no account needed).

Autopilots (automated programs)

Tool	What it does
list_autopilots	List autopilot programs and their state/progress.
get_autopilot	One autopilot’s config, target groups and recent campaigns.
create_autopilot	Create an autopilot in draft. Does not start it.
update_autopilot	Update an editable (non-stopped) autopilot.
delete_autopilot	Delete an autopilot (not while it is running).
start_autopilot	⚠ Starts a live program that sends recurring phishing campaigns on a schedule.
pause_autopilot	Pause a running autopilot.
stop_autopilot	Stop an autopilot permanently (irreversible).

29.6 Adding a sending domain (BYOD)

To send a campaign from your own domain (for example your-org.com):

1. Ask the AI to call provision_sending_domain with the domain.
2. Set the returned nameservers at your domain registrar.
3. Poll with check_sending_domain until it reports the domain is active and sendable.

Once active, the domain appears in list_sending_domains / list_platform_domains and can be used as a campaign’s sending/landing domain. See also Domains.

29.7 Example: build a campaign from a template

A typical AI-driven flow, all build-only until you choose to schedule:

1. whoami → pick the account_id.
2. list_phishing_categories and list_phishing_templates → choose a template.
3. build_campaign_from_template (optionally quick_launch) → a draft campaign with recipients, sitting at review.
4. get_campaign → confirm there are no readiness errors.
5. Either launch it yourself in the UI, or ask the AI to schedule_campaign for a specific time (this sends for real).
6. After it runs, get_campaign_results, get_campaign_recipients and list_account_trends summarize who fell for it.

Every tool ships live on the platform with each deploy — no extra setup, no migration, and no per-tool configuration is required.