Riverside

View saved version →

---
name: content-discovery
description: Use when the user wants to search, find, list, browse, or retrieve their Riverside content — productions, studios, projects, recordings, edits, exports, transcripts — by what was said in it, by its title or topic, or by where it lives; when they ask for a download or share link; or when another workflow first needs a studioId, productionId, projectId, sessionId, or editId. Not for creating or changing an edit (see video-editing), and not for publishing to social platforms (see social-publishing).
---

# Content discovery

Read-only search and navigation over the Riverside platform. Hierarchy tools
carry a `platform_` prefix and search tools carry a `search_` prefix; nothing on
this surface modifies content. Copy tool names verbatim.

**The live tool schemas are the authority.** Required and nullable fields, date
windows, limits, defaults, page sizes, and pagination tokens all come from the
schema of the tool you are about to call — never from memory, from an earlier
session, or from a number written in a skill file. Read the schema, then call.

## The entity bridge

A production contains studios. A studio contains projects. A project contains
both recordings and edits. An edit produces exports.

Which id crosses into another skill:

- **`studioId`** — social publishing needs one, and so do the brand and captions
  editing tools. No editing or social tool can discover a studio, so it has to
  come from here. A studio also carries its `productionId`.
- **`sessionId`** — the recording-session identifier used by transcript reads
  and edit creation. Reuse a recording's `id` only when the live response or
  schema says that item is the same session (for example, some upload or
  single-take records). For multi-take material, confirm the intended take or
  start from an existing project edit instead of assuming the ids coincide.
- **`editId`** — one cut of one or more recordings. Social publishing consumes
  it as the `clipId`.
- **`exportId`** — one rendered file. No tool returns its download link; send
  the user to the edit's `riversideUrl` instead.

## Where to read next

| Need | Read |
|---|---|
| Find content by exact words, topic, or title | [Search](references/search.md) |
| Browse hierarchy, determine latest, page completely, or get a rendered file | [Hierarchy navigation](references/hierarchy-navigation.md) |
| Resolve or hand off IDs for editing or social publishing | [Cross-skill handoffs](references/cross-skill-handoffs.md) |

**Routing contract:** Before the first Riverside workflow call, evaluate every
row against the observable request and state. Read every matching reference and
no unrelated reference. After each Riverside response, evaluate every row
again before the next workflow call; read any newly matching reference first.
Only this table routes references — a reference never routes to another one.

## Rules that hold in every flow

- **Ask, don't guess.** When more than one studio, project, recording, or edit
  fits what the user described, show the candidates and let them pick. Guessing
  produces a confident answer about the wrong content.
- **Keep broad requests broad.** Scoping parameters such as `projectId` on
  `platform_list_recordings` and `platform_list_edits` are optional. Omit them
  for "all my recordings"-style requests, and never carry a narrow scope
  captured in an earlier step into a request the user did not scope that way.
- **Links come from the platform.** Studios, projects, recordings, and edits
  each carry a `riversideUrl`. Return the one the server gave you; never
  construct or guess a URL, and never build one from an export's `s3Key`.
- **Preview links are opt-in.** `platform_get_recording` withholds the
  token-bearing `previewUrl` unless asked. Set `includePreviewUrl` only once the
  user has explicitly asked for a shareable preview, and read a null value as
  "no share link exists right now".
- **Verify readiness before sharing.** Recording

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: podcast-hosting
description: Use when the user wants to browse or manage a Riverside hosted podcast, create or update an episode, change podcast artwork, distribute a show, or read podcast download analytics. For video edits use video-editing; for clips posted to social accounts use social-publishing.
---

# Podcast hosting

Manage hosted shows and episodes through the `hosting_` tools on the same
Riverside connection. Read the current tool schema before each call; schemas,
`hosting_get_hosting_config`, and `hosting_get_podcast_guidelines` govern valid
values and prerequisites. A missing tool is unavailable in this connection.

## Resolve the show and source

Use `hosting_get_user_context` to establish the connected account. Browse with
`hosting_list_podcasts` and `hosting_list_episodes`; inspect selected objects
with `hosting_get_podcast` and `hosting_get_episode`. Page according to the
current schemas. Ask the user to choose when several shows or episodes fit.

