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.
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
workspaceargument; 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 isupdate_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_datetakes a bareYYYY-MM-DD(preferred), which resolves to the workspace's posting time for that platform and weekday, or ISO 8601 with an explicit offset such as2026-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
workspaceargument: a workspace id, or its exact name or show name. - A
list_workspacestool appears. It takes no parameters and returnsworkspaces(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.
Related
- MCP tool reference: every tool, the plan it needs, its parameters and what it returns.
- MCP access, permissions & audit: connection errors, tokens, OAuth and the Activity log.
- Connect an AI assistant (MCP): connect a client to one or several workspaces.
- Agent workflows: the tools combined into step-by-step recipes.