> For the complete documentation index, see [llms.txt](https://guide.hypercape.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.hypercape.com/revelio/mcp.md).

# Connect AI apps (MCP)

Use Revelio's MCP connector (server `4.0.0`) to find completed videos, retrieve authenticated MP4 download details, and optionally get captions and review notes. Every key can also read your account, products, story ideas, and characters, and, while Creator Cloud is active, list your Cloud folder files and get short-lived download links for them. A key created with content creation allowed can also register products and make story ideas, videos, and characters with your credits (see step 6). A destination that accepts raw video URLs can use the short-lived `videoPublicUrl` from `get_video_download` or `get_publish_package`; otherwise use a downloader that supports an Authorization header and a destination file-upload tool. Connecting Revelio alone does not publish or schedule anything.

[Open Connect AI apps in Revelio](https://revelio.hypercape.com/integrations/mcp)

### 1. Create and protect a connection key

1. Sign in to Revelio and choose **Connect AI apps** in the left menu.
2. Optionally open **Rename key (optional)** and enter a name for the app or device before creating it.
3. To let your AI app make content, tick **Allow the AI to make content (uses credits)**. With it on, the app can register products and make story ideas, videos, and characters, using credits the same way as the app. A key with this permission expires after 90 days. Leave it off for a read-only key.
4. Choose **Create connection key**. The new key starts with `rvl_`, is shown only once, and fills into the configuration on this screen. Store it like a password before leaving the page.
5. Use one key per app or device so you can revoke them separately. You can have up to five active keys of either kind; expired keys do not count. **My connection keys** shows each key's permissions (**MCP read**, plus **MCP make content (uses credits)** when allowed) and its **Expires** date; a lapsed key shows **Expired** and is refused like a deleted one, so create a new key.
6. If a key is lost or exposed, delete it under **My connection keys**, create a replacement, and update the client. Deleting a key stops new tool calls and authenticated video downloads using it. A file transfer already in progress may finish.

Never put a real key in a guide, shared screenshot, chat message, public repository, or URL query string. A key grants access to that account's completed videos, posting packages, products, story ideas, characters, Creator Cloud files (while Creator Cloud is active), and available credits. Only a key with content creation allowed can start paid work; no key can publish or schedule. Keep configuration files and terminal history containing keys private.

![MCP connection steps with Cursor selected and the complete placeholder configuration; no connection key was created](https://3720355098-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKmVnLoHDk5ZkU3shqZqa%2Fuploads%2Ff5Pz3Skaa29zfhxaOja3%2Frevelio-responsive-2026-10-07-18-mcp-connect.jpg?alt=media)

### 2. Connect a supported client

The production endpoint is:

```
https://revelio.hypercape.com/api/mcp
```

It uses remote HTTP MCP with a fixed header: `Authorization: Bearer YOUR_REVELIO_MCP_TOKEN`. Revelio does not provide OAuth sign-in for this endpoint. Use a client that can send this header, directly or through the `mcp-remote` bridge. An OAuth-only connector cannot use this setup; the in-app page currently lists ChatGPT and claude.ai web connectors as unavailable for this connection method.

On Revelio's connection page, choose **Claude Desktop**, **Cursor**, **VS Code**, or **Claude Code**, then use **Copy settings**. Merge the Revelio entry into your existing configuration without removing other servers. Replace `YOUR_REVELIO_MCP_TOKEN` if it is still a placeholder.

#### Claude Desktop

Install a currently supported Node.js release compatible with `mcp-remote`. Open **Settings → Developer → Edit Config**, add the Revelio server in `claude_desktop_config.json`, save, and fully quit/reopen the app. This configuration uses a local bridge to the remote endpoint; preserve `Authorization:${REVELIO_AUTH_HEADER}` exactly.

```json
{
  "mcpServers": {
    "revelio": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://revelio.hypercape.com/api/mcp",
        "--header",
        "Authorization:${REVELIO_AUTH_HEADER}"
      ],
      "env": {
        "REVELIO_AUTH_HEADER": "Bearer YOUR_REVELIO_MCP_TOKEN"
      }
    }
  }
}
```

#### Cursor

Use `~/.cursor/mcp.json` for your user or `.cursor/mcp.json` for a project. Keep any real key out of source control. Save and reload the MCP connection.

```json
{
  "mcpServers": {
    "revelio": {
      "url": "https://revelio.hypercape.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_REVELIO_MCP_TOKEN"
      }
    }
  }
}
```

#### VS Code

Add the server and input to `.vscode/mcp.json`. VS Code prompts for the key rather than requiring it to be embedded in this example. Start or restart the MCP server and enable its tools in your AI session.

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "revelio-mcp-token",
      "description": "Revelio MCP token",
      "password": true
    }
  ],
  "servers": {
    "revelio": {
      "type": "http",
      "url": "https://revelio.hypercape.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:revelio-mcp-token}"
      }
    }
  }
}
```

#### Claude Code

Run the following command with your own key, then check the server from `/mcp`. User scope makes it available across your projects. Treat the resulting local configuration and command history as sensitive.

```bash
claude mcp add --transport http --scope user revelio https://revelio.hypercape.com/api/mcp \
  --header "Authorization: Bearer YOUR_REVELIO_MCP_TOKEN"
