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.
On this page
- Plans and gated tools
- Start a session with get_started
- Learn the workspace
- Find source material and check claims
- See posts and the calendar
- Create drafts
- Revise and take back posts
- Attach images and videos to posts
- Plan campaigns
- Ideas and scripts
- Episodes and YouTube videos
- Series tools
- Prompts and templates
- Post and episode analytics
- Website traffic and search
- Related
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_stateisnull.section: aslugfromdocs_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_episodeswithguests: truereturns only who appeared on which episode, with job title and company, for up to 50episode_idsor the 25 most recent. Guests who asked for their data to be removed are never returned. - Judge an episode by
has_transcript,has_mediaandclip_count, notstatus. - Unconfirmed speakers come back with
speaker_name: null: do not name them. A quoteverify_quotescannot 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_postswithscheduled_afterandscheduled_before. get_postreads one post (post_id) or up to 20 (post_ids). Copy checks come back asguardrailswith Humanizer;check_sources: truealso flags statistics not in the source transcript, and is slower.effective_statusis the status, exceptscheduled_privateoruploaded_privatefor 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 fromdestination. Never type the URL. - Platforms. Pass
social_account_id(preferred) orplatform. Awordpresspost is always an article;webmakes 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.
itemstakes up to 100 posts, withdefaults,schedule(none,as_givenorautowithauto_window),submit_for_approvalanddry_run. Each item counts as one change against the daily budget. Run adry_runfirst: a clean dry run means a clean write. - Approval.
submit_for_approvaltakes 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 withapprovals_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 |
|---|---|
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 |
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_postnever unschedules. - Fix exact text. With
post_id, passfindandreplace_withinstead ofcontent;findmust match once unlessreplace_allistrue, and a save made since Convia read the post refuses the edit. Withcampaign_id, the same fix runs across the campaign's posts that have not gone out, as a preview unlessdry_runisfalse. remove_poststakes 1 to 25 posts and a requiredreason, recorded in the MCP activity log.action: "unschedule"returns posts to draft and clears the date (returned asprevious_scheduled_date).action: "trash"moves posts to Trash, where a person can restore them. Both refuse published, approved and publishing posts, andtrashrefuses a scheduled post: unschedule it first, so a restored post can never publish unreviewed. Results come back asupdated,unchangedandrefused.- 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_uploadwith the exactfile_size_bytesreturns anupload_url(valid 30 minutes for an image, 2 hours for a video);PUTthe bytes there; thenfinalize_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) oncreate_postorupdate_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_urlcannot fetch them. - Media errors include
unsupported_media_type,file_too_large,upload_expired,storage_quota_exceededandurl_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_atfromget_episode_prepasexpected_prep_updated_at; if the episode changed since, the save is refused and the current outline returned. update_episodechanges 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_videopreviews first: the call withoutapply_tokenchanges 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.
Website traffic and search
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.
Related
- MCP protocol, connections & errors: rate limits, paging, multi-workspace connections and error codes.
- Connect an AI assistant (MCP): connect a client to one or several workspaces.
- Agent workflows: these tools as step-by-step recipes.
- MCP access, permissions & audit: connection errors, roles, plans and the audit log.
- Glossary: Convia terms used in tool results.