Podcast and episode IDs are UUIDs. Studio identifiers are not interchangeable:
`hosting_create_podcast` takes the studio **slug**, while
`hosting_list_podcasts` takes the studio **id**. Resolve both from
`platform_list_studios` or `platform_get_studio`; keep their field names.

Episode creation takes exactly one source:

- `sessionId`: the recording session ID. The hosting schema identifies the
  `id` returned by `platform_list_recordings` or `platform_get_recording` as
  this value; verify the intended recording.
- `idClip`: a verified Riverside clip ID. Do not substitute an edit ID from
  `platform_list_edits`. If the clip ID is unknown, ask the user for the clip
  ID displayed beneath the recording on the Riverside project page.

## Create and update

Before metadata writes, read `hosting_get_hosting_config` and
`hosting_get_podcast_guidelines`. Collect the fields required by the live
schema, including podcast categories and language. Podcast categories are
hosting metadata, independent of the plugin directory's Creativity category.

`hosting_create_podcast` creates a draft. If its optional artwork upload fails,
the show may already exist: preserve the returned podcast ID and retry only
`hosting_upload_cover_art` when requested. Do not create a second show.

Use `hosting_create_episode` for the chosen source and
`hosting_edit_podcast` or `hosting_edit_episode` for requested changes. Preserve
fields the user did not ask to change. For a publication date, resolve the
user's timezone and supply the schema's date and timezone fields; clarify an
ambiguous wall-clock time before writing.

Before publishing, scheduling, changing public metadata, replacing artwork,
or connecting a distribution platform, show the target show/episode and exact
changes and obtain confirmation. Confirmation of draft creation does not
authorize subsequent publication or distribution.

After a write, read the affected podcast or episode. Episode processing can
continue after creation; report the returned state and use bounded status
reads instead of recreating it. Before publishing a new episode, read
`hosting_get_episode` and wait until it is ready. Stop and report processing or
failed instead of sending a publish update. Do not force a processing episode
to ready. After an unknown mutation outcome, reconcile with list/get reads
before considering another write.

## Artwork and distribution

`hosting_upload_cover_art` replaces show artwork.
`hosting_upload_episode_artwork` replaces square episode art or a video
thumbnail; a linked YouTube thumbnail may change as well. Use the current
schema's size, format, and dimension rules. Image sources must be final public
HTTPS URLs; do not send private URLs or credentials, or rely on redirects.

Use `hosting_connect_platform` only for a requested, confirmed destination.
The current workflow requires a nonprivate show and a published episode.
Read live platform guidance: submitting a new show differs from supplying the
URL of an existing show. A

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: setup
description: Use when installing or connecting Riverside on Claude Code, Cursor, ChatGPT, or Codex; when authentication, 401, auth-loop, tool-not-found, account, or plan issues prevent tools from working; or when a feature-disabled or precondition error might be mistaken for a connection failure. Do not use for normal content, editing, or publishing after the connection works.
---

# Setup and connection

This plugin wraps Riverside's remote MCP server at `https://mcp.riverside.com/mcp`.
The tools run against the user's own Riverside account over an authenticated
connection.

## Requirements

- **A Riverside account.** Sign up or sign in at https://riverside.com.
- **A qualifying paid plan.** The MCP is available only on qualifying Riverside
  paid plans; Free and Pro accounts are not admitted, and their tool calls will
  not authorize. Plan details are at https://riverside.com/pricing.
- A supported client with this plugin installed and enabled — Claude Code (CLI,
  desktop, or IDE extension), Cursor, ChatGPT, or Codex.

Each client authenticates separately. Connecting Riverside in one client does not
connect it in another.

## First-time connection

How the connection is established depends on the host family. Every path ends in
the same place: a browser sign-in at Riverside, after which the tools work.

### Claude Code and Cursor — connect on the first tool call

The connection is set up once, on the **first tool call**:

1. Trigger any Riverside tool (e.g. ask to list your studios or productions).
2. The client opens Riverside's hosted sign-in in your browser. It finds that
   page automatically by discovering the MCP endpoint, so there is no URL to
   enter by hand. Clients register themselves via Dynamic Client Registration —
   there is no client ID or secret to configure.
3. Sign in and approve access. The prompt asking whether to grant the client
   access belongs to your client, not to Riverside.
