Skip to content
Convia ProDocs

For the complete documentation index, see llms.txt. This page is also available as markdown.

MCP tool reference

Look up every tool the Convia MCP server exposes, grouped by job, with the plan each one needs, the options that matter, its limits and safety rules.

Last updated
On this page

The Convia Pro MCP server gives a connected assistant 55 tools to read a workspace's content and write drafts. This page groups them by job, with the plan each needs, the options that replaced older tools, and the rules and limits a tool's own description does not make obvious. Every client also receives each tool's full parameters from the server, and sees only the tools its workspace's plan includes. For the protocol, rate limits, multi-workspace connections and error codes, see MCP protocol, connections & errors.

Plans and gated tools

Every tool needs MCP Connections on the workspace's plan (Grow and above). Some tools, and some options on a tool, also need more, checked on every call. tools/list leaves out tools the plan lacks, and Integrations → MCP Connections marks them Not on your plan (or Advanced MCP). An option the plan lacks returns feature_disabled.

Also needs Tools and options
Advanced MCP (Scale and above) update_youtube_video; create_post and update_post with items; update_post with campaign_id
Advanced Analytics query_post_performance, get_episode_performance, get_audience_growth, get_site_traffic (view from_posts), get_search_queries (view queries); get_started with measurement: true
Website Analytics as well (coming soon) get_site_traffic views traffic, audience, properties; get_search_queries views totals, pages, opportunities
Magic Campaign create_campaign_from_plan, get_campaign_plan, update_campaign_plan
Ideas create_idea, list_ideas, get_idea, update_idea
Scripts create_script, list_scripts, get_script, update_script
Series list_series, get_series, create_series, update_series, add_to_series
Advanced AI upsert_prompt_template
Prompt Learning list_prompt_versions, get_prompt_version

Every other tool needs only MCP Connections. In the tables below, Plan names only what a tool needs beyond that. See Plans & billing and the pricing page.

Start a session with get_started

get_started is listed first on every connection; call it first. It is read-only. It returns what Convia is (from these docs, fetched for clients without web access), the workspaces the connection reaches, the chosen workspace's setup, which tools fit common jobs on its plan (tools_by_job) and next_steps.

  • workspace: with several workspaces, the one to describe. Until one is chosen, workspace_state is null.
  • section: a slug from docs_index, to read that docs page in full.
  • measurement: true: also report what the workspace can measure (Google Analytics and its key events, tagged links, which accounts report followers). It is slower and needs Advanced Analytics. Read it before judging performance, so a conversion never set up is not read as zero.

workspace_state includes the plan, Brand Brain, connected platforms, episode and scheduled post counts, and the workspace's destinations (where posts send people, with the default marked). Pass a destination's id or name as destination when writing.

list_workspaces appears only on a connection that reaches several workspaces, and lists them.

Learn the workspace

Read-only context an assistant pulls before it writes, so copy matches the workspace's voice.

Tool What it does Plan
get_brand_context The Brand Brain: voice, point of view, audience, content rules and the host's voice
get_text_snippets Reusable text blocks, such as the standard outro, to reproduce exactly
list_social_platforms Connected accounts, with the social_account_id to write to
get_schedule_settings Timezone, posting window and default posting times per platform and weekday

Find source material and check claims

Clip titles and descriptions are written by AI. Quotes and figures must come from the transcript.

Tool What it does Plan
list_episodes Episodes with guests, numbers, status, whether each has a transcript, media, clips and Episode Prep, and its full-length YouTube link
list_clips Clips with their episode, how often and how recently each was used, and where each is live
get_transcript What was said, with speakers and timestamps
search_content Keyword search across episodes, clips, posts and transcripts
verify_quotes Check up to 50 phrases against one episode's transcript at once
  • Guests. list_episodes with guests: true returns only who appeared on which episode, with job title and company, for up to 50 episode_ids or the 25 most recent. Guests who asked for their data to be removed are never returned.
  • Judge an episode by has_transcript, has_media and clip_count, not status.
  • Unconfirmed speakers come back with speaker_name: null: do not name them. A quote verify_quotes cannot find is unverified, not false; a paraphrase is not found.
  • Search is literal, not semantic. Transcript search opens at most 25 episodes per call.

See posts and the calendar

