MCP server

Make capsules from your agent

Connect Claude, ChatGPT, Cursor or any app that speaks MCP to your Capsules workspace. Ask it to turn an article into a capsule, change a scene, animate the stills or build a preview. It works with your account and only the permissions you give it.

Server URL

https://api.staging.capsules.ink/mcp

Connect your app

Add the server once. The first time your app uses it, you sign in to Capsules and choose what it may do.

Claude (claude.ai and Claude Desktop)

Open Settings, then Connectors, and choose Add custom connector. Paste the server URL and connect. Claude opens the Capsules sign-in page.

ChatGPT

In Settings, add a custom connector (MCP server) with the server URL. ChatGPT opens the Capsules sign-in page when you connect.

Claude Code

Terminal

claude mcp add --transport http capsules https://api.staging.capsules.ink/mcp

Then run /mcp inside Claude Code and choose capsules to sign in.

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "capsules": {
      "url": "https://api.staging.capsules.ink/mcp"
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "capsules": {
      "type": "http",
      "url": "https://api.staging.capsules.ink/mcp"
    }
  }
}

Any other app

Point it at the server URL. It speaks Streamable HTTP and signs in with OAuth 2.1, so any current MCP client can connect. Apps that can't sign in can use an API key.

Sign-in and permissions

When you connect, Capsules shows which app is asking and where it will send you back. You choose the workspaces it can reach and what it may do in them:

ReadSee your capsules, scenes, styles, credit balance and job statusOn by default

Create and editCreate, edit and delete capsules, scenes and stylesOn by default

Spend creditsSpend workspace credits on AI generation (scene analysis, style probes, images, animation)On by default

PublishPublish and unpublish capsules on the public webOff unless allowed

Viewing is always included. Publishing stays off unless you tick it, and is only offered if your role can publish in a workspace you chose. If you choose more than one workspace, your agent asks which one to use when it isn't clear.

You can see and disconnect every connected app in Settings, Connected apps. Disconnecting stops it immediately.

Things to ask

Talk to your agent the way you would talk to an editor. A few to start with:

Turn https://example.com/my-essay into a capsule.
Make a capsule from this draft, in my Studio workspace. Keep my words exactly.
Show me scene 3 and redo it at dusk, same people, same street.
What would animating every scene cost? Go ahead if it's under 200 credits.
Build the preview and send me the link.
Review my latest capsule for continuity problems before I publish it.

A capsule from a link takes a few minutes: the text is imported as written, split into scenes, given a visual style, and each scene gets a still. Animation is a separate step, because it costs more.

Teach it the craft

The Capsules skill gives your agent the craft behind a good capsule: story structure, choosing a visual style, writing motion, data scenes and spending credits carefully.

Claude: download capsules-skill.zip and upload it where Claude's settings list your skills.
Claude Code and other agents: save SKILL.md as ~/.claude/skills/capsules/SKILL.md, or wherever your agent reads skills.
Agents reading the web: llms-full.txt covers connecting, every tool and the same craft notes.

Credits and safety

Generation uses your workspace's credits, the same as in the editor. Your agent tells you what a batch will cost before it runs, and can check prices and your balance at any time.
Failed generations are refunded automatically, and a cancelled animation is refunded.
Slow steps never run twice by accident: if your app times out, the work carries on and your agent picks up the result instead of starting again.
Your words are imported as written. Your agent never publishes, or emails your subscribers, unless you ask it to.
Deleting a capsule or a scene cannot be undone. Your agent is told to delete only when you ask, and most apps confirm risky actions with you first.

Use an API key instead

For apps that can't sign in, create a key in Settings, API Keys (on plans with API access) and send it as a bearer token. A key reaches the one workspace it was created in, with every permission, including publishing. Treat it like a password and revoke it when you're done.

~/.cursor/mcp.json

{
  "mcpServers": {
    "capsules": {
      "url": "https://api.staging.capsules.ink/mcp",
      "headers": {
        "Authorization": "Bearer cap_your_api_key"
      }
    }
  }
}

Tool reference

What your agent can do, grouped by the permission each needs. This list comes straight from the server.

Read (capsules:read)

