FlowCastle MCP server

Validate and apply a batch of flow-builder actions — the single write path for editing flows, blocks, variables, broadcasts, sequences, and folders. Call this directly; a separate validate_actions call beforehand is unnecessary. Broadcasts have no dedicated tool and are managed here: create_broadcast makes a DRAFT (it owns its flow via data.flowId — add the message blocks in the same batch, no separate create_flow), optionally with create_recurrence_schedule + attach_recurrence_to_broadcast for recurring; a later update_broadcast with status SCHEDULED (and scheduledAt for one-shots) is what actually schedules/sends it. The full recipe is in get_action_schema under `broadcasts`. DESTRUCTIVE: the batch may include delete_block, delete_link, delete_flow, and delete_variable. Confirm with the user before applying deletions. IRREVERSIBLE SIDE EFFECTS: run_operation starts a real operation run, which may send broadcasts to real contacts and write application variables. It cannot be undone or recalled, is not idempotent, and is available only through this tool — confirm with the user before applying a batch containing one, and never blindly retry a timed-out call that did. Validation always runs first and an invalid batch applies nothing. Execution is NOT atomic, however: if an action fails mid-batch, the actions before it stay applied and execution stops — re-read state with get_flow_context before retrying rather than blindly resending the batch. Not idempotent — resending a batch of create_* actions creates duplicates. Read get_action_schema for the action contract and get_design_guidelines before any structural edit. Returns { success, changes, errors, warnings, actionId } plus an idRemap mapping placeholder ids to the real ids that were created.

Create a new application (workspace) owned by the caller. Requires a personal API key (usr_...) — application-scoped keys cannot create applications. Seeds default flows unless skipDefaultFlows is true. Creates persistent state and is NOT idempotent: calling it twice creates two applications. Returns the new application id, which you then pass as applicationId to the other tools.

Create a contact manually — for imports or externally-sourced audiences; contacts who message a bot are created automatically. Requires the manage_broadcasts permission. platformId must be unique within the bot (duplicate fails with 409); botId may be omitted only when the application has exactly one bot. The variables map takes variable NAMES (or full folder paths when a name is ambiguous) — not ids — and unknown names fail with 422. NOT idempotent: retrying a success creates nothing new only because the duplicate platformId is rejected.

Return the action-authoring contract: every supported action kind with its required fields, the placeholder ids for referencing entities created earlier in the same batch, the `{{var|...}}` / `{{sysvar|...}}` / `{{out|...}}` reference syntax, and the creatable block types. Read-only, takes no arguments, and needs no API key. Read this before drafting any apply_actions batch — it is the schema those actions are validated against.

Return the full application-level automation context in one read-only call: every flow (with folders), connected bots, variables, sequences, and operations. This is the broad orientation call — prefer get_workspace_summary when you only need names and counts, since this response grows with workspace size. Operation graphs are hidden flows and appear only in the operations list, never in flows.

Return the complete contents of one block: block data, action configs, HTTP request bodies, custom-code files, triggers, menu payloads, and media paths. Read-only. This is the heaviest read in the API — call get_flow_context first to find the block you need rather than walking a flow block by block. Always read a block before updating it, since update_block replaces the fields you send.

Return engagement analytics for a broadcast: delivery breakdown by status plus per-message-block sent and clicked counts for its flow, over an optional date window. Read-only. Sent counts reflect messages attempted, not confirmed deliveries.

Return full details for a single broadcast: status, schedule, recurrence rule, linked flow, and delivery breakdown by status. Read-only. Call list_broadcasts first to find the broadcastId. For per-message-block engagement stats use get_broadcast_analytics instead.

Return one contact's full profile plus every contact-variable value stored for them. Read-only. Values may hold personal data; variables of type SECRET are always redacted. Call list_contacts first to find the contactId.

Return one contact's engagement history: goals they achieved and buttons they clicked, newest first, plus all-time goal totals. Read-only. This is the per-contact companion to get_broadcast_analytics (which is aggregate). Clicks are inline/menu button presses inside the bot — typed replies, commands and website visits never appear. Goals and clicks are capped separately by `limit`; goalsTruncated/clicksTruncated say when older events exist. Call list_contacts first to find the contactId.