```

#### Refresh tools after the MCP 4.0 update

The server version is now `4.0.0`. The three video tools, `list_recent_completed_videos`, `get_video_download`, and `get_publish_package`, keep `schemaVersion: "3.0"` unchanged; the tools added in 4.0 return `schemaVersion: "4.0"`. Reload/reconnect your Revelio MCP server or restart the AI app so it discovers the new tools. If an old conversation still expects the earlier tool list, start a new one after refreshing. A valid connection key does not need replacing; to let the assistant make content, create a new key with content creation turned on.

Every key can use these account and catalog tools, which do not spend credits:

| Tool                           | What it returns                                                                                                                                                                                                       |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_account`                  | The account role, feature access, available credits, and whether this key can create content (`key.canCreate`).                                                                                                       |
| `list_products`, `get_product` | Your products; `readyForIdeas` once a product is analyzed; its category, key ingredients, and summary.                                                                                                                |
| `list_story_ideas`             | A product's story ideas (`productId`), or a character or animal lead's own episodes with no product (`characterId`; give one, not both): title, logline, story format, language, and the starring `characterId`.      |
| `list_characters`              | Your saved leads (person, animal, or character), whether each is `usable`, its angle `views`, and `hasSoul`.                                                                                                          |
| `list_story_formats`           | The 16 story formats (including `talking_product`, where the product itself talks, and `social_reel`, one silent 5-second cut that is used only when you pass it) with their cuts, length, fitting leads, and ending. |
| `get_video_status`             | Status and progress of a video; when it has completed, use `get_publish_package` or `get_video_download`.                                                                                                             |
| `get_request_status`           | A paid request by its `requestKey`: `running`, `succeeded` (with the new IDs), or `failed` (with a reason).                                                                                                           |
| `estimate_credits`             | The credits a paid tool would hold now, your available credits, and whether that is `sufficient`. It starts nothing.                                                                                                  |