Tool What it does Plan
list_posts Posts filtered by platform, status, episode, text or date, with each published post's link. Metadata only
get_post Posts in full: body, titles, SEO fields, media, lineage and copy checks
find_open_slots Open days on a platform's calendar at the workspace's posting times, optionally rotating episodes
list_publishing_issues Posts waiting on a person, most urgent first, each with a suggested action
  • The calendar is list_posts with scheduled_after and scheduled_before.
  • get_post reads one post (post_id) or up to 20 (post_ids). Copy checks come back as guardrails with Humanizer; check_sources: true also flags statistics not in the source transcript, and is slower.
  • effective_status is the status, except scheduled_private or uploaded_private for a YouTube video uploaded private and not yet visible.

Create drafts

Everything here is saved as a draft. Nothing is published, scheduled or sent without a person.

Tool What it does Plan
create_post Draft a post, or many with items items: Advanced MCP
create_episode Create an episode record; recording and media are added in the app
submit_for_approval Send drafts to the approval queue, marked Submitted by assistant
upsert_destination Add or change a destination. Owners and Managers only
  • Dates. Prefer a bare YYYY-MM-DD: it resolves to the workspace's posting time. A dated draft sits on the calendar until a person schedules it.
  • Links. Write {{destination_url}} where the link goes; Convia fills it from destination. Never type the URL.
  • Platforms. Pass social_account_id (preferred) or platform. A wordpress post is always an article; web makes a plain draft article on the Articles page, sent nowhere. An article body can be Markdown or HTML and is stored as HTML.
  • Many at once. items takes up to 100 posts, with defaults, schedule (none, as_given or auto with auto_window), submit_for_approval and dry_run. Each item counts as one change against the daily budget. Run a dry_run first: a clean dry run means a clean write.
  • Approval. submit_for_approval takes up to 200 drafts. Only a draft with an account and a future date goes. It is the furthest an assistant can take a post. Where approvals are off, it is refused with approvals_disabled.

Platform settings. platform_options accepts only these keys; anything else is refused, so a setting either applies or the assistant hears why.

Platform Keys
Instagram media_format (reel or story; a story has no caption), share_to_feed, trial_reel, trial_auto_share
YouTube tags, category_id, playlist_ids, default_audio_language
Pinterest board_id (default or a board id the user gave), board_section_id, alt_text
Mastodon visibility (public, unlisted or private), spoiler_text
WordPress categories and tags by name (an unknown category is refused with the valid names), excerpt, slug; a person chooses draft or publish on the article page

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

Revise and take back posts

Tool What it does Plan
update_post Revise a post, fix exact text, or revise many with items items, campaign_id: Advanced MCP
remove_posts Take posts off the calendar or move them to Trash
  • Safety. Published and approved posts are refused (post_immutable). A post waiting for approval returns to draft (approval_reset: true). A scheduled post stays scheduled and publishes at its date: update_post never unschedules.
  • Fix exact text. With post_id, pass find and replace_with instead of content; find must match once unless replace_all is true, and a save made since Convia read the post refuses the edit. With campaign_id, the same fix runs across the campaign's posts that have not gone out, as a preview unless dry_run is false.
  • remove_posts takes 1 to 25 posts and a required reason, recorded in the MCP activity log. action: "unschedule" returns posts to draft and clears the date (returned as previous_scheduled_date). action: "trash" moves posts to Trash, where a person can restore them. Both refuse published, approved and publishing posts, and trash refuses a scheduled post: unschedule it first, so a restored post can never publish unreviewed. Results come back as updated, unchanged and refused.
  • YouTube copy (published title, description and tags) is read when the video uploads. After that the post is published, and the live video is changed with update_youtube_video.

Attach images and videos to posts

Tool What it does Plan
list_media The Media library as a person sees it, with which posts use each file. Never returns file links
import_media_from_url Add an image from a public https:// link
create_media_upload Start uploading a local image or video
finalize_media_upload Check and record an upload, returning its media_id
  • What fits. Images: PNG, JPEG, WebP or GIF up to 10 MB. Videos (upload only): MP4 or QuickTime up to the plan's per-file limit and at most 1 GB. Files are checked from their contents and count against storage.
  • Upload steps. create_media_upload with the exact file_size_bytes returns an upload_url (valid 30 minutes for an image, 2 hours for a video); PUT the bytes there; then finalize_media_upload. A file that fails the check is deleted. A video's size and length are measured shortly after.
  • Attach with media_ids (up to 10) on create_post or update_post, where it replaces what the post carries. A post carries a clip or media, not both. On an article, the first image becomes the featured image.
  • Sign-in links and chat attachments are not public, so import_media_from_url cannot fetch them.
  • Media errors include unsupported_media_type, file_too_large, upload_expired, storage_quota_exceeded and url_not_allowed.