4. The browser hands the authorization back to the client, the MCP server
   connects, and the tool call proceeds.

### ChatGPT and Codex — connect before the first tool call

There is no first-tool-call prompt on these hosts. Use the connection lane the
host currently exposes.

Before connecting ChatGPT:

- The Riverside account must be on a qualifying paid plan; Riverside Free and
  Pro accounts are not admitted.
- Write actions must be separately enabled for the ChatGPT workspace. Which
  plans allow them is OpenAI's to define and changes, so check their
  developer-mode docs. Admins may also need Developer Mode on and Riverside
  approved.
- Use ChatGPT on the web. MCP apps are not available on mobile.

#### Before the directory listing is available

- **ChatGPT:** in the browser, enable Developer Mode under **Settings → Security
  and login**. Open **Plugins**, select **+**, name the connection Riverside, use
  `https://mcp.riverside.com/mcp`, choose OAuth, create it, and complete the
  Riverside sign-in.
- **Codex:** run
  `codex mcp add riverside --url https://mcp.riverside.com/mcp`, then
  `codex mcp login riverside`. Run `/mcp` in a Codex session to confirm the tools
  are listed.

Do not use an `npx` or `mcp-remote` bridge; both hosts support the remote HTTP
endpoint and OAuth directly.

#### After the directory listing is available

Two independent things have to be true:

1. **The plugin is installed and enabled.** This supplies the five Riverside
   skills — the guidance the model follows.
2. **The Riverside app is enabled, connected, and signed in.** This supplies the
   tools themselves. Find Riverside among the host's apps or connectors and
   complete the sign-in from its settings.

In either lane, the plugin and Riverside connection are managed separately and
can fail separately:

| State | What the user sees |
|---|---|
| Plugin installed, connection signed in | Riverside skills load and the tools work |
| Plugin installed, connection missing | The skill still loads, but no Riverside tools 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: social-publishing
description: Publish/schedule Riverside clips, manage unpublished posts and social accounts, or read analytics on YouTube, TikTok, Instagram, Facebook, LinkedIn or X. Clip editing uses video-editing; live posts must be edited/removed on their platform.
---

# Social publishing

| Tool | Purpose |
|---|---|
| `social_get_connected_platforms` | Accounts and live limits |
| `social_get_publishing_guidelines` | Platform rules and recovery |
| `social_upload_create` | Publish or schedule a clip |
| `social_get_upload_status` | Publish outcome |
| `social_list_uploads` | Find posts |
| `social_get_upload` | Content and capability flags |
| `social_update_upload` | Change an unpublished post |
| `social_cancel_upload` | Permanently cancel a cancellable post |
| `social_get_upload_analytics` | Collected metrics |
| `social_connect_social_account` | User authorization link |
| `social_disconnect_social_account` | Disconnect and cancel scheduled posts |

## Safety contract

Create and `publishNow` can produce real posts: never call them to test or
diagnose. No tool can edit, delete or unpublish a live post. Cancellation cannot
be undone. Success, processing, timeout, transport failure and unknown outcomes
may have posted: never repeat the publish. Only explicit failures passing the
recovery gate can become eligible for a fresh publish.

Use current schemas, connected account limits and live guidelines. Resolve
studio/production ids through content-discovery. Publishing needs `clipId`
(typically an exported edit id) and a connected account.

## Mandatory routing

Before social calls, read all matching references and no unrelated ones. After
every response/failure, re-evaluate and read new matches before the next call.

| Observable condition | Required reference |
|---|---|
| Wall-clock/future time, or draft export may need `composeSettings` | [Scheduling and draft export](references/scheduling-and-draft-export.md) |
| Posts, analytics, accounts, or processing/partial/failed/unknown publish (timeout, transport failure or unusable response) | [Results, management and recovery](references/results-and-recovery.md) |
| A publish was made and its outcome is unconfirmed | [Publish outcome](references/upload-status.md) |

"Tomorrow at 9" matches scheduling before its timezone is known.

## Publish workflow

1. Resolve `studioId` and read connected platforms. Select a valid
   `platformAccountId` by account/channel name; ask if studio/account is unclear.
   Empty `accounts: []` may mean failed account-detail lookup. Retry this read
   once; if still empty, report unavailable details and stop.