| Tool                       | What it does                                                                                                                                                                                                                                                                                                                     |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_cloud_assets`        | Lists your Cloud folder files, newest first: `assetId`, `kind`, `name`, `contentType`, `sizeBytes`, `usableAsCharacterImage`, and `createdAt`, plus your storage and transfer `usage` and `hasMore`. Optional `kind`, `limit` (1–20, default 10), and `offset`. No storage paths are returned.                                   |
| `get_cloud_asset_download` | A download link for one file (`assetId`) that works for 5 minutes (`expiresInSeconds: 300`). Anyone holding the link can fetch the file, so pass it only to a tool you trust. Every call counts the file size toward your monthly transfer (`countsAgainstTransferQuota: true`). Limited to 30 links per 10 minutes per account. |

Without Creator Cloud, these tools return `CREATOR_CLOUD_REQUIRED`. See [Creator Cloud](/revelio/creator-cloud.md).

### 3. Find the exact completed video

Ask: **“List my 5 most recent Revelio videos.”**

The `list_recent_completed_videos` tool takes:

```json
{"limit": 5}
```

The limit is 1–20, with a default of 10. It returns the signed-in account's completed, non-deleted videos in newest-created-first order. Failed/in-progress jobs and editor AI clips that have not been exported as a finished video are not included. This call does not issue media URLs.

Check the title, product, timestamps, duration, and `generationId`. Do not select by title alone: several versions can share the same title.

* **Original:** `isEditedVersion: false`.
* **Exported edit:** `isEditedVersion: true`; `editedFromGenerationId` identifies the original. Choose this entry when you want the version with your final music, text, or outro. Unsaved editor work is not an exported edit.
* **File readiness:** `publishPackageAvailable` indicates whether the stored video path is available for a package; `hasQualityWarnings` tells you whether warnings were recorded.

If you cannot find an older result in the recent list, identify it in Revelio's **My content**. The generation ID is the UUID in a video result URL such as `/history/<generationId>`. Use only a completed result belonging to the account behind your connection key.

### 4. Get download details and download the MP4

Call **`get_video_download`** with the chosen completed original or exported edit's ID:

```json
{"generationId": "<generationId returned by the list>"}
```

Replace the placeholder with the actual UUID. This tool returns download details without depending on captions, cover images, campaign metadata, or `publishReadiness`. It does not regenerate the video or spend generation credits.

| Field                                         | How to use it                                                                                                                                                                                                                             |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schemaVersion`                               | Must be `"3.0"` for the current contract.                                                                                                                                                                                                 |
| `generationId`                                | Confirm the intended original or exported edit.                                                                                                                                                                                           |
| `media.videoDownloadUrl`                      | Stable Revelio URL: `https://revelio.hypercape.com/api/mcp/videos/{generationId}/download`.                                                                                                                                               |
| `media.requiresAuthorization`                 | `true`: send the same account's MCP key separately in the `Authorization: Bearer …` header.                                                                                                                                               |
| `media.mimeType`                              | `video/mp4`.                                                                                                                                                                                                                              |
| `media.durationSeconds` / `media.aspectRatio` | File duration and aspect ratio.                                                                                                                                                                                                           |
| `media.videoPublicUrl`                        | Short-lived signed MP4 URL, returned by both `get_video_download` and `get_publish_package`, for a destination that cannot send a custom Authorization header. It is `null` (together with its expiry) when a signed link is unavailable. |
| `media.videoPublicUrlExpiresInSeconds`        | Lifetime of `videoPublicUrl` in seconds; call either tool again for a fresh URL after expiry.                                                                                                                                             |

**MCP and the file download are separate requests.** MCP discovery and tool calls use `POST /api/mcp`. The stable owner URL uses `GET /api/mcp/videos/{generationId}/download` and needs the Authorization header. A URL-only publishing tool should use `media.videoPublicUrl` from `get_publish_package` instead; it is signed for a limited time and can be fetched without a Bearer header.

Use a trusted file downloader that supports a custom Authorization header. Some AI clients keep connector credentials hidden from other tools, so automatic download is not available in every client. Configure a supported Bearer downloader or use a secure local invocation with the key supplied privately through an environment variable. Send the key only to the trusted Revelio origin, never to Metricool or another upload destination. Do not paste it into an AI prompt, URL, or shared script.

Example local download (no real key is included):

```bash
# Set REVELIO_MCP_TOKEN privately in your local environment first.
# Replace the example UUID with the ID you selected.
# Send credentials only to this trusted Revelio origin; do not follow redirects.
curl --fail --silent --show-error \
  -H "Authorization: Bearer ${REVELIO_MCP_TOKEN}" \
  --output revelio-video.mp4 \
  "https://revelio.hypercape.com/api/mcp/videos/11111111-1111-4111-8111-111111111111/download"
```

If your AI client cannot perform an authenticated file GET, sign in to Revelio, open the completed result, and choose **Download video**. Then upload that MP4 manually to your publishing service.

The owner URL can be used repeatedly while the owner's stored file exists, the account remains approved, and the key is valid. You do not need to request a new owner link or regenerate the video. The `videoPublicUrl` from `get_video_download` or a publish package is a separate short-lived transfer grant; anyone who receives it can fetch the MP4 until it expires. Revoking the key blocks new authenticated downloads, while a public handoff already in progress may finish. Deleted results, missing files, another account's files, and unapproved accounts cannot be downloaded through the owner route.

The stable owner URL is not an anonymous public playback or embed API. `videoPublicUrl` is a time-limited transfer grant for an approved publishing handoff, not a permanent public page. Attachment disposition is not a technical guarantee that streaming is impossible. Repeated downloads use network bandwidth and infrastructure resources.

#### Optional: retrieve posting text and review notes

Use **`get_publish_package`** with the same `generationId` when you also need:

* `copy.title`, `copy.caption`, and `copy.hashtags`.
* `source.isEditedVersion` and `source.editedFromGenerationId` to recheck the version.
* `quality` and `publishReadiness`: warnings, review status, disclosures, and checklist items.
* An optional `cover` image, which can be `null`. The video public handoff and cover image are temporary URLs with their own expiry fields; request another package if either has expired.

