# 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.

> For the complete documentation index, see [llms.txt](https://docs.conviapro.com/llms.txt).

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](https://docs.conviapro.com/docs/mcp-tools.md).

## 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](#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](https://docs.conviapro.com/docs/ai-credits.md).

### 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](https://docs.conviapro.com/docs/mcp-tools.md#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](https://docs.conviapro.com/docs/mcp-tools.md#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](https://docs.conviapro.com/docs/mcp-security.md).

## Related

- [MCP tool reference](https://docs.conviapro.com/docs/mcp-tools.md): every tool, the plan it needs, its parameters and what it returns.
- [MCP access, permissions & audit](https://docs.conviapro.com/docs/mcp-security.md): connection errors, tokens, OAuth and the Activity log.
- [Connect an AI assistant (MCP)](https://docs.conviapro.com/docs/mcp-quickstart.md): connect a client to one or several workspaces.
- [Agent workflows](https://docs.conviapro.com/docs/mcp-workflows.md): the tools combined into step-by-step recipes.

---

Source: https://docs.conviapro.com/docs/mcp-protocol · Section: AI agents & MCP · Last updated: 2026-11-15
