Skip to content
Convia ProDocs

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

MCP protocol, connections & errors

Check how the Convia MCP server speaks MCP, its rate limits and list paging, how multi-workspace connections work, and what each tool error code means.

Last updated
On this page

The Convia Pro MCP server follows the Model Context Protocol over HTTP. This page covers what every tool shares: the protocol and its limits, paging, connections that reach several workspaces, the instructions a client receives and the error codes a tool returns. Each tool's parameters are in the MCP tool reference.

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 https://mcp.conviapro.com, and each response is application/json. There is no session id and no event stream.

Item Value
Methods initialize, ping, tools/list, tools/call. Notifications get 202 with an empty body
Capabilities tools only
Server info name: convia-mcp, version: 1.0.0
Protocol versions 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. initialize echoes yours if supported, otherwise answers 2025-11-25
MCP-Protocol-Version header Optional. Any other value returns HTTP 400 unsupported_protocol_version
Batching A JSON array of messages is answered with an array
Workspace budget 300 requests an hour and 100 changes a day per workspace, or 1,000 and 500 with Advanced MCP, on rolling windows. Over it, a tool call returns rate_limited; reading still works when only the change limit is reached
Flood limit 60 requests a minute per credential. Over it: HTTP 429, Retry-After: 60

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

  • Workspace. Every call acts on one workspace, and an id from another workspace is treated as unknown. On a connection that reaches several workspaces, every tool takes a required workspace argument; see Connections that reach several workspaces.
  • Nothing publishes. No tool publishes, schedules a post to go out or approves one. New posts are drafts. A draft can be sent to the approval queue with submit_for_approval, where a person decides. The one exception is update_youtube_video, which changes the copy on a video already on YouTube after a preview.
  • 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 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.
  • Links. Write {{destination_url}} where a destination's link goes and Convia puts the real link there. Never type the URL.
  • No AI credits. MCP runs no AI writing inside Convia and spends no AI credits.

List paging and shorter lists

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

list_episodes, list_clips and query_post_performance take detail: full (the default for now) or compact, which leaves out long text and nested detail so a long list fits in the assistant's context. On list_clips, compact returns a 140-character description_excerpt instead of the description.

Connections that reach several workspaces

When a person ticks more than one workspace while approving a connection, the connection changes shape:

  • Every tool takes a required workspace argument: a workspace id, or its exact name or show name.
  • A list_workspaces tool appears. It takes no parameters and returns workspaces (id, name, show_name).
  • Every result says which workspace it came from.
  • A call that names no workspace (workspace_required), one the connection was not given (unknown_workspace) or a name two workspaces share (ambiguous_workspace) is refused with the choices listed. Convia never guesses.

With one workspace ticked, or with a workspace token, there is no workspace argument and no list_workspaces.

How the server instructions guide a client

initialize returns instructions that apply to every tool, built for the plan and the connection so they name only tools the client can see. In short: call get_started first; read get_brand_context, get_prompt_template and get_text_snippets, verify claims with search_content, and check list_posts (with scheduled_after and scheduled_before) and get_schedule_settings before choosing a date; call get_episode_prep before writing for an episode not yet recorded; write {{destination_url}}, never a URL; treat every write as a draft; revise rather than duplicate, and take posts back with remove_posts; dry-run a batch first; call get_started with measurement: true before judging performance; on a connection with several workspaces, never assume one; and ask the user when something is ambiguous.

Tool errors

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

Code Meaning
validation_error Missing, malformed or out-of-range argument, or a broken rule (past date, outside a campaign window, unknown platform option, ambiguous name, a find that does not match)
not_found No such id in this workspace
unknown_platform, wrong_platform Platform not accepted by this tool
feature_disabled The plan lacks the capability this tool or option needs. After an upgrade, reconnect the client
rate_limited The workspace's hourly request or daily change budget is used up. Wait and retry
workspace_required, unknown_workspace, ambiguous_workspace A connection with several workspaces did not name one it can reach
unknown_section, docs_unavailable A get_started section not in docs_index, or unreachable
post_immutable update_post on a published or approved post
platform_account_mismatch platform and social_account_id disagree
title_too_long, description_too_long A YouTube title over 100 characters or description over 5,000
forbidden The tool acts for the connected person, who is not an Owner or Manager
not_available The feature behind the tool cannot answer right now
default_template_immutable, platform_prompts_immutable, retired_content_type Disallowed template writes. See Prompts and templates
db_error, internal_error Convia could not complete the request. Retry later

The media tools add their own codes, listed under Attach images and videos to posts. JSON-RPC errors: -32700 parse error, -32600 invalid request, -32601 method not found, -32602 unknown tool. Connection errors (HTTP 400, 401, 403, 405, 429, 503) come first; see MCP access, permissions & audit.