The package contains the same stable authenticated video URL as `get_video_download`. Review `publishReadiness.status` (`ready`, `needs_review`, or `blocked`), `manualReviewRequired`, disclosures, and checklist details before publication. Download access is independent of this status. The stored review data does not grant approval, certify visual accuracy, or publish the result. Older results may need review because they have no stored campaign blueprint; warnings can also be historical.

A completed result is not a quality certification. The user reviews visual quality. Usable completed videos are charged under the normal policy; a manual regeneration is a new paid action. Visual quality concerns do not automatically trigger a no-charge failure or regeneration.

### 5. Upload to Metricool or another publishing service

1. Connect the destination service separately and confirm that your assistant has a working file-upload tool or URL-based media import for it. MCP connectivity alone does not prove upload capability.
2. If the destination accepts a raw video URL, pass `media.videoPublicUrl` from `get_publish_package` before `media.videoPublicUrlExpiresInSeconds` elapses. Otherwise download the MP4 with an authenticated Revelio GET, or use **Download video** while signed in to Revelio.
3. Upload **that MP4 file** with the destination's supported media-upload tool or web interface when URL import is unavailable. Complete the upload before scheduling. Do not pass the stable protected Revelio URL or your Revelio key to the destination as its media source.
4. Review the destination account, video version, caption, hashtags, disclosures, and schedule.
5. Publish or schedule only after you explicitly approve it in that workflow.

**A YouTube watch link is not a raw video-file URL and cannot be substituted for Metricool's original video-file URL.** If your assistant only accepts a URL and cannot upload a local file, use Metricool's media upload interface to upload the downloaded MP4 manually. Do not assume that connecting Metricool's MCP also supplies a downloader and file uploader.

Example prompt:

> List my recent Revelio videos and identify the latest exported edit of the video I choose. Use get\_video\_download for its owner download details and get\_publish\_package for its schema 3.0 posting text and public handoff URL. Show me the version, caption, hashtags, disclosures, review warnings, and the public URL expiry. If my selected publishing service accepts a raw video URL, use videoPublicUrl before it expires; otherwise download the MP4 using a trusted downloader configured with my Revelio Bearer key and upload only that file. Never send my Revelio key to the publishing service. Ask me before publishing or scheduling.

The video and account tools do not create media, spend generation credits, edit captions, or regenerate results. Only the paid tools in step 6 create content, and only with a key that allows it. No Revelio MCP tool posts to social networks. Downloads and external service actions can have their own traffic or service costs.

### 6. Optional: make content with credits

Only a key created with **Allow the AI to make content (uses credits)** can use these tools; a read-only key gets `CREATE_SCOPE_REQUIRED`. They run the same steps as the app, with the same credit estimate, checks, and limits, and always use the default models.

| Tool                    | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_product`        | Registers a product from its `https://` page (`productUrl`), or from `productName` plus `description`, and starts its analysis. Poll `get_request_status` for `result.productId`, then `get_product` until `readyForIdeas` is `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `create_story_ideas`    | Makes 3–5 story ideas for an analyzed product (`productId`). Optional: `storyFormat` (an ID from `list_story_formats`; leave it out to let Revelio pick one per idea; it never picks `social_reel` on its own), `characterId` (a ready saved lead), `language` (`en` unless you pass `ko`), and `brief`. With a character or animal `characterId`, `productless: true` makes episodes of its own story with no product shown or mentioned. Leave out `productId` and pass a character or animal `characterId` to make that lead's own episodes with no product at all; list them with `list_story_ideas` by `characterId`. `world_portal`, `talking_product`, and `social_reel` need the product, so they are refused (`INVALID_ARGUMENT`) for episodes with no product or with `productless: true`. |
| `create_video`          | Starts the video for a story idea (`ideaId`), optionally starring `characterId`. It gets generated background music under the voices unless `backgroundMusic` is `false`. It returns `result.generationId`; poll `get_video_status`, then use `get_publish_package` or `get_video_download`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `create_character`      | Creates an original character lead from a `name` and `description` (photoreal unless `renderStyle` says otherwise), with an optional `soul` (its Markdown bible) and profile fields. Pass `speaks: false` for a character that never talks on camera; a narrator then says its lines.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `create_character_view` | Draws one angle (`front`, `quarter`, `side`, or `back`) of a saved character or animal from the views it already has. Poll `get_request_status` for `result.views`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

