For the complete documentation index, see llms.txt. This page is also available as markdown.
Agent workflows
Follow step-by-step MCP recipes for AI agents in Convia, from drafting an on-brand post to building a campaign, revising drafts and taking posts back.
On this page
- Rules every MCP recipe follows
- Draft a post in the brand's voice
- Put one clip out on a given day
- Find what is stuck and what is unused
- Draft a batch and send it for approval
- Turn an episode into a campaign
- Revise a draft instead of duplicating it
- Take posts back
- Choose what to make next from analytics
- Grow the idea backlog
- Gather a content program into a series
- Manage prompt templates
- Related
Agent workflows are step-by-step recipes showing how an AI agent connected to Convia Pro through MCP should combine tools to get a task right the first time, naming each tool, the arguments that matter and why it comes in that order. Every recipe follows the instructions the Convia MCP server sends on connection: read before you write, write drafts only, revise rather than duplicate, and ask the user when something is ambiguous. For every parameter and return field, see the MCP tool reference.
Rules every MCP recipe follows
- Start with
get_started. One call returns the workspaces the connection reaches, how the chosen one is set up (including its destinations, where posts send people) and which tools fit each job on its plan. Itsnext_stepssay what is missing, such as Brand Brain or a connected account, before you write anything. - Know which workspace. On a connection that reaches several workspaces, pass
workspace(an id or exact name fromlist_workspaces) on every call. If the user has not made clear which show they mean, ask. Readget_brand_contextfor each workspace you write for, and never carry one workspace's voice, facts or links into another. - Read context first. Copy written without
get_brand_contextwill not match the workspace's voice. - Verify before stating. A figure, quote or claim that
search_contentcannot find in a transcript is unverified. Do not write it as fact, and never quote clip titles or descriptions as speech. - Use ids from results. Never invent a post, clip, idea or account id.
- Prefer bare dates. Pass
scheduled_dateasYYYY-MM-DDso Convia applies the workspace's own posting time. - Drafts only. Nothing you write is published. A dated draft sits on the calendar until a person schedules it, and a campaign stays a draft until a person activates it.
submit_for_approvalis as far as you can take a post. - Never type a destination link. Pick a destination from
get_startedand write{{destination_url}}where the link goes; Convia puts the real link there. - Ask when unsure. A wrong draft costs the user more to find and fix than a question costs to ask.
Draft a post in the brand's voice
Use this recipe for one post on one platform.
get_brand_context. On a connection with several workspaces, pass onlyworkspace, such as{"workspace": "Facing Disruption"}, and pass the same value on every call that follows. This returns the voice, audience and content rules. Ifhas_brand_contextisfalse, tell the user their Brand Brain is not set up and ask whether to continue.get_prompt_templatewith{"surface": "platform", "platform": "linkedin"}(or the target platform). This shows how the workspace frames copy for that platform. Iftemplateisnull, Convia's default applies.get_text_snippets. If the post needs a standard line, such as a call to action or outro, use the snippet text exactly as stored.search_contentwith{"query": "<distinctive words>", "types": ["transcript"]}for every figure or quote you plan to use. Use the literal words, not a paraphrase. Read the surrounding passage withget_transcript(episode_id, plusstart_secondsnear the hit). Ifspeaker_nameisnull, do not name the speaker. To check several quotes from one episode at once, useverify_quotes.list_episodeswith{"guests": true, "episode_ids": ["<episode id>"]}, to spell the guest's name, job title and company correctly.list_social_platformsto get thesocial_account_idfor the target account. Pick where the post sends people from the destinationsget_startedreturned.get_schedule_settings, thenlist_postswithscheduled_afterandscheduled_beforefor the weeks you are considering (ISO 8601, such as2026-10-19T00:00:00Z), so the new post does not land on a busy day.- Write the copy yourself.
create_post:
{
"content": "<your copy>",
"social_account_id": "<id from list_social_platforms>",
"scheduled_date": "2026-10-20",
"source_idea_id": "<idea id, if the post came from an idea>",
"destination": "<destination id or name, or none>",
"tags": ["pricing", "founder-led sales"]
}
Put {{destination_url}} in content where the link goes. On a connection with several workspaces, add "workspace" to the call as well.
- Report back the
url, the resolvedscheduled_dateand anywarnings, and remind the user the post is a draft they still need to schedule, or offer to send it to their approval queue withsubmit_for_approval.
Put one clip out on a given day
Use this when the user wants a clip posted without building a campaign.
list_clipswith{"platform": "linkedin", "max_times_used": 0, "sort": "least_used"}to find clips never posted to that platform. Addepisode_idto stay within one episode, ornot_used_sinceto resurface older material.get_transcriptwith the clip'sepisode_idandclip_idto read what is said in it. Checkoffset_basisbefore citing a timestamp.get_brand_context, then write the caption.get_schedule_settingsandlist_postswithscheduled_afterandscheduled_beforeto pick the day.create_postwithsource_clip_id,social_account_idand a barescheduled_date. Supplysource_clip_idonly when you are confident the clip matches: an unknown id is an error, not a text-only post.- Read
source_clip.times_usedin the response to confirm the clip is now counted as used.
Find what is stuck and what is unused
Use this at the start of a distribution session, before writing anything new.
list_publishing_issueswith no filters. It lists posts waiting on a person, most urgent first, each with asuggested_action. Ifcountsshow more than about 25, call it again with{"group_by": "episode"}, show the user the summary, and drill into the episodes they pick withepisode_id.- Tell the user what it found. These are posts already made that are not reaching anyone: approvals about to lapse, failures, dated drafts nobody submitted, YouTube videos left private.
list_clipswith{"platform": "linkedin", "max_times_used": 0, "sort": "least_used"}(or the platform the user cares about) to find clips that never went out there. Addepisode_idto stay within one episode.- Draft from the clips worth posting, as in Put one clip out on a given day.
Draft a batch and send it for approval
Use this for many posts at once, such as a week of clips on one platform. Passing items to create_post needs Advanced MCP on the plan; without it, call create_post once per post.
find_open_slotswith theplatform, astart_date, anend_dateand thecountyou need, plusrotate([{"episode_id": "<id>", "quantity": 3}]) to spread episodes across the slots.- Write each post yourself, after reading the brand context and checking quotes with
verify_quotes. create_postwithitems,"schedule": "as_given"(using the slot dates) or"schedule": "auto"with anauto_window, and"dry_run": true. Show the user the plan, including every item infailedand its reason.- When the user agrees, call
create_postagain with the same arguments anddry_runremoved. Add"submit_for_approval": trueand anoteif the user wants the posts in their approval queue. - Report what was created and what failed, by index. Each post is a draft, or waiting for approval, until a person schedules it.
To send drafts you already made to the approval queue, call submit_for_approval with their post_ids and a note. Only drafts with an account and a future date go; the rest come back in rejected. If the workspace has approvals off, tell the user to schedule the drafts in Convia.
Turn an episode into a campaign
Use create_campaign_from_plan for a coordinated set of posts around one argument. Do not call create_post repeatedly to build a campaign. This tool needs Magic Campaign on the workspace's plan; see Magic Campaign.
list_episodesto find the episode. Checkhas_transcriptandclip_count, notstatus.list_postswith{"parent_webcast_id": "<id>"}andlist_campaignswith the sameparent_webcast_id. If posts or a campaign already exist for this episode, show the user and ask before adding another.get_brand_context.get_transcriptfor the episode. For a long episode, page withnext_start_seconds. Identify the one argument the campaign will make and the quotes that support it.list_episodeswithguests: trueand the episode's id inepisode_ids, to name the guest correctly.list_clipswith{"episode_id": "<id>", "sort": "least_used"}to find clips for clip-backed posts.get_schedule_settingsandlist_postswithscheduled_afterandscheduled_beforefor the campaign window.- Write the spine (
through_lineandauthority_objective) and every post. Keep to one idea per campaign: for a month covering several arguments, make one call per argument with dates that do not overlap. create_campaign_from_planwithparent_webcast_id, bare dates inside a window of 90 days or less, and at most 40 posts on at most 8 platforms. For a post that needs an asset you cannot supply, leavecontentas""if you have no copy, setneeded_assetto describe it, and addasset_instructionswith the full brief.- Read the response. Tell the user how many posts were created, list each entry in
gaps(those posts are flagged with your brief), and pass on every warning, such as a platform with no connected account. Remind them to review the campaign and activate it in Campaigns.
A source_clip_id that does not match a clip is discarded and that post is held as a gap, with a warning. That is the safe outcome, not an error.
Revise a draft instead of duplicating it
When the user asks to change something that already exists, find it and update it.
- Find the post. Use
list_postswithbody_containsfor a phrase in the caption, orparent_webcast_idfor an episode's posts, andstatussuch as["draft", "pending_approval", "scheduled"]. get_postto read the full body (post_idsreads up to 20 at once).contentreplaces the whole body, so start from what is there.update_postwithpost_idand only the fields that change. For a small fix, passfindandreplace_withinstead ofcontent: the exact text, which must appear once unlessreplace_allistrue.- Read the response:
approval_reset: truemeans the post was waiting for approval and is back in draft, so the edit is reviewed. Tell the user.post_immutablemeans the post is published or approved. Tell the user to change it in the app.- A scheduled post stays scheduled after an edit. If the user wanted it off the calendar, use
remove_postswithaction: "unschedule".
Ideas and scripts work the same way: list_ideas then get_idea then update_idea, or list_scripts then get_script then update_script. An idea is never deleted: set its status to archived.
Take posts back
Pick the action by what the user means. Editing the text is not a way to stop a post.
| The user means | Call |
|---|---|
| "Stop this going out, I'll decide later" | remove_posts with action: "unschedule": back to draft, scheduled date cleared |
| "This should never have been made" | remove_posts with action: "trash": moved to Trash, restorable by a person. Unschedule first if it is scheduled |
| "Fix a typo" | update_post: the post stays scheduled |
- Find the posts with
list_posts, for examplestatus: ["scheduled"]withbody_containsorparent_webcast_id, orscheduled_afterandscheduled_beforefor a date window. - Show the user the list and confirm before changing anything.
- Call
remove_postswith theaction, up to 25post_idsand a shortreason, such as "wrong guest named in the caption". The reason goes to the workspace's MCP audit log. For more than 25 posts, split into several calls. - To trash scheduled posts, call
remove_postswithaction: "unschedule"first, then again withaction: "trash"and the same ids. - Read
updated,unchangedandrefused.unchangedmeans the post was already in that state. For each refused post, pass on the reason: a published post must be taken down on the platform itself, and an approved post must be handled in the app.
Unscheduling returns each post's previous_scheduled_date, so you can restore the date later with update_post. The post then stays a draft on the calendar until a person schedules it.
Choose what to make next from analytics
The analytics tools in this recipe need Advanced Analytics on the plan. A null metric means not collected yet, never zero, and views, impressions and reach are never added together.
get_startedwithmeasurement: truefirst. It says what the workspace can measure, so a conversion that was never set up is not read as zero. Pass what it says is missing on to the user.query_post_performancewith{"order_by": "engagements", "min_age_hours": 48}, optionally filtered byplatformorcampaign, to rank posts in one call rather than reading posts one at a time. For one post, passpost_id, and addhistory: truefor its readings over time.get_episode_performancerolls up everything made from an episode or campaign.get_site_trafficwith{"view": "from_posts", "group_by": "post"}(or"campaign") to see which posts sent people to the workspace's own website.get_audience_growthto see whether followers grew over the same period.get_search_querieswith{"position_min": 8, "position_max": 20, "sort": "impressions"}for searches where the site is close to page one, or{"branded": "only"}to track how often people search for the brand by name.search_contenton the winning topics to find source material, andlist_clipswithnot_used_sinceto find clips worth resurfacing.list_ideaswithqueryto check the backlog for the same idea, thencreate_ideawith the evidence innotes: the numbers, the source episode and the angle.
See Analytics and Website analytics for what each figure means.
Grow the idea backlog
list_ideaswithqueryfor the topic, andget_ideaon close matches. The user may already have had the thought.create_ideafor genuinely new ideas. Put the angle, the audience, the raw material (episode, timestamp, clip) and any overlap with existing ideas innotes, so a later session can act on it without redoing the thinking.- When an idea has been used or dropped,
update_ideawith{"status": "archived"}.
See Ideas & scripts.
Gather a content program into a series
Use this when the user wants related ideas, scripts, episodes, clips, posts or media kept together, such as every issue of a newsletter. The series tools need a plan that includes Series.
list_seriesto see whether a fitting series exists. Prefer adding to it over making a near-duplicate.- If none fits,
create_serieswith anameand a one-linedescription. - Find the items with the usual reads:
list_ideas,list_scripts,list_episodes,list_clips,list_postsorlist_media. add_to_serieswith theseries_idand up to 200items, each{ "kind": "post", "id": "<post id>" }. An article is apost. Reportadded,already_inand anything inskipped_items.get_seriesto show the user what the series now holds.
To take an item out, call add_to_series with the same items and "remove": true; the item itself is not changed. Rules that add new items automatically, Create campaign from a series and series results are set up or read in Convia, not through MCP.
Manage prompt templates
An agent can read every prompt template and stage a new version, but it cannot change what Convia generates with. A person makes a staged version live. Staging needs Advanced AI on the plan.
list_prompt_templatesto see what exists.resolves_as: "default"marks the live template for each content type.get_prompt_templatewithtemplate_id, or with{"surface": "content", "content_type": "article"}for the live one. Notevariables_used: keep every{placeholder}in your revision.get_brand_context, so the template does not repeat rules Convia already supplies. Some generators add less brand context than others, so keep essential voice guidance in the template.upsert_prompt_templatewithcontent_type, a clearnameand the fullprompt_template. Addtemplate_idonly to revise an alternative you staged earlier; the live default cannot be edited.- Tell the user the version is saved but not live, and that a manager can make it the default in Brand Brain → Content instructions.
On plans with Prompt Learning, an agent can also stage a draft of a per-platform social prompt: upsert_prompt_template with {"surface": "platform", "platform": "linkedin"}, a name, the full system_prompt and a change_note citing the evidence. It comes back with a word diff against the live prompt, and a person reviews it in Brand Brain → Platform instructions. Without Prompt Learning, give the user the proposed text to paste in there. See How AI uses your brand.
Related
- MCP tool reference: exact parameters, limits and errors for every tool.
- Connect an AI assistant (MCP): set up the connection these recipes use.
- MCP access, permissions & audit: what an agent is allowed to do, and the Activity log.
- Campaigns: what happens to a draft campaign after the agent hands it over.