Most MCP failures are an expired upload token, a stale tool catalog, or a plan limit. The connection itself is usually fine.

## The upload returned 401

`uploadUrl` lasts about 30 minutes. Call `create_upload_link` and continue `curl -T`. You do not need to sign in again.

If every MCP call returns 401, the OAuth session or API key is dead. Reconnect in the client or generate a new key on [Connections](https://app.prezzly.ai/connections).

## The client has no `create_upload_link`

The catalog is stale. Reload the Prezzly MCP server (Cursor: Settings → MCP → toggle the server). Do not send a placeholder through `add_revision` to obtain `uploadUrl`.

## 402 `plan_limit`

Storage or per-upload size cap. Tell the user; do not retry. Free-plan defaults include 10 MB per upload and 250 MB storage. Compare plans in the app.

## 409 path exists / empty deck

- "Upload `index.html` or a zip first": the deck has no HTML yet. Upload HTML or a zip before individual assets.
- `files` plus `missingAssets`: that path already exists with different bytes. Replace it with a zip to `uploadUrl` or `add_revision`, not a second `add_files`.

## 400 on `index.html`

A single PUT of `index.html` to an existing deck is rejected. Local clients zip `index.html` (and new binaries) to `uploadUrl`. Chat clients send the real HTML through `add_revision`.

## OAuth never starts

Confirm the URL is `https://mcp.prezzly.ai`. The client must send Streamable HTTP, not stdio. If it only accepts a token, use a Bearer key from Connections.

Pop-up blockers can swallow the Prezzly sign-in window. Allow the popup and try again.

## The agent stuffed images into tool arguments

[Install the skill](/docs/skills/install/). On a local client, `create_presentation` takes title and kind only; binaries go through `curl -T`. Chat clients should use https URLs or `add_files` with `url`.

## Slides do not advance

Exactly one element needs both `slide` and `active`. CSS must hide non-active slides. Do not add a custom ArrowLeft / ArrowRight handler unless you intend to own navigation. See [Slides and dashboards](/docs/html-conventions/).

## The dashboard has no section list

Mark major blocks with `id` or `data-prezzly-section`. Bare `h1`–`h3` are a fallback. Confirm `kind` was `dashboard` at upload time.

## `missingAssets` never clears

Each referenced relative path must exist on disk and be uploaded under the same path. Skip `https:`, `data:`, `#`, and `mailto:`. Spaces and non-ASCII paths need a zip, not a raw `curl -T`.

## The new revision looks too small

Compare `revision.totalBytes` with the previous revision from `get_presentation`. If it shrank and that was not intended, call `restore_revision`.

More status codes: [Publish and update a deck](/docs/mcp/upload/).