Plan campaigns

Tool What it does Plan
list_campaigns Campaigns, with how many beats and gaps each holds
get_campaign_plan One campaign's narrative plan: the through line, every beat and its gaps Magic Campaign
create_campaign_from_plan Write a whole multi-platform campaign and its posts in one call Magic Campaign
update_campaign_plan Reword, drop or pin beats before any posts exist Magic Campaign

create_campaign_from_plan takes up to 40 posts on up to 8 platforms, inside a window of 90 days or less. A date outside the window is rejected, never moved, and a clip that does not match is held as a flagged gap rather than faked. The campaign stays a draft until a person activates it. update_campaign_plan refuses a campaign that already has posts.

Ideas and scripts

Tool What it does Plan
list_ideas, get_idea The idea backlog, and one idea with everything made from it Ideas
create_idea, update_idea Capture or revise an idea. There is no delete: archive it Ideas
list_scripts, get_script Scripts without the body, and one script in full Scripts
create_script, update_script Write or revise a script Scripts

Episodes and YouTube videos

Tool What it does Plan
get_episode_prep An episode's Episode Prep: the prep call transcript and conversation outline
update_episode Edit an episode's details and its Episode Prep in Convia
update_youtube_video Change the title, description, chapters or tags of a video Convia uploaded to YouTube Advanced MCP
  • Episode Prep is seen by no other tool. To save prep, pass prep_updated_at from get_episode_prep as expected_prep_updated_at; if the episode changed since, the save is refused and the current outline returned.
  • update_episode changes Convia only, not a platform or podcast feed. Once the episode's video is on YouTube, its title and description follow the video and are refused.
  • update_youtube_video previews first: the call without apply_token changes nothing. Apply only after the user agrees. It cannot change privacy, the release time or premieres.

Series tools

Series group ideas, scripts, episodes, clips, posts (articles included) and Media library files.

Tool What it does Plan
list_series Series with how many items of each kind they hold; archived ones on request Series
get_series One series and its items, newest first (up to 500) Series
create_series Create a series. Names are unique among live series Series
update_series Rename, change the description, archive or restore Series
add_to_series Link up to 200 items, or unlink them with remove: true Series

Adding only links an item: it stays in its episode or campaign and is never changed. Items not in the workspace, or deleted, come back in skipped_items. An archived series must be restored before items are added. The tools cannot set rules that add items automatically, delete a series, create a campaign from one or read its results.

Prompts and templates

Content templates drive long-form generators and can hold named alternatives, one of them the live default. Platform prompts are one per social platform.

Tool What it does Plan
list_prompt_templates, get_prompt_template Which templates exist and which is live, and one template's text with its placeholders
upsert_prompt_template Stage a content alternative, or a platform prompt draft with a change note Advanced AI
list_prompt_versions The newest saved version of a prompt by default (raise limit for history), plus the live one when older Prompt Learning
get_prompt_version One version's text, with a word diff Prompt Learning

Nothing staged changes generation until a person makes it live in Brand Brain. Editing the live default returns default_template_immutable; a platform draft without Prompt Learning returns platform_prompts_immutable; a retired thumbnail template type returns retired_content_type.

Post and episode analytics

A null metric means not collected, never zero, and views, impressions and reach are never added together. See Analytics.

Tool What it does Plan
query_post_performance Many posts' analytics, filtered like list_posts and sorted; or one post with post_id Advanced Analytics
get_episode_performance Everything made from an episode or campaign, rolled up, or recent episodes ranked Advanced Analytics
get_audience_growth Followers per account at the start and end of a period, beside posts published Advanced Analytics

query_post_performance with post_id returns one post's latest numbers; add history: true for its readings over time. YouTube videos uploaded private and not yet revealed are left out unless include_unreleased is set.

Each tool answers through a view. See Website analytics.

Tool Views Plan
get_site_traffic from_posts: visits and key events your posts' tagged links sent. traffic: all visits by channel, source, campaign, host or date. audience: by device or country. properties: connected properties from_posts: Advanced Analytics. Others: Website Analytics as well
get_search_queries queries (default): searches from Search Console and Bing. totals, pages, opportunities (near page one, low click rate, cannibalization, rising, lost) queries: Advanced Analytics. Others: Website Analytics as well

With no view, get_site_traffic answers traffic where the plan has Website Analytics and from_posts otherwise, and says which. Website Analytics is coming soon: until a plan on the pricing page includes it, those views return feature_disabled.