MCP tools for lead alerts

These tools manage lead alerts and read their results. Rule changes take effect immediately: there's no draft and nothing to publish. The lead alerts reference explains how visits are checked and what each action does.

MCP lead alert access

Every tool accepts an optional string project_id and follows the shared MCP authorization and project-selection rules. Lead alerts are on every plan. A project whose plan has lapsed can't use them until it's reactivated, and every tool returns Lead alerts are not available on this project until its plan is reactivated in the dashboard.

Rules and checked visits are addressed by string IDs (rule_id and visit_id). Results can include email addresses, contact tags and fields, and browsing history. Examples are illustrative and were not executed. They show tools/call parameters and decoded response payloads.

list-lead-alert-rules

Read-only. Takes only project_id. Returns:

• live_checking: whether visits are being checked and actions run in this environment.
• how_it_works: a sentence-level summary of when visits are checked and when a rule takes effect.
• alert_confidence: the confidence a match needs, such as 0.8.
• max_rules: 10.
• rules: each rule's rule_id, name, description, enabled, actions, and breadth.
• usage: this billing month's allowance of distinct alerted people, how many it has used, how many alerts are held at the limit, resets_at, included_by_plan, bought, and free_until (the end of the free launch period, or null after it).

breadth is the rule's reach estimate, or null if it was never estimated. Its status is pending for a few minutes after the rule is created or reworded, then ready or failed (with error). A ready estimate has monthly_people, the volume and price_monthly_cents that would cover them, and within_included when the plan already covers them. people_capped: true means the sample hit its limit, so the estimate is a floor.

The tools can't change the project's lead alerts volume. That's done in the dashboard's Plan & billing; see alerted leads and volume.

{"name":"list-lead-alert-rules","arguments":{"project_id":"123456789"}}

Actions use the shapes below. Email platform actions include the platform they were set up for.

Tag, list, and field IDs come from get-integration-data in the integration tools. These actions only change a person who is already a contact in the connected email platform; they never create one. An action the platform can't run, or one set up for a different platform, is refused with the reason.

create-lead-alert-rule

A project can have up to 10 rules. The rule applies to visits checked after it's created. Returns {rule}.

{"name":"create-lead-alert-rule","arguments":{"project_id":"123456789","name":"Ready to buy","description":"People who aren't customers yet, looking at pricing or coming back several times in a week.","actions":[{"type":"email","to":"sales@example.com"}]}}

update-lead-alert-rule

Requires rule_id and at least one of name, description, enabled, or actions, with the same limits as create. enabled: false pauses the rule without deleting it. actions replaces every action the rule has, so start from the rule's current actions; keep each existing email platform action's platform, and leave it out for a new one. An empty list leaves matches only listed. New wording applies to visits checked from then on. Returns {rule}.

delete-lead-alert-rule

Requires rule_id. Deletes the rule immediately; there's no undo. Visits it already checked keep its verdicts. Returns {"deleted":true,"rule_id":"..."}.

list-lead-alerts

Read-only. Lists checked visits, newest first.

{"name":"list-lead-alerts","arguments":{"project_id":"123456789","limit":20}}

The response has live_checking, total, limit, offset, has_more, and visits. Each visit has visit_id, email, visit_ended_at, alert, summary, pageviews, arrived_from, test_run, held, nullable released_at, nullable skipped, nullable emailed_at, verdicts, and actions. A verdict has rule_id, rule_name, verdict (match, no_match, or null), confidence, alerted, and repeat_not_resent. An action result has rule_id, type, status (done, skipped, or failed), and detail. test_run: true marks a visit found by replaying past traffic; no actions ran for it.

held: true marks an alert held at the project's monthly limit: it's listed, but no email, write-up, or actions ran, and it isn't counted. released_at is when a held alert was sent after the limit rose. skipped: "pages" means no rule could match the visit's pages, so the email platform contact wasn't read.

get-lead-alert

Read-only. Requires visit_id from list-lead-alerts. Returns everything in the list entry plus visit_started_at, facts (the pages with titles and time on each, arrival, network, earlier activity, segments, and email platform contact the rules were judged on), insights, and insights_error.

{"name":"get-lead-alert","arguments":{"project_id":"123456789","visit_id":"987654321"}}

An unknown ID returns Checked visit '<id>' not found. Use list-lead-alerts to see visit IDs.