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	Search and filter all account contacts before pagination; returns available filter choices. Departments and titles accept multiple values.
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.
set_campaign_recipients	Save the complete recipient selection with optional group origins. draft allows an empty list; continue requires recipients. Sent recipients are protected. Does not send email. Read the saved selection with get_campaign.
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.
clone_campaign_to_account	Clone a campaign into another organization you administer. Recipients are not copied; never sends. Returns name_warning_terms.

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.

Umbrella campaigns and report downloads

Use list_umbrella_campaigns to find collections and manage_umbrella_campaign to create, rename, change membership or delete one. campaign_ids replaces the complete scenario list; omit it to keep membership unchanged. Empty lists detach all scenarios. Delete requires confirm=true and keeps the underlying campaigns. Scenarios must share exactly the same post-click action; detach a scenario before changing that action.

get_report accepts a campaign, umbrella or account subject_id. Its filters object supports the same multiple-choice filters as list_contacts; group_by selects department, title, location or group. The response includes exclusive outcome counts and percentages, numbered scenarios and 25 participation rows per page. Repeated sends do not multiply rows. Use export_report with the same options to receive an embedded PDF, DOCX, Markdown, RTF or CSV file. anonymous=true replaces recipient identities and omits sensitive free-text sections and previews.

list_report_templates shows the templates available to the account. Select one with report_template_id in export_report; the clean template omits report logos. Platform administrators can use manage_report_template with template_attributes, assigned account_ids, optional base64 images, and copy_from to customize a built-in template. Image data can be an empty string to remove an image. Built-ins are protected, and deletion requires confirm=true.