| Tool                    | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_product`        | Registers a product from its `https://` page (`productUrl`), or from `productName` plus `description`, and starts its analysis. Poll `get_request_status` for `result.productId`, then `get_product` until `readyForIdeas` is `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `create_story_ideas`    | Makes 3–5 story ideas for an analyzed product (`productId`). Optional: `storyFormat` (an ID from `list_story_formats`; leave it out to let Revelio pick one per idea), `characterId` (a ready saved lead), `language` (`en` unless you pass `ko`), and `brief`. With a character or animal `characterId`, `productless: true` makes episodes of its own story with no product shown or mentioned. Leave out `productId` and pass a character or animal `characterId` to make that lead's own episodes with no product at all; list them with `list_story_ideas` by `characterId`. `social_reel` is used only when you pass it as `storyFormat`; the automatic pick never chooses it. Formats that need a product (`world_portal`, `talking_product`, and `social_reel`) are refused without a product or with `productless`. |
| `create_video`          | Starts the video for a story idea (`ideaId`), optionally starring `characterId`. It gets generated background music under the voices unless `backgroundMusic` is `false`. It returns `result.generationId`; poll `get_video_status`, then use `get_publish_package` or `get_video_download`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `create_character`      | Creates an original character lead from a `name` and `description` (photoreal unless `renderStyle` says otherwise), with an optional `soul` (its Markdown bible) and profile fields. Pass `speaks: false` for a character that never talks on camera; a narrator then says its lines. Or pass `cloudAssetIds` (1–4 Creator Cloud images in the order front, three-quarter, side, back; JPG, PNG, or WEBP, up to 8 MB each) to make it from your own images: it finishes at once, uses no credits, and counts each copy toward your monthly transfer.                                                                                                                                                                                                                                                                         |
| `create_character_view` | Draws one angle (`front`, `quarter`, `side`, or `back`) of a saved character or animal from the views it already has. Poll `get_request_status` for `result.views`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

For every paid call:

* Send your own `requestKey` (8–80 letters, digits, `-` or `_`). Repeating a call with the same key and arguments returns the first request; it never starts or charges twice. The same key with different arguments returns `REQUEST_KEY_REUSED`.
* Add `maxCredits` to refuse anything whose estimate is higher (`CREDIT_LIMIT_EXCEEDED`). Call `estimate_credits` first to see the estimate and your available credits.
* A call is refused before anything is recorded or started when the key cannot create, the paid-request limit is reached, the account may not use the feature (`FEATURE_ACCESS_DENIED`), the product or character is not ready (`NOT_READY`), AI generation is paused, the estimate is above `maxCredits`, or the balance cannot cover it (`INSUFFICIENT_CREDITS`).
* `create_product`, `create_story_ideas`, `create_character` from a description, and `create_character_view` answer `running` and finish afterwards. Poll `get_request_status` with the same `requestKey` until it reports `succeeded` (with the new IDs) or `failed` (with a reason). A request still running after 20 minutes is reported as `failed`.
* Paid requests are limited to 30 per 10 minutes per account, across all of its keys.

A typical flow: `get_account` → `list_products` (or `create_product`) → optionally `list_characters`, `create_character`, and `create_character_view` → `estimate_credits` → `create_story_ideas` → `get_request_status` → `list_story_ideas` → `create_video` → `get_video_status` → `get_publish_package`. Review each result in Revelio as you would in the app; completion is not a quality guarantee, and publishing still happens only in your publishing tool after you approve it.

For a brand mascot's own episodes, skip the product: `list_characters` → `create_story_ideas` with only `characterId` → `get_request_status` → `list_story_ideas` with `characterId` → `create_video`.

### Troubleshooting

