Skip to content
Convia ProDocs

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.

Last updated
On this page

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. Its next_steps say 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 from list_workspaces) on every call. If the user has not made clear which show they mean, ask. Read get_brand_context for 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_context will not match the workspace's voice.
  • Verify before stating. A figure, quote or claim that search_content cannot 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_date as YYYY-MM-DD so 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_approval is as far as you can take a post.
  • Never type a destination link. Pick a destination from get_started and 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.

  1. get_brand_context. On a connection with several workspaces, pass only workspace, such as {"workspace": "Facing Disruption"}, and pass the same value on every call that follows. This returns the voice, audience and content rules. If has_brand_context is false, tell the user their Brand Brain is not set up and ask whether to continue.
  2. get_prompt_template with {"surface": "platform", "platform": "linkedin"} (or the target platform). This shows how the workspace frames copy for that platform. If template is null, Convia's default applies.
  3. 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.
  4. search_content with {"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 with get_transcript (episode_id, plus start_seconds near the hit). If speaker_name is null, do not name the speaker. To check several quotes from one episode at once, use verify_quotes.
  5. list_episodes with {"guests": true, "episode_ids": ["<episode id>"]}, to spell the guest's name, job title and company correctly.
  6. list_social_platforms to get the social_account_id for the target account. Pick where the post sends people from the destinations get_started returned.
  7. get_schedule_settings, then list_posts with scheduled_after and scheduled_before for the weeks you are considering (ISO 8601, such as 2026-10-19T00:00:00Z), so the new post does not land on a busy day.
  8. Write the copy yourself.
  9. create_post:
json
{
  "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.

  1. Report back the url, the resolved scheduled_date and any warnings, and remind the user the post is a draft they still need to schedule, or offer to send it to their approval queue with submit_for_approval.

Put one clip out on a given day

Use this when the user wants a clip posted without building a campaign.

  1. list_clips with {"platform": "linkedin", "max_times_used": 0, "sort": "least_used"} to find clips never posted to that platform. Add episode_id to stay within one episode, or not_used_since to resurface older material.
  2. get_transcript with the clip's episode_id and clip_id to read what is said in it. Check offset_basis before citing a timestamp.
  3. get_brand_context, then write the caption.
  4. get_schedule_settings and list_posts with scheduled_after and scheduled_before to pick the day.
  5. create_post with source_clip_id, social_account_id and a bare scheduled_date. Supply source_clip_id only when you are confident the clip matches: an unknown id is an error, not a text-only post.
  6. Read source_clip.times_used in 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.

  1. list_publishing_issues with no filters. It lists posts waiting on a person, most urgent first, each with a suggested_action. If counts show more than about 25, call it again with {"group_by": "episode"}, show the user the summary, and drill into the episodes they pick with episode_id.
  2. 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.
  3. list_clips with {"platform": "linkedin", "max_times_used": 0, "sort": "least_used"} (or the platform the user cares about) to find clips that never went out there. Add episode_id to stay within one episode.
  4. 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.

  1. find_open_slots with the platform, a start_date, an end_date and the count you need, plus rotate ([{"episode_id": "<id>", "quantity": 3}]) to spread episodes across the slots.
  2. Write each post yourself, after reading the brand context and checking quotes with verify_quotes.
  3. create_post with items, "schedule": "as_given" (using the slot dates) or "schedule": "auto" with an auto_window, and "dry_run": true. Show the user the plan, including every item in failed and its reason.
  4. When the user agrees, call create_post again with the same arguments and dry_run removed. Add "submit_for_approval": true and a note if the user wants the posts in their approval queue.
  5. 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.

  1. list_episodes to find the episode. Check has_transcript and clip_count, not status.
  2. list_posts with {"parent_webcast_id": "<id>"} and list_campaigns with the same parent_webcast_id. If posts or a campaign already exist for this episode, show the user and ask before adding another.
  3. get_brand_context.
  4. get_transcript for the episode. For a long episode, page with next_start_seconds. Identify the one argument the campaign will make and the quotes that support it.
  5. list_episodes with guests: true and the episode's id in episode_ids, to name the guest correctly.
  6. list_clips with {"episode_id": "<id>", "sort": "least_used"} to find clips for clip-backed posts.
  7. get_schedule_settings and list_posts with scheduled_after and scheduled_before for the campaign window.
  8. Write the spine (through_line and authority_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.
  9. create_campaign_from_plan with parent_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, leave content as "" if you have no copy, set needed_asset to describe it, and add asset_instructions with the full brief.
  10. 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.

  1. Find the post. Use list_posts with body_contains for a phrase in the caption, or parent_webcast_id for an episode's posts, and status such as ["draft", "pending_approval", "scheduled"].
  2. get_post to read the full body (post_ids reads up to 20 at once). content replaces the whole body, so start from what is there.
  3. update_post with post_id and only the fields that change. For a small fix, pass find and replace_with instead of content: the exact text, which must appear once unless replace_all is true.
  4. Read the response:
    • approval_reset: true means the post was waiting for approval and is back in draft, so the edit is reviewed. Tell the user.
    • post_immutable means 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_posts with action: "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
  1. Find the posts with list_posts, for example status: ["scheduled"] with body_contains or parent_webcast_id, or scheduled_after and scheduled_before for a date window.
  2. Show the user the list and confirm before changing anything.
  3. Call remove_posts with the action, up to 25 post_ids and a short reason, 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.
  4. To trash scheduled posts, call remove_posts with action: "unschedule" first, then again with action: "trash" and the same ids.
  5. Read updated, unchanged and refused. unchanged means 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.

  1. get_started with measurement: true first. 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.
  2. query_post_performance with {"order_by": "engagements", "min_age_hours": 48}, optionally filtered by platform or campaign, to rank posts in one call rather than reading posts one at a time. For one post, pass post_id, and add history: true for its readings over time. get_episode_performance rolls up everything made from an episode or campaign.
  3. get_site_traffic with {"view": "from_posts", "group_by": "post"} (or "campaign") to see which posts sent people to the workspace's own website.
  4. get_audience_growth to see whether followers grew over the same period.
  5. get_search_queries with {"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.
  6. search_content on the winning topics to find source material, and list_clips with not_used_since to find clips worth resurfacing.
  7. list_ideas with query to check the backlog for the same idea, then create_idea with the evidence in notes: the numbers, the source episode and the angle.

See Analytics and Website analytics for what each figure means.

Grow the idea backlog

  1. list_ideas with query for the topic, and get_idea on close matches. The user may already have had the thought.
  2. create_idea for genuinely new ideas. Put the angle, the audience, the raw material (episode, timestamp, clip) and any overlap with existing ideas in notes, so a later session can act on it without redoing the thinking.
  3. When an idea has been used or dropped, update_idea with {"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.

  1. list_series to see whether a fitting series exists. Prefer adding to it over making a near-duplicate.
  2. If none fits, create_series with a name and a one-line description.
  3. Find the items with the usual reads: list_ideas, list_scripts, list_episodes, list_clips, list_posts or list_media.
  4. add_to_series with the series_id and up to 200 items, each { "kind": "post", "id": "<post id>" }. An article is a post. Report added, already_in and anything in skipped_items.
  5. get_series to 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.

  1. list_prompt_templates to see what exists. resolves_as: "default" marks the live template for each content type.
  2. get_prompt_template with template_id, or with {"surface": "content", "content_type": "article"} for the live one. Note variables_used: keep every {placeholder} in your revision.
  3. 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.
  4. upsert_prompt_template with content_type, a clear name and the full prompt_template. Add template_id only to revise an alternative you staged earlier; the live default cannot be edited.
  5. 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.