2. Load `social_get_publishing_guidelines` for the platform. Use current create
   schema and platform counting rules, not raw string length. Ask for YouTube
   privacy from live values; never infer/default it. Before YouTube publishing,
   inspect `editing_get_export_publish_data` and surface copyright/Content-ID
   flags instead of publishing over them.
3. Show exact metadata, account/channel, visibility, resolved schedule and
   compose choices. Explain that a live post cannot be undone here; wait for
   explicit confirmation. It covers one call for that target/payload. Preview
   material changes; retries need new confirmation even if unchanged. Stop on
   refusal, hesitation, changed direction or withdrawn confirmation.
4. Make one `social_upload_create` call per separately confirmed target/payload.
5. Report account, visibility, schedule and outcome per target; re-run routing.

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: video-editing
description: Use when the user wants to cut, trim, clean up, caption, lay out, crop, brand, add overlays, stock media or music to, or otherwise change the content of a Riverside edit, or to turn a raw recording into an editable edit. Not for browsing or searching existing content (see content-discovery), and not for publishing to social platforms (see social-publishing). If the question is whether an editing error is really an authentication or connection problem, use setup first.
---

# Video editing

Server-side timeline editing. Tools are exposed at the gateway with the
`editing_` prefix. Work is keyed by an **`editId`**; revision-aware writes
advance a **`revision`**.

Current tool schemas and the live `editing_get_editing_guide` response are
authoritative for parameters, enums, limits, defaults, and recoverable errors.
This file carries only the invariants no single schema can state.

## Three rules that override everything

1. **Keep operating on the same edit.** When iterating on an existing edit, do
   NOT create a new edit or clone — keep passing the same `editId` and its
   latest `revision`. Create or clone only when the user explicitly asks for a
   separate version. The currently listed entry points
   (`editing_create_edit_from_recording` and `editing_clone_edit`) each return
   an `editId` that becomes the working edit for the rest of the flow.

2. **Thread the revision on revision-aware writes.** When the current write
   schema exposes `expectedRevision`, pass the latest revision back as that
   value; omitting it risks clobbering a concurrent edit. After a successful
   revision-changing write, use the revision it returns for the next such
   write. Preserve the revision's live type and value rather than coercing it.

   Do not generalize this into an argument for every tool that accepts an
   `editId`: reads and some non-revisioned operations do not accept
   `expectedRevision`. The live schema of the specific call decides whether the
   argument exists; the invariant is that you never omit or stale it when it
   does.

   A revision conflict is not retryable. Never replay the same write with a
   newer revision substituted. Stop before another write and evaluate the
   routing table again; the now-observable conflict selects the recovery
   workflow that re-reads and re-derives the operation.

3. **Never mix time axes.** See below. This is the easiest way to silently
   corrupt an edit.

## Time axes — read before computing any time

The timeline has two axes, and tools disagree about which one they take.

- **Source time** — positions in the original recorded media, before cuts.
- **Playable time** — positions on the edited, post-cut timeline the viewer sees.

With no cuts yet the two coincide and the distinction is harmless. Once any cut
exists they diverge, and a number from one axis fed to a tool on the other lands
in the wrong place with no error.

| Axis & unit | Tools |
|---|---|
| **Source**, `{n,d}` fractions of seconds | `editing_read_timeline_in_range` (every returned time: `trackTime`, `timeRange`, `duration`, scene times), fraction-based `editing_batch` params |
| **Source**, integer ms | `editing_add_lower_third` (`startMs`), `editing_add_text_overlay` (`startMs`), `editing_insert_overlay` (`startMs`) |
| **Playable**, integer ms | `editing_cut_time_ranges` (`startMs`/`endMs`), `editing_insert_audio` (`startMs`), `editing_insert_media_as_scene` (`startMs`), `editing_read_aligned_transcript` (`playableStartMs`/`playableEndMs`, and its `startMs`/`endMs` window), `editing_resolve_transcript_selection` (in and out) |

Rules that follow:

- **Never compare or reason across the axes** — not in a tool argument, and not
  in your own analysis. Converting a source `{n,d}` to milliseconds does not
  make it comparable to a playable millisecond value: once cuts exist, "these
  two numbers differ" tells you nothing about whether they name the same moment.
  Two values are comparabl

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 6 — file references are metadata, not package contents.