| Problem                                    | What to check                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401` / `MCP_UNAUTHORIZED`                 | Correct endpoint, complete key, exactly one `Bearer` prefix, and whether the key was deleted or has expired. Reload the client after updating its configuration.                                                                                                                                                                                                     |
| `MCP_INSUFFICIENT_SCOPE`                   | Use a key created in **Connect AI apps**, with the `mcp:read` permission, and confirm the account can access Revelio.                                                                                                                                                                                                                                                |
| `CREATE_SCOPE_REQUIRED`                    | The key can only read. Create a new key with **Allow the AI to make content (uses credits)** turned on.                                                                                                                                                                                                                                                              |
| `CREDIT_LIMIT_EXCEEDED`                    | The estimate is higher than your `maxCredits`; nothing was started. Raise `maxCredits` or make a smaller request.                                                                                                                                                                                                                                                    |
| `INSUFFICIENT_CREDITS`                     | Top up credits in Revelio, then try again with a new `requestKey`.                                                                                                                                                                                                                                                                                                   |
| `REQUEST_KEY_REUSED`                       | That `requestKey` was already used for a different request. Use a new one.                                                                                                                                                                                                                                                                                           |
| `NOT_READY` / `CONFLICT`                   | The product or character is not ready yet, or is busy with another request. Check its status and try again later. From a Creator Cloud tool, `CONFLICT` means your monthly transfer is used up.                                                                                                                                                                      |
| `FEATURE_ACCESS_DENIED`                    | The account is not allowed to use this feature, for example characters.                                                                                                                                                                                                                                                                                              |
| `CREATOR_CLOUD_REQUIRED`                   | This needs an active Creator Cloud subscription (paid or gifted). See [Creator Cloud](/revelio/creator-cloud.md).                                                                                                                                                                                                                                                    |
| `NOT_FOUND` / `REQUEST_NOT_FOUND`          | No Creator Cloud file with that `assetId`, or no paid request with that `requestKey`.                                                                                                                                                                                                                                                                                |
| `SERVICE_UNAVAILABLE`                      | Revelio could not do this right now. Retry later.                                                                                                                                                                                                                                                                                                                    |
| `INVALID_ARGUMENT`                         | `limit` must be 1–20; use the actual video UUID as `generationId`; `requestKey` must be 8–80 letters, digits, `-` or `_`. Extra input fields are not accepted. A story format that needs a product (`world_portal`, `talking_product`, `social_reel`) cannot be used without one, and Creator Cloud images must be JPG, PNG, or WEBP, at most 8 MB, and listed once. |
| `VIDEO_NOT_FOUND`                          | Confirm the account, ID, completed status, and that the result has not been deleted. An ID from another account will not work.                                                                                                                                                                                                                                       |
| `VIDEO_ASSET_UNAVAILABLE`                  | Open the result in Revelio and check the file. Contact support if a completed result's asset is missing. A new package cannot restore a missing file.                                                                                                                                                                                                                |
| File GET returns `401`                     | The downloader must send the same valid MCP key separately as an Authorization Bearer header. A connector key may not be available to other AI tools; use a secure local downloader or sign-in download in Revelio.                                                                                                                                                  |
| Expired cover image URL                    | Request `get_publish_package` again for a fresh cover image URL. This does not apply to the stable video URL.                                                                                                                                                                                                                                                        |
| `videoPublicUrl` is `null` or expired      | Call `get_video_download` or `get_publish_package` again for a fresh URL. If it is still `null`, use the stable authenticated URL with your key, or **Download video** while signed in to Revelio.                                                                                                                                                                   |
| Old tool list or missing tools             | Refresh/reconnect the MCP server and start a fresh conversation if needed. Confirm server `4.0.0` (the video tools still report schema 3.0); keep your valid key.                                                                                                                                                                                                    |
| No edited version                          | Finish exporting it in Revelio, wait for completion, then list again.                                                                                                                                                                                                                                                                                                |
| `429` / too many requests / `RATE_LIMITED` | Wait and reduce repeated calls. The endpoint allows 60 requests/minute per key; publish-package calls have an additional 20/minute limit; file downloads have their own 20/minute limit; paid requests are limited to 30 per 10 minutes per account. Creator Cloud download links are limited to 30 per 10 minutes per account.                                      |
| `MCP_INTERNAL_ERROR`                       | Retry later. If it continues, contact support with the result ID and error, without keys or temporary cover URLs.                                                                                                                                                                                                                                                    |
| AI can read the package but cannot post    | Add a supported downloader/uploader or upload manually. Do not replace the MP4 with a YouTube watch link.                                                                                                                                                                                                                                                            |

**Related:** [Edit & download](/revelio/edit-and-download.md) · [Creator Cloud](/revelio/creator-cloud.md) · [Credits & help](/revelio/credits-and-help.md) · [Overview](/revelio/overview.md).

Client configuration references: [mcp-remote](https://github.com/punkpeye/mcp-remote), [Cursor MCP](https://cursor.com/docs/mcp), [VS Code MCP](https://code.visualstudio.com/docs/copilot/customization/mcp-servers), [Claude Code MCP](https://code.claude.com/docs/en/mcp).
