Control Storyblok From Claude Code

A marketing lead asks Claude Code for three headline variants on a product card. Each one is written into Storyblok as a draft version of the story, and each one is visible in the Visual Editor at the preview URL the space already has configured. They pick the strongest, ask for one more pass on the subheadline, then publish it themselves. Twenty minutes from a blank prompt to a live page, with nobody opening the content dashboard and nobody pasting text between two windows.

The setup for that is one command. What makes it safe to run on a real site is that Storyblok moved the read, write and delete boundary into the server itself, so the permission model you would otherwise hand-build is now a thing you switch on.

Any walkthrough that has you run pnpm add -g @storyblok/mcp-server, edit ~/.claude/mcp.json, and pass a --mode=draft flag is describing a setup that does not exist. There is no such package, the flag is not real, and that is not the file Claude Code reads. The current server is hosted. You connect to it, you do not install it.

Why this only works now

Storyblok has had a Management API for years, and Claude has had tool use since 2024. What was missing was a stable way for a model to discover what an API can do and call it without somebody writing a bespoke integration first. MCP, the Model Context Protocol, is that layer, and Storyblok now runs an official server on it. DatoCMS runs one too.

What makes it shippable on a client site is the approval step sitting in front of every tool call. That gate is only worth anything if you have decided in advance what it guards, which is why we keep a short written list of the lines we do not let an agent cross in a client system.

How do you set up the Storyblok MCP server?

One command, then a browser tab. Add the hosted server to Claude Code, run /mcp, pick Storyblok, and sign in. On the authorisation screen you define read and write permissions per scope and select the spaces the connector can access, then allow it. Nothing lands on your filesystem and there is no token to copy.

claude mcp add --transport http Storyblok https://mcp.storyblok.com/mcp

For scripted or non-interactive use, or a client that has no OAuth support, Storyblok also accepts a personal access token sent as an Authorization: Bearer <TOKEN> header instead.

One limit to know before you plan around it. The server exposes the Management API only, and it cannot read published content through the Content Delivery API. Storyblok documents the whole tool surface at its MCP server page.

What can the server actually do?

Seven tools, graded by blast radius. Two map the API surface, three execute work at increasing levels of risk, and two handle asset uploads. Most operations are scoped to a space and take a space ID per call, so the agent has to name the space it is working in every single time.

Tool	What it does	Blast radius
`search`	Finds Management API operations by keyword	None
`describe`	Returns the full parameter detail for one operation	None
`execute_readonly`	Runs safe read operations (GET)	Read
`execute_mutating`	Runs mutating operations (POST, PUT, PATCH)	Writes content
`execute_destructive`	Runs destructive operations (DELETE), and requires explicit confirmation	Removes content
`upload_asset`	Creates an asset record and returns a signed S3 upload URL	Writes an asset
`upload_asset_finish`	Finalises and validates the asset upload to S3	Writes an asset

You could build that grading yourself out of two API tokens, one read-only and one draft-write, wired into two separate server entries. Storyblok ships the boundary instead, so you get it without maintaining that config.

What does an agent actually edit in Storyblok?

Bloks. Storyblok’s own definition is that a block “can be an entire entry (a story), or it can be just one piece of an entry.” Content type blocks are the stories themselves. Nestable blocks are the children that sit inside them, a hero or an image or a text section. Universal blocks work as either. Everything available in a space is listed in the Block Library.

The mapping that matters once an agent is reading API responses: the Technical name of a block is the value of the component key. So when Claude pulls a story back, the JSON it gets is your schema rather than a wall of text, and every field it wants to change has a name that came from your content model. That is the same reason structured content pays off for SEO and AI: a typed shape is legible to a machine in a way free text never is.

A Blocks field can also restrict what is allowed inside it, which is the part worth configuring before you point an agent at a space:

restrict_components turns the restriction on. It defaults to false, meaning everything is allowed.
component_whitelist is an array of nestable or universal block names permitted inside Blocks, Link and Richtext fields.
component_group_whitelist takes group (folder) UUIDs instead, and component_tag_whitelist takes tag IDs.

Restricting by group is usually the better call. A new block dropped into that folder is allowed automatically, so nobody has to go back and edit a dozen field definitions when the design team adds a variant.

Can Claude publish a story on its own?

Only if you decide it should, and the default keeps it well away from the live site. Saving a story creates a draft version. Publishing is a separate call, a GET to /v1/spaces/:space_id/stories/:story_id/publish. The Content Delivery API defaults to version=published, so a draft the agent wrote is not reachable by a visitor until a person acts.

Storyblok shows three states in the content list, and they are worth knowing because they are what an editor will be looking at after an agent has been working:

Draft or unpublished: gray dashes. The story only appears in preview versions.
Published: solid green. The story is accessible to website visitors.
Changed: green dashes. Published, then edited. The edits only appear in preview versions until somebody republishes.

That third state is the one that makes agent work comfortable. An agent can rewrite a field on a page that is already live, and the version visitors see stays exactly as it was until a human republishes.

Review does not need a deploy either. The Visual Editor loads your site in an iframe at the Preview URL you set under Settings, fetching the draft version, and the StoryblokBridge reloads the page on each save or publish event. So the surface where somebody checks agent-written copy is the surface the editor already works in every day.

If a change should go live later, story_schedulings handles it. The endpoint creates, retrieves, updates and deletes a schedule to publish a story at a given date and time. In the interface it is More Options next to Publish, then Schedule Publishing.

What is this good for

Patterns that earn their keep on a real marketing site:

