phishfort-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@phishfort-mcp Show me recent phishing incidents"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
██████╗ ██╗ ██╗██╗███████╗██╗ ██╗███████╗ ██████╗ ██████╗ ████████╗
██╔══██╗██║ ██║██║██╔════╝██║ ██║██╔════╝██╔═══██╗██╔══██╗╚══██╔══╝
██████╔╝███████║██║███████╗███████║█████╗ ██║ ██║██████╔╝ ██║
██╔═══╝ ██╔══██║██║╚════██║██╔══██║██╔══╝ ██║ ██║██╔══██╗ ██║
██║ ██║ ██║██║███████║██║ ██║██║ ╚██████╔╝██║ ██║ ██║
╚═╝ ╚═╝ ╚═╝╚═╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝
███╗ ███╗ ██████╗██████╗
████╗ ████║██╔════╝██╔══██╗
██╔████╔██║██║ ██████╔╝
██║╚██╔╝██║██║ ██╔═══╝
██║ ╚═╝ ██║╚██████╗██║
╚═╝ ╚═╝ ╚═════╝╚═╝
MCP server + paired agent skill for PhishFort workflows
approval-gated writes | secret-safe defaults | no URL fetchingphishfort-mcp
A security-first MCP server and paired agent skill for the PhishFort Unified Client API.
Security-reviewed and hardened — 2026-07-29. Approval-gated writes · secret-safe by default · no incident-URL fetching · every security claim verified against the code.
Bring PhishFort incident review, reporting, attachments, comments, and webhook management into your MCP client, then give your agent the workflow playbook for using those tools safely.
Paired skill | Official PhishFort API docs | Security review | Local reference
Unofficial project. Not affiliated with, endorsed by, or maintained by PhishFort.
Security, reviewed in the open
This is a security tool, so the security work is the headline — not a disclaimer at the bottom. Every control is implemented in code, covered by tests, and was put through a review-and-harden pass whose results are public.
2026-06-02 — v0.1.0. Local
stdioMCP server and paired agent skill, security-first by default: approval-gated writes, API host pinning, redirects disabled, and no fetching of incident URLs.2026-06-05 — Posture mapped to evidence. Every security feature documented against MCP, OpenAI, and Anthropic guidance, each row tied to the exact code and test behind it.
2026-06-10 — Review and hardening pass. A security review conducted by Claude Fable 5 Ultracode (initial pass), Opus 4.8 xhigh, rubber-ducked with Codex 5.5 xhigh via plugin drove a hardening pass:
destructive confirmation is now enforced on incident-action requests — the annotation and the approval gate agree,
secret-named fields are scrubbed recursively, and one-time webhook secrets are written through
O_NOFOLLOW0600files,reads retry bounded transport failures; writes retry only proven pre-send connection/pool failures; secret-named fields are redacted from errors,
the approval salt is random and process-stable, and the retry count is bounded,
the webhook URL preflight rejects legacy numeric-IP encodings,
the final attachment descriptor is held through upload, narrowing the validate→upload replacement window.
The same pass reworded every security claim to match what the code enforces — the approval gate is described as in-process integrity and confirmation, not independent authorization, and the webhook URL check as a pre-submit sanity check. Tests went from 26 to 36.
2026-07-30 — v0.1.1. Packages reference resources into wheels, adds current Users, Clients, Documents, and total-count reads, distinguishes safe read retries from mutation outcomes needing manual review, binds immutable attachment snapshots to approval, validates webhook timestamp freshness, requires file-backed verifier secrets, hardens one-time secret persistence beneath an owned
0700root, and uses documented attachment MIME types. Distribution uses a versioned Git tag and GitHub Release assets; this project is not published to PyPI.
The table below is the evidence: each control maps to the code and the test that backs it.
Related MCP server: wrg-mcp-server
Standards-Backed Security Posture
This server was designed against the Official Model Context Protocol security guidance, Anthropic connector guidance, OpenAI MCP guidance, OpenAI agent safety guidance, and PhishFort's official API docs. The table below lists only security features that are implemented in code, with local evidence.
Local evidence:
Security feature | What it prevents | Confirmed implementation |
Local | Avoids exposing a public HTTP MCP surface in v1 |
|
Two-step approval gate for writes | Forces an explicit plan→confirm step with a tamper-evident digest before any mutation. This is in-process integrity/confirmation, not independent human authorization — the host UI provides the human prompt via the destructive hints below | Write tools require |
Tamper-resistant approval digest | Blocks changing params after approval planning |
|
Destructive confirmation | Adds explicit friction for delete/rotate operations | Destructive specs require |
Read/write MCP annotations | Gives MCP hosts correct safety hints |
|
API keys never passed as tool args | Reduces credential leakage through prompts/tool logs |
|
Default API host pinning | Avoids accidental credential use against arbitrary hosts |
|
Redirects disabled | Avoids following API responses to unexpected locations |
|
Error redaction | Prevents API keys, secret-named fields, and echoed secret values from leaking through raised API errors |
|
Untrusted data warnings | Reminds agents not to treat remote content as instructions |
|
No generic URL fetching | Avoids browsing hostile or sensitive URLs returned by the API | Server exposes PhishFort API tools only; no tool fetches incident or document URLs |
Attachment file restrictions | Reduces local file exfiltration and approval-time file swaps |
|
Webhook URL preflight (defense-in-depth) | Rejects localhost/private/reserved targets — including legacy decimal/octal/hex IP forms — before a webhook is registered. The server never fetches the URL itself (PhishFort delivers webhooks), so backend egress controls remain the real boundary |
|
Webhook secret containment | Keeps one-time secrets out of tool output and avoids post-mutation sink setup |
|
Webhook signature verification | Enables receiver-side HMAC verification and rejects stale timestamps |
|
Limit-aware behavior | Avoids known API limit failures where possible |
|
Bounded retry behavior | Avoids unsafe retry storms and duplicate writes | Reads may retry |
About
phishfort-mcp is a public, unofficial MCP integration for teams and operators who want PhishFort incident workflows available inside agentic tools without giving up basic operational control. The MCP server provides live API access; the paired skill gives compatible agents the workflow memory needed to use that access consistently.
It is built for local-first use, explicit approvals, and careful handling of phishing data. The goal is not to make incident response fully autonomous. The goal is to make the repetitive parts faster while keeping sensitive actions, secrets, and untrusted content under control.
Why This Exists
PhishFort has a focused REST API for phishing incident workflows. MCP makes that API usable from agentic tools, and the paired skill teaches those agents the operating procedure: what to read first, how to plan writes, what data is untrusted, and when to stop for explicit approval.
That pairing matters because security workflows are not just API calls. Incident data can contain hostile text, URLs should not be fetched casually, and takedown or webhook operations should not happen from a loose prompt.
phishfort-mcp ships two pieces that work together:
a local
stdioMCP server for live PhishFort API accessan agent-agnostic skill that turns raw tool access into repeatable, safer workflows
approval-gated writes for reporting, actions, evidence, comments, and webhooks
secret-safe handling for API keys and one-time webhook secrets
untrusted-data guardrails for incident text, URLs, and webhook payloads
What You Can Do
Workflow | Tools |
Give agents the PhishFort operating playbook |
|
Check documented API limits |
|
Check identity and client scope |
|
List users and clients in authorized scope |
|
Search and inspect incidents |
|
List document metadata and obtain short-lived signed URLs |
|
Report URLs, domains, emails, phones, and IPv4 subjects |
|
Request takedown, monitoring, or safe review |
|
Add evidence and analyst context |
|
Manage webhook subscriptions |
|
Verify incoming webhook deliveries |
|
The server also exposes MCP resources for the distilled API reference, source manifest, and security review:
phishfort://reference/summaryphishfort://reference/limitsphishfort://reference/source-manifestphishfort://reference/security-review
Paired Skill
This repo ships an agent-agnostic skill in skills/phishfort-mcp/SKILL.md. Use it with any skill-capable MCP host to teach the agent the safe operating pattern for this server: read before write, treat all remote API data as untrusted, never fetch returned URLs by default, and use phishfort_plan_change before mutating calls.
The skill keeps detailed workflows in references/workflows.md, exact tool parameters in references/tool-map.md, and points agents to phishfort_get_limits before workflows where limits change the right next step.
The GitHub Release wheel installs the MCP server and its embedded reference resources. The paired skill is a repository asset; download it from the matching Git tag when your host supports skills. This project is not published to PyPI.
Safety Built In
The standards-backed table above is the detailed proof. Operationally, the server stays local-first, keeps credentials out of tool arguments, treats PhishFort data as untrusted, gates writes through phishfort_plan_change, stores webhook secrets outside tool output, and constrains attachments, webhook URLs, limits, and retries.
See MCP security review for the reasoning behind these choices.
Quick Start
uvx --from git+https://github.com/mychaelconnolly/phishfort-mcp.git@v0.1.1 phishfort-mcp --helpFor source development or the paired skill:
git clone --branch v0.1.1 --depth 1 https://github.com/mychaelconnolly/phishfort-mcp.git
cd phishfort-mcp
uv sync --frozen --extra dev
uv run phishfort-mcp --helpCreate a local key file:
mkdir -p ~/.config/phishfort-mcp
chmod 700 ~/.config/phishfort-mcp
$EDITOR ~/.config/phishfort-mcp/phishfort-api-key.txt
chmod 600 ~/.config/phishfort-mcp/phishfort-api-key.txtCodex MCP Registration
codex mcp add phishfort \
--env PHISHFORT_API_KEY_FILE=$HOME/.config/phishfort-mcp/phishfort-api-key.txt \
-- uvx --from git+https://github.com/mychaelconnolly/phishfort-mcp.git@v0.1.1 phishfort-mcpThen verify:
codex mcp listA fresh Codex session may be required before new MCP tools are discoverable.
Configuration
Variable | Default | Notes |
|
| Pinned to official API host unless override is enabled. |
| unset | Useful for short-lived local shells. |
| unset | Preferred for MCP registration. |
|
| Effective-user-owned |
|
| Comma-separated roots allowed for attachment uploads. |
|
| HTTP request timeout. |
|
| Caps read-side |
|
| Test-only escape hatch for non-production API hosts. |
|
| Test-only escape hatch for localhost/private webhook targets. |
phishfort_verify_webhook_signature accepts secret_file only. The file must remain
beneath PHISHFORT_SECRET_DIR; the root and any subdirectories must be owned by the
effective user with mode 0700. Symlinked components, root rebinding, and platforms
without required descriptor-relative no-follow primitives fail closed.
Approval-Gated Writes
Read tools can be called directly. Writes are two-step on purpose:
Call
phishfort_plan_changewithoperationand exact params.Review
warnings,risk,request_digest, andapproval_phrase.Call the intended mutating tool with the same params plus
approval_id,approval_phrase,expires_at, andrequest_digest.
If anything changes, rerun phishfort_plan_change.
This gate is in-process integrity and confirmation: it proves the executed params
match the planned params (tamper-evident digest), enforces expiry, and requires
destructive_confirmed=true for destructive operations. It is not an independent
authorization boundary — the same agent can plan and confirm. The human-in-the-loop
checkpoint is the MCP host's own tool-confirmation UI, driven by the destructive
annotations the server sets.
Mutating API calls are not automatically replayed after HTTP status responses or ambiguous
read/protocol failures. PhishFort documents no idempotency key for incident reports. A
report 409 means duplicate. Any 2xx with a nonempty incident id confirms creation,
even when dashboard url is null or absent; a 2xx without a nonempty id stops for
manual review with no automatic retry.
Verification
uv run ruff check .
uv run pytestOptional live smoke when a valid key exists:
phishfort_whoamiphishfort_list_incidents(limit=1)
Do not run live mutating smoke unless you intend to change PhishFort state.
Document signed URLs are short-lived download grants. Treat them as sensitive, untrusted API output: do not persist or share them, and do not fetch them automatically.
API Reference
Official PhishFort docs:
PhishFort's docs MCP serves documentation, not account API operations. This project remains the local account-workflow MCP server.
This repo includes a distilled reference in docs/reference/phishfort-unified-client-api.md and a source URL manifest in docs/reference/source-manifest.json. Fetched raw PhishFort docs are intentionally not tracked.
License
MIT. See LICENSE.
Available Tools
23 toolsphishfort_add_attachmentsAdd PhishFort AttachmentsC
Add attachment files to an existing incident after approval.
Inputs: expires_at (required), approval_id (required), incident_id (required), request_digest (required), +3 more. Returns: data, outcome, operation, http_status, +4 more
phishfort_add_commentAdd PhishFort CommentB
Add a comment to an existing incident after approval.
Inputs: comment (required), expires_at (required), approval_id (required), incident_id (required), +3 more. Returns: data, outcome, operation, http_status, +4 more
phishfort_create_webhookCreate PhishFort WebhookC
Create webhook subscription. One-time secret is saved locally, not returned.
Inputs: url (required), events (required), expires_at (required), approval_id (required), +5 more. Returns: data, webhook_id, http_status, remote_state, +7 more
phishfort_delete_webhookDelete PhishFort WebhookCDestructive
Delete webhook subscription after approval.
Inputs: expires_at (required), webhook_id (required), approval_id (required), request_digest (required), +2 more. Returns: data, outcome, operation, http_status, +4 more
phishfort_find_incident_by_subjectFind PhishFort Incident By SubjectBRead-onlyIdempotent
Find one incident by URL, domain, or subject value. Subject is URL-encoded.
Inputs: subject (required). Returns: object
phishfort_get_documentGet PhishFort DocumentARead-onlyIdempotent
Get document metadata and its time-limited signed URL without fetching it.
Inputs: document_id (required). Returns: object
phishfort_get_document_signed_urlGet PhishFort Document Signed URLARead-onlyIdempotent
Get a time-limited document URL without fetching it.
Inputs: document_id (required). Returns: object
phishfort_get_incidentGet PhishFort IncidentBRead-onlyIdempotent
Get one PhishFort incident by id.
Inputs: incident_id (required). Returns: object
phishfort_get_limitsGet PhishFort API LimitsARead-onlyIdempotent
Return documented API limits and MCP-enforced limit choices.
Inputs: no named parameters. Returns: object
phishfort_list_capabilitiesList PhishFort CapabilitiesARead-onlyIdempotent
List supported PhishFort MCP operations and mutation approval requirements.
Inputs: no named parameters. Returns: object
phishfort_list_clientsList PhishFort ClientsARead-onlyIdempotent
List visible clients with id, search, active, limit, and offset filters.
Inputs: limit, active, offset, search, +1 more. Returns: object
phishfort_list_documentsList PhishFort DocumentsCRead-onlyIdempotent
List document metadata. doc_type accepts comma-separated documented types.
Inputs: q, page, limit, sort_by, +6 more. Returns: object
phishfort_list_incidentsList PhishFort IncidentsCRead-onlyIdempotent
List incidents. Set include_total to request paging.total.
Inputs: limit, cursor, status, to_date, +3 more. Returns: object
phishfort_list_usersList PhishFort UsersCRead-onlyIdempotent
List users with role, client, search, limit, and offset filters.
Inputs: role, limit, offset, search, +1 more. Returns: object
phishfort_list_webhooksList PhishFort WebhooksARead-onlyIdempotent
List configured webhook subscriptions.
Inputs: no named parameters. Returns: object
phishfort_plan_changePlan PhishFort ChangeB
Plan a PhishFort write. Does not mutate. Use returned approval fields on write tools.
Inputs: operation (required), params, expires_in_seconds. Returns: object
phishfort_report_incidentReport PhishFort IncidentC
Report incident for takedown or monitoring after approval.
Inputs: action (required), expires_at (required), approval_id (required), request_digest (required), +9 more. Returns: data, http_status, incident_id, remote_state, +5 more
phishfort_request_incident_actionRequest PhishFort Incident ActionBDestructive
Request takedown, monitoring, or safe review for an existing incident.
Inputs: action (required), expires_at (required), approval_id (required), incident_id (required), +3 more. Returns: data, outcome, operation, http_status, +4 more
phishfort_rotate_webhook_secretRotate PhishFort Webhook SecretCDestructive
Rotate webhook secret. One-time secret is saved locally, not returned.
Inputs: expires_at (required), webhook_id (required), approval_id (required), request_digest (required), +3 more. Returns: data, webhook_id, http_status, remote_state, +7 more
phishfort_test_webhookTest PhishFort WebhookC
Send test webhook delivery after approval.
Inputs: expires_at (required), webhook_id (required), approval_id (required), request_digest (required), +2 more. Returns: data, outcome, operation, http_status, +4 more
phishfort_update_webhookUpdate PhishFort WebhookC
Update webhook subscription after approval.
Inputs: expires_at (required), webhook_id (required), approval_id (required), request_digest (required), +6 more. Returns: data, outcome, operation, http_status, +4 more
phishfort_verify_webhook_signatureVerify PhishFort Webhook SignatureBRead-onlyIdempotent
Verify a fresh X-PhishFort-Signature using a contained local secret file.
Inputs: raw_body (required), signature (required), timestamp (required), secret_file (required). Returns: object
phishfort_whoamiPhishFort WhoamiARead-onlyIdempotent
Return authenticated PhishFort client identity.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Each tool targets a distinct operation: incident listing vs. finding by subject, document metadata vs. signed URL, etc. No two tools have overlapping purposes; descriptions clearly differentiate them.
All tools follow a consistent 'phishfort_verb_noun' pattern in snake_case, e.g., 'list_incidents', 'create_webhook', 'verify_webhook_signature'. No mixing of conventions.
23 tools is on the higher side but still reasonable for a platform covering incidents, documents, users, clients, webhooks, and system info. Each tool has a clear purpose, so the count feels justified rather than excessive.
Core incident lifecycle is covered (list, get, report, request action, add attachments/comments), but missing direct update or delete incident operations. Webhook CRUD is complete. Overall, notable gaps exist but the main workflows are functional.
Maintenance
Related MCP Connectors
One OAuth connector for your team's remote MCP servers, with Tool Packs, guardrails and logs.
Official Rewst MCP server: build, run, and debug Rewst workflows, forms, apps, and integrations.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceA Python-based MCP server that enables integration with Microsoft Security Copilot and Microsoft Sentinel, allowing users to run KQL queries, manage skillsets/plugins, and execute prompts in Security Copilot.23MIT
- AlicenseNot gradedqualityAmaintenanceAn MCP server that exposes a 60+ tool security and threat-intel stack to AI agents, enabling secret scanning, Sigma rule generation, ransomware lookup, OSINT, and deep research.1MIT
- AlicenseAqualityBmaintenanceExposes 79 cybersecurity skills and 12 orchestrator agents over MCP, with a typed 11-field output contract, an enforced resolvable-evidence gate (no verdict without a resolvable source), and human-approval gating for every mutating action. Apache-2.0, stdlib-only.85Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides MCP tools to query the phishunt.io phishing feed, enabling domain checks, brand-specific phishing lists, delta syncs, and phishing-signal analysis.1MIT