Webhooks & integrations

MCP server

Drive ViralSlides from any MCP client, such as Claude Code or Cursor: list apps, generate slideshows, hooks and videos, and publish over MCP.

3 min readLast updated Oct 3, 2026

The ViralSlides MCP server lets an AI client (Claude Code, Claude Desktop, Cursor, or anything that speaks the Model Context Protocol) operate your workspace through tools: list your apps, generate slideshows and hooks, check status, and publish to TikTok/Instagram. It's a thin layer over the same REST API, so everything is scoped to your organization and authenticated with your existing API key.

Pro and Business only

The MCP server uses the same API-key gate as the REST API — your organization must be on Pro or Business. Free/Starter keys are rejected with PLAN_LACKS_API.

Endpoint

It's a remote MCP server over the Streamable HTTP transport. There's nothing to install or run — point your client at the URL and pass your API key as a Bearer header.

Endpointtext

POST https://api.viralslides.app/v0/mcp
Authorization: Bearer vs_live_...

Get a key from /api-keys (see Authentication). The same vs_live_ key works for both the REST API and MCP.

Connect from Claude Code

Add the remote MCP serverbash

claude mcp add --transport http --scope user viralslides \
  https://api.viralslides.app/v0/mcp \
  --header "Authorization: Bearer vs_live_..."

Make it permanent with --scope user

--scope user writes the server to your personal Claude config (~/.claude.json), so it stays available in every project and across sessions. Without the flag, claude mcp add defaults to local scope and only registers the server in the directory where you ran the command. That local scope is the usual reason an MCP server seems to disappear the next time you start Claude from somewhere else. Avoid --scope project here: it writes a committed .mcp.json and would leak your API key into version control.

Verify it stuck with "claude mcp list" (the viralslides server should show as connected), then ask Claude things like "list my ViralSlides apps" or "generate a hot-takes slideshow for CutieCure and show me the slides when it's done."

Connect from Cursor (or any mcp.json client)

~/.cursor/mcp.json (or your client's MCP config)json

{
  "mcpServers": {
    "viralslides": {
      "url": "https://api.viralslides.app/v0/mcp",
      "headers": { "Authorization": "Bearer vs_live_..." }
    }
  }
}

Connect from Claude Desktop

On plans that support custom connectors: Settings → Connectors → Add custom connector, paste the endpoint URL, and add an Authorization header with value "Bearer vs_live_...". Desktop talks to the same remote server.

Available tools

Tool	What it does
list_apps	List the apps in your workspace (id, name, niche, design, tagline).
get_app	Full positioning for one app: offer, audience, value props, pain points.
list_formats	Available slideshow formats (narrative shapes) to pass as template_key.
list_design_templates	Available visual designs (scrapbook, editorial, bold, listicle, inspo, ...).
generate_slideshow	Generate a slideshow for an app. Async — returns a slideshow_id with status PENDING. Counts against your monthly quota.
get_slideshow	Poll status; once COMPLETED returns slide image URLs, caption, and hashtags.
list_slideshows	List recent slideshows, optionally filtered by app or status.
generate_hooks	Brainstorm scroll-stopping hooks grounded in the app's pain points and offer.
get_usage	Your plan, its limits, and slideshows generated this billing period.
publish_slideshow	Publish a COMPLETED slideshow to the app's connected TikTok or Instagram, as a photo carousel or (content: video) its video.
render_video	Render the slideshow as an MP4 on our servers, with optional AI voiceover and music. 2 credits.
get_video_brief	Everything your agent needs to build its own motion video: instructions, specs and safe area, brand colours and fonts, per-scene text and raw photos.
create_video_upload	A short-lived upload link for an MP4 your agent rendered.
attach_video	Checks the uploaded MP4 and sets it as the slideshow's video, ready for publish_slideshow.

Motion videos made by your agent

Agents like Claude Code can build rich motion videos in code (for example with Remotion). Ask for one in plain words, or run the make_motion_video prompt your client lists. The agent calls get_video_brief, renders a 1080x1920 H.264 MP4 on your machine, uploads it, attaches it, and shows it to you before anything is posted. Agent-made videos use no credits.

The flowtext

get_video_brief(slideshow_id)          -> scenes, brand, specs, instructions
(render video.mp4 locally)
create_video_upload(slideshow_id)      -> upload_id, upload_url
curl -X PUT -H "Content-Type: video/mp4" --upload-file video.mp4 "<upload_url>"
attach_video(slideshow_id, upload_id)  -> checked: H.264, 9:16, 5 to 60 s, under 200 MB
publish_slideshow(slideshow_id, platform, content: "video")   after you approve

Prefer not to render anything yourself? render_video makes the video on our servers (slides with motion, optional voiceover and music) for 2 credits. Poll get_slideshow until video_status is READY.

Generate then poll

generate_slideshow returns immediately with status PENDING — rendering runs in the background (usually under a minute). Call get_slideshow with the returned id until status is COMPLETED (then read slides/caption/hashtags) or FAILED (read the error field).

publish_slideshow posts publicly

publish_slideshow posts to your live TikTok/Instagram and cannot be undone. It requires a plan with publishing enabled and the platform account connected to the app, and the slideshow must be COMPLETED. Confirm before letting an agent call it — a good MCP client will ask you to approve the tool call.

Auth, quota, and limits

Auth: same vs_live_ key as the REST API, sent as Authorization: Bearer. Revoke it from /api-keys and MCP access stops immediately.
Scope: every tool is scoped to the key's organization — there is no cross-org access.
Credits: generate_slideshow uses 1 credit and render_video uses 2, from the same monthly pool as the dashboard and REST API. Agent-made videos (attach_video) are free. Out of credits, the tool returns QUOTA_EXCEEDED.
Rate limits: MCP shares the same per-minute API rate limit as the REST surface (see API → Overview).
Transport: stateless Streamable HTTP — each call is self-contained and authenticated; there are no sessions to manage.