Return the flow-design rules that validation does NOT enforce: when to split a branch into its own flow, how navigation and menus must be wired, and worked examples. Read-only, takes no arguments, and needs no API key. Read this before any structural edit (new blocks, new branches, new flows) — a batch can pass validate_actions and still be badly structured, and these rules are what catch that.

Return one flow's graph topology: its blocks, how they link, and a short summary per block. Read-only. Deliberately omits block data and action configs to stay cheap — once you know which block matters, call get_block_details for its full contents. This is the normal first step before editing an existing flow.

Return one reusable flow example by id, optionally with a complete action batch you can adapt and pass to apply_actions. Read-only, needs no API key. Call search_flow_examples first to find the id.

Return a compact index of both installed and available marketplace modules, with each module's key, versions, description, actions, and triggers. Read-only. Start here when you need a capability the core action kinds do not cover; then call get_module_details for the exact input fields of one module, and install_module to add it. Returns a summary only — action input fields and setup requirements come from get_module_details.

Return everything needed to use one module: action input fields and their types, trigger configuration, manual setup fields (credentials an operator must fill in the dashboard), and references to already-installed actions. Read-only. Call get_module_catalog first to obtain moduleKey, and call this again after install_module to read the installed action references you need when drafting actions. An unknown moduleKey does not raise — the response carries an `error` string plus `availableModules` listing valid keys and versions.

Search variable definitions by scope and keyword. Read-only. Returns { variables, total, returned, truncated } — compare returned against total to detect a cut-off result set and re-call with a higher limit. Values are withheld unless includeValues is true; variables marked secret stay redacted either way. Use the returned ids in `{{var|<id>}}` references.

Return a compact application, flow, sequence, operation, and bot summary — the cheapest way to orient in a workspace. Read-only, no side effects. Deliberately omits variables and full flow graphs: use get_variable_context for variables, get_flow_context for a flow's topology, and get_application_context when you need flows, bots, and variables together.

Install an exact marketplace module version into an application and create any missing installed-template actions. Requires the manage_automation permission. Call get_module_catalog first to select the module and version, then get_module_details after installation to inspect setup requirements and installed action references. Safe to re-run: installing a version that is already installed only fills in missing template actions rather than duplicating them. Modules with manual setup fields still need an operator to enter credentials in the dashboard before their actions will run.

List the applications this API key can access, with the caller role and the permissions it grants. Start here when using a personal API key (usr_...): every other tool needs an explicit applicationId, which this tool supplies. Read-only, takes no arguments. Returns an array of { id, name, role, permissions }; an empty array means the key is valid but belongs to no application yet.

List broadcasts in the application with status, schedule, and delivery counts. Read-only. Filters combine as AND. Note that delivery counts report messages attempted, not confirmed deliveries. Use get_broadcast_details for one broadcast's full breakdown. To CREATE or SEND a broadcast use apply_actions: create_broadcast makes a draft, update_broadcast (status SCHEDULED) schedules/sends it — see get_action_schema under `broadcasts`.

List and search contacts in the application, paginated, newest first. Read-only. Filters combine as AND; search matches name, username, email, phone, and platformId. Returns compact contact summaries without variable values — use get_contact for one contact's variables. Remember platformId is unique only per bot, so the same person talking to two bots appears as two contacts.

The reverse lookup: which contacts triggered one analytics event — achieved a goal (kind GOAL + goalKey), clicked a button (BUTTON_CLICK + blockId, optionally buttonId/buttonIndex), were sent a block (BLOCK_SENT + blockId), or received a broadcast (BROADCAST_DELIVERED + broadcastId). Read-only, paginated, ordered by each contact's most recent matching event. Runs as SQL over the event tables, so it is safe on large workspaces — prefer it over paging list_contacts and checking each one. Omitting goalKey for kind GOAL fails with the list of known goal keys, which is the cheapest way to discover them.

List the group/channel chats a telegram_mtproto userbot monitors. Read-only. The watched list is the single source of truth for which chats the userbot processes: messages from unlisted group/channel chats are dropped (fail closed) and their contacts never materialize; DMs always pass. botId may be omitted when the application has exactly one userbot.

