# RemixViral for AI agents (MCP): quickstart and human oversight

RemixViral is built for AI agents to operate over MCP; the human owner tags the work and reviews and approves what the agent did.

- Server: https://remixviral.ai/api/mcp (Streamable HTTP). ChatGPT: https://remixviral.ai/api/mcp/chatgpt.
- Registry name: ai.remixviral/clipper

## Discovery
- https://remixviral.ai/llms.txt and https://remixviral.ai/llms-full.txt: product facts, pricing and limits for language models.
- https://remixviral.ai/.well-known/mcp/server-card.json: machine-readable server card (URL, auth, tools, registry name).
- Official MCP Registry: ai.remixviral/clipper (remote server, Streamable HTTP).
- https://remixviral.ai/pricing.md and https://remixviral.ai/mcp.md: plain-markdown pricing and this guide.

## Authentication
- OAuth 2.1 with PKCE and dynamic client registration, discovered from https://remixviral.ai/api/mcp (401 with a WWW-Authenticate resource_metadata link). The human owner signs in to RemixViral and presses Allow on the consent screen; RemixViral then creates an API key named "MCP: <client name>" on their account (90-day expiry).
- API key: the owner creates a key at https://remixviral.ai/en/developers and gives it to the agent as Authorization: Bearer <key>. Default scopes: video:create, video:read, credits:read, usage:read.
- There is no self-serve agent signup: an account is created and paid for by a human, and a human approves (OAuth) or creates (API key) the agent's access.

## Tools
| Tool | What it does | Credits |
|---|---|---|
| `list_clip_jobs` | Lists your long-video clip jobs, newest first, with id, status and title. | read-only, free |
| `get_clip_job` | Reads one clip job: status, then the clips ranked best first with start and end seconds, the reason each was picked and a score. Optional full transcript. | read-only, free |
| `create_video` | Starts a faceless Short from a topic (30, 60 or 90 seconds). Returns an id; the render runs asynchronously. | spends credits |
| `get_video` | Status of one video and, when it is done, the playable link. | read-only, free |
| `list_videos` | Lists your videos, newest first, with an optional status filter. | read-only, free |
| `list_niches` | Lists the niches, art styles, qualities and durations create_video accepts. | read-only, free |
| `get_credit_balance` | Your credit balance, monthly allocation and plan. | read-only, free |

## Minimal call sequence
| Step | Tool | Example arguments | Returns |
|---|---|---|---|
| Check what the account can afford | `get_credit_balance` | `{}` | balance, monthly allocation and plan |
| Find the clip jobs the human uploaded | `list_clip_jobs` | `{}` | sources[] with id, status, title |
| Read the ranked clips | `get_clip_job` | `{ "id": "<job id>", "includeTranscript": false }` | clips ranked best first with startSec, endSec, reason, score, render status |
| Start a faceless Short (spends credits; show the cost to the human first) | `create_video` | `{ "topic": "3 tiny habits that change your life", "duration": 30, "language": "en" }` | id and status "PENDING"; estimatedCredits |
| Poll until done (every 20-30 seconds) | `get_video` | `{ "id": "<video id>" }` | status PENDING/GENERATING_*/RENDERING, then COMPLETED with videoUrl, or FAILED with error |

## Limits, cost and idempotency
- Rate limit: each API key allows 100 requests per hour by default; beyond that the call fails with 429 RATE_LIMIT_EXCEEDED and the reset time in the message.
- At most 3 faceless videos may render at once per account; a fourth call returns 429 TOO_MANY_PENDING_VIDEOS.
- Idempotency: create_video is not idempotent, but an identical request within 10 minutes returns the existing video with deduplicated: true and spends nothing. allowDuplicate: true forces a new one.
- Cost: a faceless Short costs 40 credits with the default voice, checked before anything is queued; reading tools never charge.
- Clip jobs cannot be started by an agent: the human uploads a video they own in the web app. There is no link import.

## Errors the agent should handle
Over MCP these arrive as a tool result with isError: true and this code; only 401 and 413 are real HTTP statuses at the transport.

| Code | REST status | Meaning | Agent action |
|---|---|---|---|
| `UNAUTHORIZED` | 401 | Missing, invalid or revoked key or token | Stop and ask the human to reconnect or issue a new key |
| `INSUFFICIENT_SCOPE` | 403 | The key lacks the scope the tool needs | Tell the human which scope is missing (the error links to the key page) |
| `VIDEO_LIMIT_REACHED` | 403 | No video allowance or credits left (no active paid plan or balance) | Hand off: a human must start or renew a plan, there is no free plan |
| `INSUFFICIENT_CREDITS` | 402 | Balance is below the cost; the error states credits needed and available | Report the numbers to the human; do not retry |
| `RATE_LIMIT_EXCEEDED` | 429 | Per-key hourly limit reached; the message carries the reset time | Wait until the stated reset time, then retry |
| `TOO_MANY_PENDING_VIDEOS` | 429 | Three videos are already rendering | Poll list_videos and retry after one finishes |
| `INVALID_TOPIC / TOPIC_TOO_LONG / INVALID_DURATION / INVALID_ALLOW_DUPLICATE` | 400 | Validation error in the arguments | Fix the argument (topic up to 500 characters, duration 30, 60 or 90) and retry once |
| `PAYLOAD_TOO_LARGE` | 413 | Request body over the size cap | Send a smaller request |

## Handing off to the human
- After create_video, give the human the video id and, once COMPLETED, the videoUrl, so they can review it.
- When a call fails with UNAUTHORIZED, INSUFFICIENT_SCOPE, VIDEO_LIMIT_REACHED or INSUFFICIENT_CREDITS, stop and tell the human exactly what they need to change; these are not retryable by the agent.
- For a clip job, summarise the ranked clips (times, score, reason) and let the human decide which to use; exporting and posting are done in the web app.

## Human oversight (what exists today)
- **Approve access**: OAuth consent screen (src/app/api/oauth/authorize): shows the client name and what it can do (create videos, read videos and status, read credit balance and API usage) with Allow and Cancel. Nothing is connected until the owner presses Allow.
- **See what is connected**: Dashboard, API keys lists every key with its name (OAuth connections appear as 'MCP: <client>'), scopes and last-used time.
- **Revoke**: Revoking a key in Dashboard, API keys cuts the agent off on its next call. Deleting the key has the same effect.
- **Limit what a key can do**: Scopes are set per key (video:read, video:create, credits:read, usage:read, and others); a read-only key cannot create videos. Each key has its own request limit.
- **Spending cap**: Spending is prepaid credits: create_video is refused up front when the balance is short, and at most three videos can render at once. There is no separate per-key spend cap.
- **Review what the agent did**: Videos the agent creates appear in the dashboard's Videos list like any other; API usage per key is recorded and shown in the developer portal's Usage tab.
- **Safe-by-default tool hints**: Six tools are annotated readOnlyHint: true. create_video is annotated readOnlyHint: false, destructiveHint: false, idempotentHint: false, so MCP clients that honour the hints ask the human before running it.
- **No destructive tools**: The MCP server has no tool that deletes, uploads, buys credits or changes the plan.

Full page: https://remixviral.ai/en/mcp