Copy variants written in place. Four headline options for a hero blok, saved as drafts, compared side by side in the Visual Editor before anyone publishes.
Reading across a content set. “Pull every story of type blog_post and tell me which ones have no link to a service page.” The agent works through it in the conversation and you fix the gaps.
Metadata at volume. Alt text, SEO fields, category references across a content set. A hand-written script would run faster, though somebody has to write it first.
Translation triggers. Picking a story, sending it out for translation, writing the result back as a draft. We went through the design of that pipeline in our piece on translation workflows.
Schema questions. “Which blocks accept a feature_card?” The search and describe tools exist so the agent maps the real API surface before it commits to a call.
Work that spans tools. Reading a week of Search Console data and drafting new descriptions against the stories that need them, in one conversation instead of three tabs and a spreadsheet.

The connecting thread is routine reasoning over content that already has a shape. That is where the model is reliable and where a typed CMS keeps it honest.

Where it breaks down

Storyblok is direct about this in its own documentation. The MCP server is meant for one-off changes, prototyping, and tasks where you describe an outcome in natural language. For repeatable, high-volume work and anything living in a CI/CD pipeline it points you at the Storyblok CLI, which has dry runs, idempotency guarantees and scriptable commands. Take the vendor at its word on that.

Beyond it, four jobs where this is the wrong instrument:

Schema changes across a space. Renaming a field that 2.000 stories depend on wants a versioned script with a dry run. An agent can draft that script for you, and it should not be the thing executing it against live content.
Multi-language work that needs glossary discipline. Marketing copy through an AI translation step is fine. Legal text, or any term where the wrong choice is invisible to the reviewer, is not.
Changes where the record matters more than the minutes. Regulatory wording, contract terms, anything somebody will read back under pressure a year from now. Make those in the Storyblok interface so the version history names the person who decided.
Unattended publishing. execute_destructive demands a confirmation from the server. Publishing deserves the same treatment even though Storyblok exposes it as a read-shaped call. Publishing should never be auto-approved, however confident the model sounds.

The governance pattern

Three rules we apply on any Storyblok space an agent can reach:

Leave the approval defaults where Storyblok put them. Storyblok ships the read-only and the write and delete tools set to Needs approval, and execute_readonly is the tempting one to relax, because reads look harmless. Publishing a story is a GET, and execute_readonly is documented as the tool that runs GET operations. Storyblok does not say how it routes the publish call, so an auto-approved read tool is a plausible path to an unattended publish. Leave the approval on until you have tested that specific call against a space you can afford to break.
Draw the environment boundary in the OAuth grant. A space is a content repository with its own stories, blocks, assets, datasources and configuration, including its own workflows, users, roles and access tokens. Because the authorisation screen asks which spaces the connector may reach, the staging-versus-production line becomes an account fact. It stops being a discipline somebody has to keep by managing two sets of credentials correctly.
Keep attribution intact. Every save creates a version, and OAuth means the agent acts as a signed-in account, so every one of those versions carries a person’s name. Somebody who trips over an unexpected edit six months from now should get a name and a timestamp, not a shrug.

This is the access control any job that can write to production already gets.

The expensive half: a brand-correct block library

The MCP wiring is a morning of work. What decides whether agent-written pages look like your brand is the set of components rendering those bloks, and that work finishes long before anyone on the marketing team opens a terminal. It is built once by design and engineering, over months, and handed over. Nobody in marketing edits a component or a block schema to use it.

What a complete library looks like:

Every block in the Block Library has one finished, design-signed rendering. Hero, intro, feature grid, testimonial, FAQ, CTA, footer reassurance. The full set a landing page needs. Marketing picks blocks and the visual result is already settled.
The whitelist on each Blocks field decides what fits where. A legal section cannot receive a marketing-styled block, because Storyblok rejects the combination before the API call lands.
Each variant is its own block. “Hero, image left” and “Hero, image right” are two entries in the library. Adding a third is a design decision, made by the people who own the design system.
A composition briefing lives in the repo. A CLAUDE.md the dev team maintains, saying which blocks make a feature-launch page and in what order, how long a hero subheadline may run, what tense the feature card titles use. That file is what the agent reads before it drafts a single word.

Skip that layer and you have a fast way to publish off-brand pages. Build it and the design system holds regardless of who or what composed the page. We build it as part of a headless website project and run it as part of agentic marketing automation.

Where this is heading

I’d say the back office dashboard is the first thing to thin out. Storyblok keeps doing the real work either way, the field validation, the versioning, the workflow stages, the roles and permissions. What loses its reason to exist is the screen an editor used to live in, because a draft can be written in a conversation and reviewed in the Visual Editor without either step routing through that screen.

That timeline depends on whether the block library and the composition briefing are finished, and that is a quarter of design and engineering rather than an afternoon of configuration. The teams publishing this way soonest are the ones who already have that library.

Storyblok does not go anywhere in this picture. The content still lives there, the validation still runs there, the approvals still happen there. What moves is the editing surface, and it stops being a single place you have to context-switch into. Some edits happen in the interface because that is the right tool for them. Some happen through an agent because the person is already there thinking about the work.

Where to start

Pick a development space for the trial, grant read and write on that space alone, point Claude Code at it, and hand the whole thing to one person for a week. What is annoying about the workflow shows up in days. Then decide whether the draft-first pattern earns a wider rollout.

If you are on a CMS without a structured content model, the tool calls that pay off here are much harder to model. WordPress can be wrapped in an MCP server, but the flat API surface and free-text content mean an agent is guessing at the shape of a page instead of reading it, and the guardrails described above have nothing to attach to. Moving to a structured stack is what our headless website service covers, and the fractional marketing engineer subscription keeps the wiring and the block library maintained once it ships.

Your team is already using AI tools on your content, connection or no connection. Websites have two audiences now, and one of them is the agents your own people point at your stack.