Runs deterministic behavioural tests against flows that are ALREADY applied (compiles them to an AST and simulates a user). Call after apply_actions to verify a build; read `summary` and the failed checks, patch with apply_actions, re-run. Mutates nothing. The smoke layer runs on its own with no input: it walks every entry, taps every button, answers every input step, and reports crashes, dead buttons, unresolved placeholders, and values the bot failed to store. Pass `scenarios` to also replay specific user journeys (at most 6) — that is the only way to assert exact texts or exact stored values. Returns { passed, smoke, scenarios, summary }. `passed` is false when any check or scenario failed; a `summary` saying coverage is "none" means nothing was testable, so a green verdict there proves nothing. Nothing is sent to real users and no state is written.

Search the library of reusable flow examples covering common business cases (lead capture, onboarding, payments, reminders). Read-only, needs no API key. Returns compact matches — id, title, summary, tags — with no flow body; pass an id to get_flow_example for the full example. Calling it with no arguments returns the top examples, and a query matching nothing returns an empty list rather than an error.

Send a message to ONE contact right now, outside any flow. For reaching many contacts use a broadcast instead. Target the contact with contactId (globally unique — preferred), or with platformId (the platform-side id, e.g. the Telegram user id). platformId is NOT globally unique: it is unique only per bot, so the same Telegram user talking to two of your bots is two contacts sharing one platformId. Pass botId alongside it whenever the application has more than one bot; without botId the call succeeds only if exactly one contact in the application matches, and otherwise fails listing the candidate bots. `{{var|name}}` placeholders in the text resolve against that contact's variable context. Requires the manage_broadcasts permission. Media: pass up to 10 attachments as publicly reachable http(s) URLs; the text becomes the caption (max 1024 characters) and may be empty. Several attachments send as one album. The kind is inferred from the URL's file extension — override with type when the URL has none. Not supported for SDK bots. Delivery is asynchronous: a successful response means the bot accepted the send, not that the platform delivered it (a broken media URL surfaces in the flow logs, not here). Unsubscribed contacts are rejected. NOT idempotent and not reversible — each call sends another message to a real person, and a sent message cannot be recalled. Confirm the recipient and text with the user before calling, and never retry a timed-out call blindly.

Replace a telegram_mtproto userbot's watched-groups list — the chats it monitors. Requires the manage_settings permission. SET semantics: send the COMPLETE desired list every time (call list_watched_groups first and include existing entries you want to keep — omitting one removes it). Each entry needs a chatId (e.g. "-100…", for chats the account has joined) or a public username/t.me link; mode "joined" (default) processes a chat the account is in, "public_peek" (max 10, needs a username) polls a public chat without joining. The running userbot picks the change up within a few minutes, no restart. An empty list means "watch every joined chat" — NOT "watch nothing".

Import a telegram_mtproto userbot's existing chats as contacts — DM partners, groups, and channels — so everything the account already talks to becomes a valid send_message target without waiting for each chat to message first. Requires the manage_broadcasts permission. Reads the account's dialog list live (the userbot must be connected; large accounts can take up to a minute) and creates missing contacts; existing contacts are untouched, so the call is idempotent. Pass kinds to narrow the import (e.g. ["group","channel"] to leave personal DMs out). Does NOT change the watched-groups list. botId may be omitted when the application has exactly one userbot.

Update application-level settings (name, active state, default language, incoming-message behavior). Requires the manage_settings permission in that application. Only the fields you pass are changed; omitted fields keep their current value, so the call is idempotent. Returns the updated application.

Update a contact's profile fields and/or contact-variable values. Requires the manage_broadcasts permission. Only the fields you pass are changed — omitted fields keep their current value — so the call is idempotent. The variables map takes variable NAMES (or full folder paths when a name is ambiguous), not ids; an unknown name fails with 422 before anything is written. Variable writes propagate to the live bot immediately (the runtime's cached values are invalidated). Setting status to "unsubscribed" stops broadcasts and sequences for the contact.

Dry-run validation of a proposed batch of flow-builder actions. Mutates nothing and is safe to repeat. OPTIONAL: apply_actions runs this exact validation itself and applies nothing when invalid, so calling validate_actions first is redundant — use it only to check a draft you do not intend to apply yet. Returns the same errors and warnings apply_actions would report. Note that passing validation does not mean the design is sound; structural rules live in get_design_guidelines.