MCP tool reference

The Convia Pro MCP server exposes 38 tools that read and write one workspace's content. Each entry gives exact parameters, limits, returns and side effects. To connect first, see Connect an AI assistant (MCP).

Protocol and conventions

The Convia MCP server speaks Streamable HTTP, statelessly: each request is an HTTP POST of a JSON-RPC 2.0 message to your MCP URL, and each response is application/json. There is no session id and no event stream.

A successful tools/call returns one text item holding the result as JSON. Rules for every tool:

• One workspace. Every call acts on the workspace in the URL. An id from another workspace is treated as unknown.
• Nothing publishes. No tool publishes, schedules a post to go out, approves, or queues for approval. New posts are drafts.
• Ids are UUIDs from earlier tool results. Never invent one.
• Post dates. scheduled_date takes a bare YYYY-MM-DD (preferred), which resolves to the workspace's default posting time for that platform and weekday, or ISO 8601 with an explicit offset such as 2026-11-03T14:30:00Z. No offset is rejected. A time more than 15 minutes past is refused.
• Trashed posts, episodes and clips are left out of lists and searches.
• No AI credits. MCP runs no AI generation inside Convia and spends no AI credits.

Paging

list_posts, list_clips, list_ideas and list_scripts return total_count, returned, offset, limit, has_more and next_offset. Pass next_offset as offset until has_more is false. Maximum offset: 10,000. list_episodes, list_scheduled_posts and list_campaigns take only limit and return count (total matching) and returned.

Server instructions

The initialize result returns these instructions under instructions. They apply to every tool.

Convia is the durable memory for this workspace's content. Read from it before authoring
anything, and write finished work back to it, so that work survives the session it was made in.

The standard order for authoring is: get_brand_context for voice and audience,
get_prompt_template for the format, get_text_snippets for the workspace's own standard blocks,
search_content on type transcript to verify any claim, then list_scheduled_posts and
get_schedule_settings before choosing a date. Author the copy yourself, then write it back with
create_post or create_campaign_from_plan.

Nothing written through this server is published. Posts are created as drafts, and a draft on
the calendar still needs a human to schedule it.

Anything you can create here you can also read back and revise: list_ideas and get_idea for the
backlog, get_post for a post's body, get_script for a script's, and the matching update_ tools
to change them. Prefer revising what exists to creating a near-duplicate beside it.

To take something back, use the verb for what you mean rather than editing around it.
unschedule_posts takes posts off the calendar and returns them to draft; archive_posts puts
them aside; delete_posts moves them to the trash, where a person can still restore them. Note
that update_post does NOT unschedule: editing a scheduled post deliberately leaves it
scheduled, so that fixing a typo never silently pulls a post from the calendar. Each of these
takes up to 25 posts and a short reason, and reports per post what it did and what it refused.

When something is ambiguous, ask the user before writing. A wrong draft in the workspace costs
more to find and fix than a question costs to ask.

Errors

A failed tool call returns a JSON-RPC result with isError: true and text {"error": "<code>", "message": "<explanation>"}.

JSON-RPC errors: -32700 parse error, -32600 invalid request, -32601 method not found, -32602 unknown tool. Connection errors (HTTP 400, 401, 403, 405, 429) come before any tool runs; see MCP access, permissions & audit.

Plan-gated tools

Every tool needs MCP Connections on the workspace's plan. Six also need a second capability, checked per call, or they return feature_disabled.

See Plans & billing for what each plan includes.

Read: workspace context

get_brand_context

Returns the workspace's Brand Brain: voice, point of view, topic space, goals, ideal customer profile, content rules and the host's voice profile. Read it before writing copy or revising a template.

