Use the widget library from your coding agent.

Add the server, sign in, done

Pick your client. Every path ends the same way: a browser opens, you sign in with your normal Scrollytelling account (email or Google), approve the connection, and the client handles tokens and refresh from there. No keys to copy.

claude mcp add --transport http scrollytelling https://api.scrollytelling.ai/mcp

{
  "mcpServers": {
    "scrollytelling": {
      "url": "https://api.scrollytelling.ai/mcp"
    }
  }
}

code --add-mcp '{"name": "scrollytelling", "type": "http", "url": "https://api.scrollytelling.ai/mcp"}'

{
  "servers": {
    "scrollytelling": {
      "type": "http",
      "url": "https://api.scrollytelling.ai/mcp"
    }
  }
}

https://api.scrollytelling.ai/mcp

curl https://api.scrollytelling.ai/mcp \
  -H "Authorization: Bearer stl_your_personal_api_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

What your agent does with it

Three tools cover the whole loop; two more handle your published stories.

Try asking:

• Add a sticky-split section to our landing page: the product photo pinned on the left, three short feature paragraphs scrolling on the right.
• Find a widget for showing our six office locations on a map and render it with our brand colours.
• Turn this list of quarterly numbers into an animated bar chart I can drop into the report page.
• Give me the embed code for our published “Annual report 2026” story for the investors page.
• Which Scrollytelling widget fits a photo essay? Render it with these five images and captions.

Code-generator MCPs vs a component MCP

Most scrollytelling, GSAP and animation MCP servers you find on registries are code generators: you describe an effect and the model writes fresh code from scratch. Useful for one-off snippets, but the output is whatever the model produces that day — untested, unstyled, and yours to debug. Ask twice and you get two different carousels.

The Scrollytelling server is the other kind: a component MCP, the same model shadcn/ui uses. Your agent searches a library of finished, production-tested widgets and gets the real thing — rendered by the exact engine that publishes every Scrollytelling story, with responsive layout, reduced-motion support, lazy-loaded media and documented props already handled. Generation gives you a starting point; a component MCP gives you the shipped thing.

The two are not rivals: let a generator write the glue code around a page, and let the component server hand it the sections that have to work.

What it covers

• The full widget library — Carousel, Stacking cards, Slideshow, Split scroll, Sticky split, Interactive map, Stacking images, Bento grid, FAQ accordion, Chart, Scroll video, Video background — rendered as complete, self-contained HTML (inline CSS and JavaScript, media by URL), with your heading, subheading and design tokens applied.
• Concepts and patterns as agent-readable markdown — which scroll pattern fits which job, pacing and asset guidance, and how to embed the output in any site or framework — served as MCP resources your agent can read before it builds.
• Your published stories — list them, and get a story's public URL, iframe embed, oEmbed endpoint and WordPress shortcode. Read-only: the story stays hosted and updated by Scrollytelling.
• Every plan, including Free — the server never spends credits and never calls an AI model; access follows the account you sign in with.

What it doesn't (yet)

• The AI story generator. Creating a whole story from a brief, a URL or a file happens in the app, where credits and plan limits apply. The MCP server is deliberately a library, not a generator.
• The Form widget. A form needs a published story to receive submissions, so it cannot be a standalone snippet — build it in the editor, publish, then use get_story_embed. (Preview it here.)
• AI Spotlight and custom sections. These are generated per story inside the editor.
• Shopify-only widgets (Product buy box, Product grid) — they need a connected store.
• Editing or publishing stories. The server is read-only; the editor does the writing.
• Scroll-video frame scrubbing from a raw clip. Splitting a video into scrub frames happens in the editor or the scroll-video playground; through MCP a videoUrl renders as an autoplay background, and a frame set you already have renders with real scrubbing.
• Templates and whole-story kits — on the roadmap.

Tools and resources

Every tool is read-only and idempotent. render_widget accepts design tokens — accentColor, backgroundColor, textColor, headingFont, bodyFont — and format: "iframe" for an <iframe srcdoc> snippet.

Common errors

• 401 — not authenticated. Re-run the client's authenticate flow (Claude Code: /mcp → scrollytelling → Authenticate), or check the API-key header if you use one. Tokens last 24 hours and refresh automatically; a disconnected agent (Settings → Integrations) gets a 401 until you approve it again.
• 403 — signed in, but the account can't be used. The account is suspended or deleted. Sign in to the dashboard to see why, or contact support from there.
• “Redirect not allowed” on the sign-in page. The client registered one callback address and sent another. Remove the server from your client and add it again so it registers fresh.
• The browser never opened. Copy the sign-in URL the client printed in its terminal or logs and open it yourself. Approve the connection; the client picks it up.
• Signed in, approved, but the client still says unauthenticated. The client lost the callback — usually a second sign-in tab or a changed port. Run the authenticate flow once more; a fresh approval replaces the old one.
• Tools don't show up. Reconnect or restart the client so it re-reads the server's tool list. The URL must be exactly https://api.scrollytelling.ai/mcp over https.
• Invalid props for <widget>. The tool result says which field is wrong. Images must be public https URLs (or data: URIs), coordinates decimal degrees, and item counts within the limits in get_widget.
• The widget renders, but images are blank. The image host blocks hot-linking or isn't public. Use a URL anyone can open in a private window, or pass a data: URI.
• 429 — too many requests. The server allows 120 calls a minute per connection and 30 sign-in operations a minute per address. Wait a moment; nothing is lost.
• “Not published yet” from get_story_embed. Only published stories have a public URL. Publish from the editor's Publish panel, then ask again. Stories beyond the plan's live-story allowance are offline until you upgrade or take another story offline.
• The map or scroll-video shows nothing inside an iframe. Give the iframe real height (90vh or more): scroll-driven widgets scroll inside their frame. The map also needs the page to reach public tile servers.

Frequently asked questions