Manage automations via MCP
Use MCP when you want an AI client or external operator to inspect, create, update, or test Peach automations through tools instead of the UI.
MCP is best for structured setup and maintenance work, such as creating an automation from a plain-English brief, checking how a rule is configured, wiring a trigger to an event payload, or running a controlled test against a contact.
For pipeline-specific setup, keep using Pipeline automations. MCP can work with automation streams and triggers, but the pipeline guide is the clearer starting point for enrollment rules, stage movement, and stage lifecycle behavior.
What MCP can manage
Peach exposes automation management through account-scoped MCP tools.
Task | MCP tool |
|---|---|
List automations | peach_list_automations |
Inspect one automation | peach_get_automation |
Create an automation | peach_create_automation |
Update automation metadata or definition | peach_update_automation |
Run an automation for a contact | peach_trigger_automation |
List trigger conditions | peach_list_expressions |
List triggers on an automation | peach_list_triggers |
Create a trigger | peach_create_trigger |
Dry-run a trigger condition | peach_evaluate_trigger_condition |
Search recent events for debugging | peach_search_events |
There is also a built-in MCP resource, peach://guides/automations, that describes automation step types, payload shapes, and event payload schemas. Read it before creating or changing an automation definition.
Recommended create flow
When creating an automation through MCP, use this sequence:
- Read peach://guides/automations.
- Use peach_list_expressions to find the event condition Peach should listen for.
- Use peach_create_automation to create the automation's action definition.
- Use peach_create_trigger to connect the automation to the event.
- Use peach_evaluate_trigger_condition with a sample payload.
- Use peach_trigger_automation only when you want to run the automation for a real or test contact.
An automation created with peach_create_automation defines what Peach should do. It does not run by itself. It needs a trigger, created with peach_create_trigger, to define when it should run.
Automation definitions
MCP-created automations are definition-driven streams.
When creating one, provide:
Field | Meaning |
|---|---|
name | Human-readable automation name. |
description | Optional note for future maintainers. |
definition | Step graph with start_step and a steps map. |
playbook_kind | Use notification only for a single-template notification automation. Use advanced for anything more complex. |
status | Optional. Use draft, published, or archived. |
business_phone_number | Optional WA ID for the sending number. If omitted, Peach uses the account's first available phone number. |
If you update an automation's definition, include playbook_kind again. If a notification automation grows beyond a single-template shape, change it to advanced.
Trigger setup
Triggers connect an event to an automation.
Use peach_create_trigger with:
Field | Meaning |
|---|---|
stream_id | The automation ID, such as strm_.... |
condition | The expression name from peach_list_expressions. |
source | Optional integration name when the same condition name exists in more than one source. |
variables | Values needed by the condition. |
data_mappings | JSONPath mappings that pull fields from the event payload into the automation context. |
activate | Set to true when the trigger should start listening immediately. |
Always include a recipient mapping when the automation needs to message or operate on a contact. Without a resolved recipient, the automation will not have a contact to run against.
Example recipient mapping:
[
{
"mapping_for": "recipient",
"value": {
"phone_number": "$.contact.phone_number"
}
}
]Use additional variable mappings when steps need payload values, such as an order ID, customer name, amount, or booking date.
Testing and debugging
Use MCP testing tools before activating broad automations.
Check | Tool |
|---|---|
Confirm the automation exists and has the expected definition | peach_get_automation |
Confirm the trigger is attached to the right automation | peach_list_triggers |
Check whether a sample event payload matches | peach_evaluate_trigger_condition |
Find recent incoming events by topic | peach_search_events |
Run the automation for a known contact | peach_trigger_automation |
For API- or integration-triggered automations, test with a payload that matches the real event shape. Most MCP setup issues come from the wrong condition, missing variables, or a JSONPath that does not resolve to a phone number.
Safe operating guidance
- Start new automations in draft unless you are intentionally going live.
- Use plain names that describe the customer-facing outcome.
- Keep the UI and MCP view aligned by checking the automation in Peach after large changes.
- Do not use MCP to recreate opt-in or opt-out account setup flows.
- Prefer the visual editor for complex branching when a human needs to maintain the flow regularly.