Returns has_brand_context, brand_context (the prose block Convia's own generators use), structured fields (persona_type, brand, host, workspace), and a note if nothing is set up.

list_social_platforms

Lists the connected social accounts. Call it to get a social_account_id for create_post.

Returns platforms (up to 100: id, platform, display_name, profile_image_url, account_type, needs_reauth, is_active) and count.

get_schedule_settings

Returns how the workspace publishes, so dates match its real schedule. Call it before choosing any date.

Returns timezone, day_window (start, end), platform_defaults (platform, day_of_week, day_name, time_of_day as HH:MM), unconfigured (connected platforms with no default), connected_platforms and fallback_note. With no default, a time falls back to the platform's best-practice hours, then the start of the posting window, which is advisory.

get_text_snippets

Returns the workspace's reusable text blocks, such as a standard outro. Reproduce them exactly.

Returns snippets (up to 200: id, name, content), count, and a note when there are none.

list_content_conversations

Lists AI co-editing conversations with their messages, for finding recurring themes.

Returns conversations (id, content_id, content_type, dates, messages with role and content, truncated) and count.

Read: episodes, clips and transcripts

list_episodes

Lists episodes, most recently published first, with what exists for each. Do not use status to judge whether an episode is real: read has_transcript, has_media and clip_count.

Returns episodes (title fields, guest_names, episode_number, season_number, status, description, dates, duration_seconds, has_media, has_transcript, is_diarized, transcript_word_count, speaker_mapping_confirmed, clip_count), count and returned. No transcript text.

list_episode_guests

Returns who appeared on which episode, with job title and company. Use it to check that a post names the right person.

Returns episodes (episode_id, title, episode_number, published_date, guests with id, name, title, company, and legacy_guest_name) and returned. Guests who asked for their data to be removed are never returned; no confirmed guest means an empty list.

list_clips

Lists clips with their episode and how often each was used. Keyword and metadata matching, not semantic.

Returns clips (id, title, description, tags, duration_seconds, episode_id, episode_name, has_transcript, text_provenance, times_used, last_used_at, start_seconds, end_seconds, plus utilization_platform, times_used_on_platform and last_used_on_platform_at with platform) and the paging envelope, with warnings if a very large workspace hits a cap. text_provenance (generated, imported, unknown) marks clip text as a summary, never speech.

get_transcript

Returns what was said in an episode, with speakers and timestamps. Read it before quoting anyone.

Returns episode_id, episode_title, duration_seconds, offset_basis (episode or clip), source (asr, pasted, or null with no transcript), diarized, speaker_mapping_confirmed, speakers, segments (speaker_label, speaker_name, start_seconds, end_seconds, text), count, returned, truncated, next_start_seconds and note. To continue, pass next_start_seconds as start_seconds. A null speaker_name means the voice is unconfirmed: do not name that speaker. With offset_basis: clip, offsets count from the start of the clip.

search_content

Keyword search across episodes, clips, posts and transcripts. Search transcript to verify a claim before writing it as fact.

Returns episodes, clips and posts (each with match_context), transcript_segments (episode_id, episode_title, speaker_label, speaker_name, start_seconds, text, match_context), transcript_episodes_scanned, transcript_scan_capped and note. Transcript search opens at most 25 episodes per call; transcript_scan_capped: true means more may match. An empty result means these exact words were not found, not that nothing similar was said.

get_derived

Shows what was already made from an episode, clip or idea, so you do not rebuild it.

Returns source, clips, posts (id, title, platform, status, scheduled_date, published_url, campaign_id, campaign_name), campaigns and counts. For an idea it also returns scripts, clips is always empty and posts omit campaign_name.

Read: posts, ideas, scripts and campaigns

list_posts

Finds posts, newest first. Metadata only: use get_post for the body.

Returns posts (id, title, platform, post_type, status, dates, parent_webcast_id, campaign_id, and excerpt when searching), count (page length) and the paging envelope. A few legacy imported posts do not match body_contains.

get_post

Reads one post in full.

Returns id, title (internal label), published_title (null means title is published), content, subtitle, seo_title, meta_description, platform, post_type, article_type, status, dates, published_url, social_account_id, parent_webcast_id, video_clip_id, campaign_id, media_ids, tags, meta_keywords and url.

list_scheduled_posts

Lists posts on the calendar in a date window, any status, earliest first. Check it before picking dates.

Returns posts (id, title, platform, status, scheduled_date, campaign_id), count, returned and known_statuses.

list_ideas

Lists the idea backlog, newest first. Read it before proposing ideas.

Returns ideas (id, title, description, notes_preview (first 280 characters), notes_truncated, status, priority, tags, category, derived_count, dates) and the paging envelope.

get_idea

Reads one idea in full, with everything derived from it.

Returns the idea's fields including full notes and source_type, plus derived (each with type, id, title, status), derived_count, derived_by_type and url.

list_scripts

Lists scripts, newest first, with a char_count instead of the body.

Returns scripts (metadata, char_count, word_count, estimated_duration_seconds, tags, dates) and the paging envelope.

get_script

Reads one script in full, including the body.

Returns the script's fields including content, notes, generated_from and url.

list_campaigns

Lists campaigns, newest first, with beat and gap counts. The full plan is not returned.

Returns campaigns (id, name, description, campaign_type, status, dates, platforms, keywords, parent_webcast_id, has_plan, beat_count, gap_count, origin (mcp or in_product)), count and returned. Plans still being drafted in the campaign builder are not listed.

get_campaign_plan

Reads one campaign's narrative plan. Requires Magic Campaign.

Returns campaign_id, name, campaign_status, has_plan, plan (the spine and each platform's beats, each with a beat_uid, its move, format, schedule offset, fulfillment status, any gap, and whether it is pinned), beat_count, gap_count, pinned_count and post_count. A campaign without a narrative plan returns has_plan: false and a detail message.

Create

create_post

Creates one draft post. Read get_brand_context first and verify figures and quotes with search_content. For a coordinated set of posts, use create_campaign_from_plan.

platform_options accepts only these keys. Unknown keys and wrong types return validation_error naming the allowed keys.

TikTok privacy and branded-content settings, YouTube Made for Kids, privacy status and publish time, and Instagram collaborator and paid-partnership labels are set by a person in the composer, never through MCP.

Returns id, title, status (always draft), and when relevant tags, source_clip (id, episode_id, times_used), source_idea_id, scheduled_date, schedule_source (explicit for a time you supplied), warnings and url. Side effect: a draft. With a scheduled_date it sits on the calendar but does not publish until a person schedules it.

create_campaign_from_plan

Creates a multi-platform campaign, its narrative spine and every post, in one call. Requires Magic Campaign. One idea per campaign; read get_brand_context and list_scheduled_posts first.

Each item in posts:

Limits per call: 40 posts, 8 platforms, a 90-day window, 500,000 characters of content. A date outside the window is rejected with its index, never moved. Bare dates on the same platform and day get different times.

Returns campaign (id, name, status: draft, url), posts_created, scheduling (timezone, day_window, sources), gaps_held, gaps_flagged, gaps (beat_id, platform, needed_asset, gap_type) and warnings (such as a platform with no connected account).

Side effects: a draft campaign and dated draft posts on the calendar. Nothing schedules, publishes or enters the approval queue until a person activates the campaign. Held beats are flagged with their brief as a comment, with one notification. If the posts fail to save, the campaign is rolled back.

create_idea

Creates an idea. Put the reasoning (angle, audience, raw material, overlap) in notes, and check list_ideas for near-duplicates first.

Returns id, title, status (new) and tags.

create_script

Creates a script, optionally linked to an idea or episode.

Returns id, title, word_count and url.

create_episode

Creates an episode record. Recording and media are added later in the app.

Returns id, youtube_title (your title) and status.

Update

update_post

Revises a post. Only the fields you supply change. Read the post with get_post first if you mean to edit rather than rewrite.

Rules: published and approved posts return post_immutable. A pending_approval post returns to draft (approval_reset: true) so the edit is reviewed. A scheduled post stays scheduled: update_post never unschedules. Titles are cleaned of markdown, quotes and labels such as Title:. At least one field must change. tags, media_ids and source_clip_id cannot be changed.

Returns id, title, status, platform, scheduled_date, approval_reset, updated_fields, and as relevant schedule_source, warnings, url.

update_idea

Revises an idea. Omitted fields are left alone; an explicit null clears a field. There is no delete: set status to archived.

Returns id, title, status, priority, tags and updated_fields.

update_script

Revises a script. Supplying content replaces the whole body.

Returns id, title, status, word_count and updated_fields.

update_campaign_plan

Amends a campaign plan before any posts exist. Requires Magic Campaign. Generates no copy and publishes nothing.

A campaign that has posts is refused, including every campaign made with create_campaign_from_plan: edit its posts instead. An edited beat is pinned (kept by a re-plan) unless you pass pinned: false. Returns campaign_id, beats_updated, beats_removed, beat_count, gap_count and pinned_count.

Lifecycle: take posts back

unschedule_posts, archive_posts and delete_posts share one contract. Each post is handled on its own, so one refusal does not block the rest.

Returns updated (id, title, status, deleted, previous_scheduled_date), unchanged and refused (each with id and reason; an unknown id is refused), and a count for each. A post already in the target state is unchanged, not a failure.

All three refuse published posts (retract those on the platform), approved posts (a person signed off) and posts being published right now. delete_posts also refuses scheduled posts: call unschedule_posts first, then delete_posts. A post already in Trash is refused by the other two.

unschedule_posts

Takes posts off the calendar and back to draft, keeping the copy: "stop this going out, decide later". Uses the shared contract above.

archive_posts

Puts aside work that is real but not going ahead, keeping it on record. Uses the shared contract above.

delete_posts

Moves to Trash what should never have been created, such as a bad batch or a duplicate run. Uses the shared contract above.

Prompts and templates

Convia has two template surfaces. Content templates drive long-form generators (article, script, conversation_outline, webcast_description, chapter_markers, webcast_promotion) and can hold named alternatives, one of which is the live default; thumbnail_style holds saved thumbnail styles with no default. Platform templates are one prompt per social platform. Retired thumbnail types (thumbnail_background, thumbnail_text_overlay, thumbnail_photo_composition, thumbnail_refinement) return retired_content_type.

list_prompt_templates

Lists templates, metadata only.

Returns templates (id, surface, content_type or platform, post_type, name, is_default, resolves_as (default or available), char_count, updated_at, and has_best_practices for platform templates), count and note.

get_prompt_template

Returns one template's full text and the {placeholder} variables it uses.

Returns template (prompt_template, or system_prompt and best_practices for platform, plus variables_used) and would_fall_back_to: null when the workspace has its own, otherwise master (Convia's platform-wide template) or inline_default (the built-in default). A warning appears if two content templates are marked default.

upsert_prompt_template

Saves a content template as a non-default alternative. Generation is unchanged until a manager makes it the default in Brand Brain → AI Prompts.

Returns id, surface, content_type, post_type, name, is_default: false, promoted: false, variables_used, url and message. Editing the live default returns default_template_immutable; writing a platform template returns platform_prompts_immutable (edit those in Brand Brain → Social Platform Prompts).

Analytics

get_post_analytics

Returns the latest analytics for one post. Requires Advanced Analytics.

Returns post_id, platform, analytics (metrics: all-time views, impressions, reach, reactions, comments, shares, saves, engagements, null if the platform does not report one; engagement_rate; window_28d for YouTube), performance (pace against the account's usual post of that platform and format at the same age: below, within or above; null until scored), reach (YouTube thumbnail impressions and click-through rate) and raw snapshot (prefer analytics.metrics). analytics is null until something is recorded.

get_web_analytics

Returns sessions and key events that Convia-tagged links sent to the workspace's own site, from its Google Analytics 4 property. Requires Advanced Analytics. See Website analytics.

Returns has_ga4, latest_data_date, range (cut off at the last collected day), requested_range, key_events_configured, totals (sessions, engaged_sessions, key_events), site_total_sessions, share_of_site_sessions (0 to 1), rows (at most 100), untagged and note. A null metric means not collected, never zero.

get_search_queries

Returns the searches that bring people to the workspace's own site, from Google Search Console and Bing. Requires Advanced Analytics.

Returns has_search, latest_data_date (google, bing), range, filters, rows (provider, query, page (null on Bing), clicks, impressions, position, is_branded), returned and note.

Related

• Connect an AI assistant (MCP): get your MCP URL and connect.
• Agent workflows: these tools as step-by-step recipes.
• MCP access, permissions & audit: connection errors, roles and the audit log.
• Glossary: Convia terms used in tool results.