get_accountAccount and workspaces: Who this connection acts as: the user, the workspaces it can reach (and which is the default), the default workspace's plan and credit balance, and what this connection is allowed to do. Call this first in a session.
list_workspacesWorkspaces this connection reaches: Every workspace this connection can act in, with your role, plan and credit balance in each. Tools that create, list styles or spend credits outside an existing capsule take one of these ids as workspaceId; ask the user which workspace when it isn't clear.
list_capsulesList capsules: Capsules this connection can reach, most recently edited first; each says which workspace it lives in. Pass workspaceId to list one workspace. Filter by title text or published state; page with nextCursor.
get_capsuleGet a capsule: A capsule with its ordered scenes: each scene's reader text, image prompt, motion prompt, and whether its still image and animation exist or are generating. Use this to check progress after generating. Long scene text is truncated unless fullText is true.
get_sceneGet a scene: One scene in full: untruncated reader text, image and motion prompts, generation status and errors, and its cinematic direction (beat, shot, angle, lens, light).
view_scene_imageLook at a scene's image: See a scene's still image (or its end frame) so you can check it against the text and the rest of the capsule: identity, wardrobe, setting and any exact data or labels.
list_stylesList styles: Visual styles a workspace can apply to its capsules: Capsules house styles and the workspace's own. Attach one with update_capsule (styleId); images generated afterwards follow it.
view_style_candidatesLook at style candidates: See candidate images from probe_style (up to 5 at a time) to judge which fit the brief and the writing.
list_modelsImage and animation models: The image-generation and animation models available, with their credit cost. Pass a slug as modelSlug to generate_scene_image, probe_style or animate_scene to pick a model; omit it to use the workspace default.
list_voicesNarration voices: Voices available for scene narration (the audiobook layer). Set one on a capsule with update_capsule (narrationVoiceId, narrationVoiceProvider) before generate_narration.
quote_animationPrice an animation run: What animating scenes would cost in credits (at each scene's default model) and whether the workspace can afford it. Without sceneIds, quotes every scene that has an image but no animation yet. Spends nothing.
get_preview_statusPreview readiness: Whether the draft preview's clips are encoded and ready to scroll, and the preview URL.
get_publicationPublication state: Whether a capsule is published, its public URL and slug, and whether it is unlisted.
get_operationCheck a running operation: Poll a slow tool call that returned status "running" with an operationId. Returns the final result once done. Poll every 15-30 seconds; operations usually finish within a few minutes.

Create and edit (capsules:write)

import_articlePreview an article import: Fetch a web page and extract its article text, to check what a capsule would be made from. Returns the title, word count, an opening excerpt and image candidates. To actually make a capsule from a URL, call create_capsule with sourceUrl — the full text then goes straight into the capsule without passing through you.
create_capsuleCreate a capsule: Create a new draft capsule in a workspace from a URL (sourceUrl — preferred: the article text is imported verbatim server-side) or from text you provide (content — pass the author's words exactly; never summarize). Next step is usually analyze_into_scenes, or upsert_scenes to lay out scenes yourself. Nothing is published.
update_capsuleUpdate a capsule: Change a capsule's title, style, source text, reader presentation, generation mode or narration settings. readerSettings is merged into the existing settings (unlisted keys are kept). Changing content replaces the source text used by analyze_into_scenes; existing scenes are not touched.
delete_capsuleDelete a capsuleCannot be undone: Permanently delete a capsule and all its scenes. Cannot be undone. Only do this when the user explicitly asks to delete this capsule (or to clean up a draft you just created that failed).
upsert_scenesLay out scenes: Create or update a capsule's scenes in one call, in the order given (array order becomes scene order). Include id to update an existing scene; omit it to create one. Existing scenes you leave out are kept and placed after these — remove them with delete_scene. Pass text verbatim; text, imagePrompt and motion are separate fields, never copies of each other.
update_sceneEdit a scene: Change one scene's title, reader text, image prompt, motion prompt, kind or layout. Only the fields you pass change. Editing the image prompt does not regenerate the image — call generate_scene_image for that.
delete_sceneDelete a sceneCannot be undone: Remove a scene from its capsule; later scenes are renumbered. Its media is not recoverable from the capsule.
reorder_scenesReorder scenes: Set the capsule's scene order. Pass every scene id of the capsule, in the new order.
attach_image_from_urlUse an image from a URL: Import an image from a public URL (jpeg, png, webp, gif or avif, up to 20 MB) and set it as a scene's still image or end frame, instead of generating one. Use only images the user has the right to use.
propose_style_briefsPropose visual directions: Read a capsule's text (at least 200 characters) and propose three visual-direction briefs: [0] cinematic photoreal, [1] metaphorical/abstract, [2] a wild-card illustrated look. Don't default to [0] — pick the most distinctive fit for the writing (or show the user). Pass the chosen brief to probe_style. No credits.
lock_in_styleSave a style: Save chosen probe_style candidates as a reusable style in a workspace. Returns the style id — attach it to a capsule with update_capsule (styleId). No credits.
build_previewBuild the draft preview: Prepare the capsule's draft reader: encodes every scene clip for scroll playback and points the preview at the latest content. Doesn't publish anything. Encoding takes a few minutes after clips change — poll get_preview_status until ready, then share previewUrl so the user can scroll it.

Spend credits (capsules:generate)

analyze_into_scenesSplit text into scenes (AI)Cannot be undone: Costs 3 credits. Reads the capsule's source text and splits it into scenes, each with reader text, an image prompt and a motion prompt. Takes 30-120 seconds; may return an operationId to poll with get_operation. Re-running on a capsule that already has scene text or media re-derives the scenes, so it needs reanalyze: true and the user's go-ahead.
probe_styleGenerate style candidates: Costs credits (one image's price per candidate, refunded for any that fail). Generates candidate images for a visual brief so a style can be chosen. Takes 20-90 seconds; may return an operationId to poll. Look at the results with view_style_candidates, then save the ones that work with lock_in_style. To refine, pass the best candidates' storageKeys as referenceStorageKeys plus a steer.
generate_scene_imageGenerate a scene image: Costs credits (see list_models). Generates a scene's still image (or end frame) in the capsule's style, from the scene's image prompt unless you pass prompt. mode: generate (first image), regenerate (same idea, new take), new-idea (fresh composition) or edit (change the current image per prompt). The previous image is kept as an alternative; a regenerated still clears the scene's animation (the old clip is kept as an alternative). Takes 10-60s; may return an operationId. Check the result with view_scene_image.
generate_missing_imagesGenerate all missing images: Costs credits per image. Generates a still for every scene in the capsule that has an image prompt but no image yet, one at a time, in the capsule's style. Stops at the first credit or style problem. Usually runs for minutes, so expect an operationId to poll with get_operation.
animate_sceneAnimate a scene: Costs credits (see quote_animation / list_models). Starts animating one scene's still into a short clip — one continuous shot driven by its motion prompt (or motion, for this run only). Returns immediately; the clip takes 2-5 minutes. Watch video.status via get_scene or get_capsule. Any existing clip is kept as an alternative.
animate_scenesAnimate many scenes: Costs credits. Quotes, then starts animating several scenes (default: every scene with an image and no clip). Refuses if the workspace can't afford the quote or it exceeds maxCredits. Returns once all are submitted; clips finish over the next few minutes (watch get_capsule progress.animating).
cancel_animationCancel an animationCannot be undone: Stop a scene's in-progress animation; its credits are refunded. Use when the user asks to stop it or you started the wrong one. A scene animated as part of a continuous take cancels the whole take. Check get_scene afterwards: video.status returns to idle.
generate_narrationNarrate a scene: Costs 1 credit. Synthesizes the scene's reader text as audio for the capsule's audiobook layer. The capsule must have narration enabled (update_capsule narrationEnabled: true, plus a voice from list_voices).

Publish (capsules:publish)

publish_capsulePublish a capsule: Make a capsule public on the web (or republish it with the latest edits). Only call this when the user has explicitly asked to publish this specific capsule. premiereEmail decides whether the workspace's subscribers are emailed on first publish — ask the user which they want; never assume.
unpublish_capsuleUnpublish a capsuleCannot be undone: Take a published capsule offline; its public URL stops working. Only when the user explicitly asks. releaseSlug frees the slug for another capsule.

Troubleshooting

It says it isn't allowed to do something: The connection wasn't given that permission. Disconnect it in Settings, Connected apps, connect again and tick the permission.
It keeps asking which workspace to use: You gave it more than one. Name the workspace in your request.
The sign-in page says the request expired: Sign-in requests last 30 minutes. Start the connection again from your app.
It says there aren't enough credits: The workspace owner can top up in Settings, AI credits.
It says the capsule is locked: Someone has it open in the Capsules editor. Try again once they're done.