Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(workflows): route MCP agents through messaging setup first (#118495)

Meikel Ratz4e1c248f608a
diff --git a/products/workflows/mcp/tools.yaml b/products/workflows/mcp/tools.yaml
index 31a919a6b535..715aac0a1788 100644
--- a/products/workflows/mcp/tools.yaml
+++ b/products/workflows/mcp/tools.yaml
@@ -53,10 +53,11 @@ tools:
enrich_url: '{id}/workflow'
title: Create workflow
description: >
- Create a workflow. It is created as a draft and does NOT run until enabled: test it with workflows-test-run
- first, then enable (workflows-enable) only with the user's explicit approval — from then on it runs on real
- people, and further content edits stage as a draft you must publish (workflows-publish) to take effect.
- Provide an actions array with exactly one type='trigger' (config.type:
+ Create a workflow. Before a project's first email, SMS or push workflow, call workflows-setup-status when it
+ is available, so the user knows what blocks sending. It is created as a draft and does NOT run until
+ enabled: test it with workflows-test-run first, then enable (workflows-enable) only with the user's explicit
+ approval — from then on it runs on real people, and further content edits stage as a draft you must publish
+ (workflows-publish) to take effect. Provide an actions array with exactly one type='trigger' (config.type:
event|webhook|manual|batch|schedule|tracking_pixel) plus action nodes
(function/function_email/function_sms/function_push, delay, conditional_branch, wait_until_condition, ...)
connected by edges. A webhook or manual trigger also needs config.template_id set to the literal
diff --git a/products/workflows/skills/building-workflows/SKILL.md b/products/workflows/skills/building-workflows/SKILL.md
index 8e634678eb61..98a08ea6a923 100644
--- a/products/workflows/skills/building-workflows/SKILL.md
+++ b/products/workflows/skills/building-workflows/SKILL.md
@@ -1,6 +1,6 @@
---
name: building-workflows
-description: 'Build, edit, test, enable, and monitor PostHog workflows over MCP. Author the action/edge graph so it runs and opens cleanly in the visual editor, then change drafts surgically with patch operations. Use when asked to build, set up, automate, change, fix, or debug a workflow, campaign, broadcast, drip sequence, or event-triggered automation in the workflows product.'
+description: 'Build, edit, test, enable, and monitor PostHog workflows over MCP. Author the action/edge graph so it runs and opens cleanly in the visual editor, then change drafts surgically with patch operations. Use when asked to build, set up, automate, change, fix, or debug a workflow, campaign, broadcast, drip sequence, or event-triggered automation in the workflows product, including first-time messaging setup (email channel, sending domain, frequency cap) before the first workflow.'
---
# Building workflows
@@ -9,6 +9,12 @@ A PostHog **workflow** is a directed graph: a list of **action nodes** (`actions
The single biggest failure mode is **getting the graph JSON structurally wrong**. The backend stores `actions`/`config` as loose JSON, but the visual editor parses every node against a strict schema, so a malformed node saves but then **breaks the editor view** for the whole workflow. Before composing or editing any graph, read [references/graph-schema.md](references/graph-schema.md). It is the contract; do not improvise node shapes from these examples alone.
+## Before the first messaging workflow
+
+When the user asks to set up workflows or messaging, or asks for an email, SMS or push workflow in a project that may not send yet, call `workflows-setup-status` before composing anything. It says which setup steps are open and links each one in the app. Walk the user through the open steps, set the sending rules, then offer suggested workflows. Read [references/onboarding.md](references/onboarding.md) for the flow and the defaults to recommend.
+
+Skip this for automations that only post to Slack or call webhooks: they need no email setup. If `workflows-setup-status` is not available, go straight to the lifecycle below.
+
## The lifecycle
Work the workflow through these stages. Don't jump straight to enabling it.
diff --git a/products/workflows/skills/building-workflows/references/onboarding.md b/products/workflows/skills/building-workflows/references/onboarding.md
new file mode 100644
index 000000000000..301eccd37ba5
--- /dev/null
+++ b/products/workflows/skills/building-workflows/references/onboarding.md
@@ -0,0 +1,62 @@
+# Onboarding a project to messaging
+
+Use this when a project needs messaging setup before its first email, SMS or push workflow.
+The goal is the same result as the in-app setup wizard, with as few messages as possible: say what is missing once, recommend a default for each choice, and ask for one confirmation.
+
+## 1. Check the setup, and start the suggestions
+
+Call `workflows-setup-status`.
+It returns every setup step with `done`, a `next_step` and an `app_url`, plus `ready_to_send_email`, `email_sending_paused` and `data_suggestions_available`.
+
+The email steps only matter for workflows that send email.
+An SMS or push workflow sends through its own channel, so do not ask for the email channel or domain when the workflow has no email step.
+
+Check `email_sending_paused` first, even when every step is done.
+When it is true and the workflow sends email, tell the user that email sending is paused for the project and that they need to contact PostHog support. The workflow can still be drafted, but its emails will not send.
+
+If every step is done and sending is not paused, skip to the lifecycle in [SKILL.md](../SKILL.md).
+
+If `data_suggestions_available` is true, call `workflows-data-suggestions-list` now.
+It starts a background run, so the suggestions are ready by the time setup is done.
+
+## 2. Say what is missing, in one message
+
+List only the open steps, in order, with a short line each.
+Group them by who does them:
+
+- **Steps the user does in the app.** The email channel and the sending domain need a domain the user controls and DNS records at their DNS provider. Share each step's `app_url`. Do not try to do these steps over MCP.
+- **Steps you can do now.** The sending rules. Recommend the defaults below and ask the user to confirm.
+- **Optional steps.** Opt-out categories and an email template. Mention them, and share the `app_url`, but do not block on them.
+
+### Sending rules to recommend
+
+Read the current values with `workflows-sending-rules-get` first.
+
+- **Frequency cap.** When there is no cap, recommend at most 1 marketing message every 2 days (`marketing_frequency_cap_max_messages: 1`, `marketing_frequency_cap_window_days: 2`). Offer a different cap or no cap if the user wants one. Transactional messages are never capped.
+- **Engagement events.** Recommend turning `capture_workflows_engagement_events` on, so sends, opens, clicks and bounces show up as events. Say that these events count toward the project's event usage.
+- **Tracking consent.** Leave `email_tracking_consent_mode` as it is unless the user asks. If they mention GDPR or consent, explain `opt_out` and `opt_in`.
+
+A cap the project already has stays as it is. Do not replace it with the recommendation.
+
+## 3. Apply what the user confirmed
+
+Call `workflows-sending-rules-update` with only the fields the user agreed to.
+It needs a project admin. If it returns a permission error, tell the user that a project admin has to set the sending rules, and move on.
+
+## 4. Offer a first workflow
+
+When `data_suggestions_available` is true, read the suggestions with `workflows-data-suggestions-get` (or the result from step 1).
+Show up to three, each with its name, trigger event and one line on why it fits.
+Offer to start from scratch as well.
+
+When the user picks a suggestion, build it with `workflows-data-suggestions-create`.
+It saves a draft. Hand over to the lifecycle in [SKILL.md](../SKILL.md): test it, then enable it only after the user says so.
+
+When suggestions are not available, ask what the workflow should do and build it from the lifecycle.
+
+## When the user skips the app steps
+
+A draft can exist before the domain is verified.
+If the workflow has an email step and `ready_to_send_email` is false, say clearly that its emails will not send yet, and share the `app_url` again.
+When `email_sending_paused` is true, the domain is fine but sending is paused for the project, so tell the user to contact PostHog support instead.
+Call `workflows-setup-status` again when the user says they finished a step.
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index 618bb28e052c..020afcef0f0c 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -14922,7 +14922,7 @@
"feature_flag": "engineering-analytics"
},
"workflows-create": {
- "description": "Create a workflow. It is created as a draft and does NOT run until enabled: test it with workflows-test-run first, then enable (workflows-enable) only with the user's explicit approval — from then on it runs on real people, and further content edits stage as a draft you must publish (workflows-publish) to take effect. Provide an actions array with exactly one type='trigger' (config.type: event|webhook|manual|batch|schedule|tracking_pixel) plus action nodes (function/function_email/function_sms/function_push, delay, conditional_branch, wait_until_condition, ...) connected by edges. A webhook or manual trigger also needs config.template_id set to the literal 'template-source-webhook', and a tracking_pixel trigger needs 'template-source-webhook-pixel'; without it the create is rejected with 'Template not found' against the trigger node. Read the building-workflows skill for node shapes before composing: a node that mismatches the per-type schema saves but breaks the visual editor. Two traps that save but break: (1) a conditional_branch condition needs a 'filters' wrapper — {filters:{properties:[...]}}, not {properties:[...]} on the condition; omitting it passes save but the editor flags it and the branch won't evaluate your condition. (2) Never hand-author bytecode anywhere; send properties/hash and the server compiles it. For '$account_custom_property_changed', current_value is polymorphic. To target multiple property types, repeat that event in filters.events: nested properties in each event entry are ANDed, while event entries are ORed. For example, one entry can pair property_name=Plan with current_value=enterprise and another can pair property_name=Seats with current_value greater than 5; do not put one shared current_value condition in top-level properties. A 'batch' trigger broadcasts to an audience (config.filters.properties: person-property conditions and/or cohort references), one run per matching person, and does NOT fire on enable: dispatch with workflows-run-batch or attach a schedule with workflows-schedule-create. A 'schedule' trigger has no audience: it runs once per occurrence, so attach its cadence with workflows-schedule-create and skip the audience preview. Behavioral targeting ('did event X at least N times over the last M days') is unsupported; reject it and explain why.",
+ "description": "Create a workflow. Before a project's first email, SMS or push workflow, call workflows-setup-status when it is available, so the user knows what blocks sending. It is created as a draft and does NOT run until enabled: test it with workflows-test-run first, then enable (workflows-enable) only with the user's explicit approval — from then on it runs on real people, and further content edits stage as a draft you must publish (workflows-publish) to take effect. Provide an actions array with exactly one type='trigger' (config.type: event|webhook|manual|batch|schedule|tracking_pixel) plus action nodes (function/function_email/function_sms/function_push, delay, conditional_branch, wait_until_condition, ...) connected by edges. A webhook or manual trigger also needs config.template_id set to the literal 'template-source-webhook', and a tracking_pixel trigger needs 'template-source-webhook-pixel'; without it the create is rejected with 'Template not found' against the trigger node. Read the building-workflows skill for node shapes before composing: a node that mismatches the per-type schema saves but breaks the visual editor. Two traps that save but break: (1) a conditional_branch condition needs a 'filters' wrapper — {filters:{properties:[...]}}, not {properties:[...]} on the condition; omitting it passes save but the editor flags it and the branch won't evaluate your condition. (2) Never hand-author bytecode anywhere; send properties/hash and the server compiles it. For '$account_custom_property_changed', current_value is polymorphic. To target multiple property types, repeat that event in filters.events: nested properties in each event entry are ANDed, while event entries are ORed. For example, one entry can pair property_name=Plan with current_value=enterprise and another can pair property_name=Seats with current_value greater than 5; do not put one shared current_value condition in top-level properties. A 'batch' trigger broadcasts to an audience (config.filters.properties: person-property conditions and/or cohort references), one run per matching person, and does NOT fire on enable: dispatch with workflows-run-batch or attach a schedule with workflows-schedule-create. A 'schedule' trigger has no audience: it runs once per occurrence, so attach its cadence with workflows-schedule-create and skip the audience preview. Behavioral targeting ('did event X at least N times over the last M days') is unsupported; reject it and explain why.",
"category": "Workflows",
"feature": "workflows",
"summary": "Create workflow",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 770a97830394..f2bdaa9bc9bd 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -15625,7 +15625,7 @@
}
},
"workflows-create": {
- "description": "Create a workflow. It is created as a draft and does NOT run until enabled: test it with workflows-test-run first, then enable (workflows-enable) only with the user's explicit approval — from then on it runs on real people, and further content edits stage as a draft you must publish (workflows-publish) to take effect. Provide an actions array with exactly one type='trigger' (config.type: event|webhook|manual|batch|schedule|tracking_pixel) plus action nodes (function/function_email/function_sms/function_push, delay, conditional_branch, wait_until_condition, ...) connected by edges. A webhook or manual trigger also needs config.template_id set to the literal 'template-source-webhook', and a tracking_pixel trigger needs 'template-source-webhook-pixel'; without it the create is rejected with 'Template not found' against the trigger node. Read the building-workflows skill for node shapes before composing: a node that mismatches the per-type schema saves but breaks the visual editor. Two traps that save but break: (1) a conditional_branch condition needs a 'filters' wrapper — {filters:{properties:[...]}}, not {properties:[...]} on the condition; omitting it passes save but the editor flags it and the branch won't evaluate your condition. (2) Never hand-author bytecode anywhere; send properties/hash and the server compiles it. For '$account_custom_property_changed', current_value is polymorphic. To target multiple property types, repeat that event in filters.events: nested properties in each event entry are ANDed, while event entries are ORed. For example, one entry can pair property_name=Plan with current_value=enterprise and another can pair property_name=Seats with current_value greater than 5; do not put one shared current_value condition in top-level properties. A 'batch' trigger broadcasts to an audience (config.filters.properties: person-property conditions and/or cohort references), one run per matching person, and does NOT fire on enable: dispatch with workflows-run-batch or attach a schedule with workflows-schedule-create. A 'schedule' trigger has no audience: it runs once per occurrence, so attach its cadence with workflows-schedule-create and skip the audience preview. Behavioral targeting ('did event X at least N times over the last M days') is unsupported; reject it and explain why.",
+ "description": "Create a workflow. Before a project's first email, SMS or push workflow, call workflows-setup-status when it is available, so the user knows what blocks sending. It is created as a draft and does NOT run until enabled: test it with workflows-test-run first, then enable (workflows-enable) only with the user's explicit approval — from then on it runs on real people, and further content edits stage as a draft you must publish (workflows-publish) to take effect. Provide an actions array with exactly one type='trigger' (config.type: event|webhook|manual|batch|schedule|tracking_pixel) plus action nodes (function/function_email/function_sms/function_push, delay, conditional_branch, wait_until_condition, ...) connected by edges. A webhook or manual trigger also needs config.template_id set to the literal 'template-source-webhook', and a tracking_pixel trigger needs 'template-source-webhook-pixel'; without it the create is rejected with 'Template not found' against the trigger node. Read the building-workflows skill for node shapes before composing: a node that mismatches the per-type schema saves but breaks the visual editor. Two traps that save but break: (1) a conditional_branch condition needs a 'filters' wrapper — {filters:{properties:[...]}}, not {properties:[...]} on the condition; omitting it passes save but the editor flags it and the branch won't evaluate your condition. (2) Never hand-author bytecode anywhere; send properties/hash and the server compiles it. For '$account_custom_property_changed', current_value is polymorphic. To target multiple property types, repeat that event in filters.events: nested properties in each event entry are ANDed, while event entries are ORed. For example, one entry can pair property_name=Plan with current_value=enterprise and another can pair property_name=Seats with current_value greater than 5; do not put one shared current_value condition in top-level properties. A 'batch' trigger broadcasts to an audience (config.filters.properties: person-property conditions and/or cohort references), one run per matching person, and does NOT fire on enable: dispatch with workflows-run-batch or attach a schedule with workflows-schedule-create. A 'schedule' trigger has no audience: it runs once per occurrence, so attach its cadence with workflows-schedule-create and skip the audience preview. Behavioral targeting ('did event X at least N times over the last M days') is unsupported; reject it and explain why.",
"category": "Workflows",
"feature": "workflows",
"summary": "Create workflow",