Skill issue: storyblok-use-mcp
Storyblok is the first headless CMS that works for developers & marketers alike.
Is your agent struggling to navigate API endpoints? Does it take a wrong turn navigating through your content folders and content types, trying to find the story you’re looking for? Does it seem a little too eager to make changes without a human thumbs-up first?
Then allow us to introduce storyblok-use-mcp! It’s a skill that helps an agent understand and interface with the Storyblok MCP Server. Using its predefined operations and parameter schemas, an agent can create, mutate, and delete your space’s stories, components, assets, and other resources.
The Storyblok agent skills library is an open source set of skills that teach an AI coding agent how to work with Storyblok: when to use the CLI vs the MCP server, modeling schemas, reading and writing content through the Storyblok MCP server, turning a design into a page, and more.
Why use this skill?
To show the benefits of using this skill, we will task two separate agents with performing the same series of actions on a Storyblok space: one with the storyblok-use-mcp skill enabled, and one without. Each task will highlight a different capability of the skill and the tools contained within.
All prompts were tested on a default Storyblok Demo Space named “MCP Demo Space” using Claude Code running the Storyblok Skills package through Opus 5, while connected to the Storyblok MCP server.
Remember that systems involving agentic integrations are probabilistic, not deterministic. Expected output can be predictable but never fully guaranteed, which means that the output seen here may not exactly reflect the output another run produces under the same conditions.
Listing stories
The most basic action the MCP server and an agent using it can take is listing stories in a specific space. In this example, both agents were given the same simple instruction:
List all stories in the space named "MCP Demo Space"Without skills
Without the storyblok-use-mcp skill available, Claude searched for the operations necessary to perform the task, determining that because the listSpaces operation had no space_id, it required user input in order to find the desired space.
After requesting the space’s region from the user and being given the desired information, the agent found the space and determined it had 30 entries, 26 of which were stories and 4 of which were folders, as well as that all stories were currently published, along with the most recent update date.
It then proceeded to print a table of the first two content types it found, as well as less verbose lists of the remaining content types and a list of the folders it located:
MCP Demo Space (ID 123456789012345, EU region) has 30 entries: 26 stories and 4 folders. All 26 stories are published.
Folders: Articles, Categories, Banners, Testimonials
Pages
┌──────────────┬─────────────┐
│ Name │ Slug │
├──────────────┼─────────────┤
│ Home │ home │
├──────────────┼─────────────┤
│ About │ about │
├──────────────┼─────────────┤
│ Services │ services │
├──────────────┼─────────────┤
│ Pricing │ pricing │
├──────────────┼─────────────┤
│ Get in touch │ contact │
├──────────────┼─────────────┤
│ 404 │ error-404 │
├──────────────┼─────────────┤
│ Site Config │ site-config │
└──────────────┴─────────────┘
Articles (articles/)
┌─────────────────────────────────────────────────────────────────────┬───────────────────────────────────────┐
│ Name │ Slug │
├─────────────────────────────────────────────────────────────────────┼───────────────────────────────────────┤
│ Article Overview │ articles/ │
├─────────────────────────────────────────────────────────────────────┼───────────────────────────────────────┤
│ The Power of Fresh Starts: Why Every Brand Deserves a New Day │ fresh-starts-for-brands │
├─────────────────────────────────────────────────────────────────────┼───────────────────────────────────────┤
│ Your Brand, Your Story: Telling It in a Way That Sticks │ your-brand-your-story-that-sticks │
├─────────────────────────────────────────────────────────────────────┼───────────────────────────────────────┤
│ Beyond Clicks: How to Create Marketing That Actually Connects │ beyond-clicks-marketing-that-connects │
├─────────────────────────────────────────────────────────────────────┼───────────────────────────────────────┤
│ Beyond the Build: How to Develop for Speed, Scale & Future-Proofing │ develop-for-scale-speed │
├─────────────────────────────────────────────────────────────────────┼───────────────────────────────────────┤
│ Design That Converts: How to Create Digital Experiences That Stick │ digital-experiences-that-stick │
├─────────────────────────────────────────────────────────────────────┼───────────────────────────────────────┤
│ Seamless Tech Stacks: How Smart Integrations Unlock Growth │ unlock-growth-with-integrations │
├─────────────────────────────────────────────────────────────────────┼───────────────────────────────────────┤
│ Why Simplicity Wins in Branding │ simplicity-wins-branding │
├─────────────────────────────────────────────────────────────────────┼───────────────────────────────────────┤
│ Joyful Branding: How to Make Your Customers Feel Something │ joyful-branding-emotion │
└─────────────────────────────────────────────────────────────────────┴───────────────────────────────────────┘
Categories (categories/): Technology, Development, Branding, Marketing, Design
Testimonials (testimonials/): Sunny Meadows, Joy Cheerful, Harmony Fields, Hope Lively
Banners (banners/): Get in touchWith skills
With storyblok-use-mcp and assorted Storyblok skills now available, Claude first looked through these skills in order to determine its first steps, loading both storyblok-use-storyblok and storyblok-use-mcp.
Similar to the unskilled agent, the skilled agent asked what region the space in question existed in, and after being told which region proceeded to produce the same list of stories and folders as without the skill.
Finding the space by name means calling listSpaces, and that call needs a region. The Storyblok server says not to guess it, so I need you to tell me.
⏺ User answered Claude's questions:
· Which Storyblok region is "MCP Demo Space" in? (Or reply with the numeric space ID, and I can skip the lookup.) → eu
"MCP Demo Space" (ID 123456789012345, EU region) has 30 entries: 26 stories and 4 folders. Every story is published.
Pages (8)
┌──────────────────┬─────────────┐
│ Name │ Slug │
├──────────────────┼─────────────┤
│ Home │ home │
├──────────────────┼─────────────┤
│ About │ about │
├──────────────────┼─────────────┤
│ Services │ services │
├──────────────────┼─────────────┤
│ Pricing │ pricing │
├──────────────────┼─────────────┤
│ Get in touch │ contact │
├──────────────────┼─────────────┤
│ 404 │ error-404 │
├──────────────────┼─────────────┤
│ Site Config │ site-config │
├──────────────────┼─────────────┤
│ Article Overview │ articles/ │
└──────────────────┴─────────────┘
Articles (8), in articles/
- The Power of Fresh Starts: Why Every Brand Deserves a New Day
- Your Brand, Your Story: Telling It in a Way That Sticks
- Beyond Clicks: How to Create Marketing That Actually Connects
- Beyond the Build: How to Develop for Speed, Scale & Future-Proofing
- Design That Converts: How to Create Digital Experiences That Stick
- Seamless Tech Stacks: How Smart Integrations Unlock Growth
- Why Simplicity Wins in Branding
- Joyful Branding: How to Make Your Customers Feel Something
Categories (5), in categories/: Technology, Development, Branding, Marketing, Design
Testimonials (4), in testimonials/: Sunny Meadows, Joy Cheerful, Harmony Fields, Hope Lively
Banners (1), in banners/: Get in touch
Folders (4, unpublished): Articles, Categories, Banners, TestimonialsPerformance comparison
While the overall process and output were very similar, as well as the number of tokens used, the skilled agent completed the given task about 20% faster, averaging 23 seconds compared to the unskilled agent’s 29 seconds.
Additionally, the skilled agent described instructions given to it by its skill file, pointing out the operation it was attempting to utilize, and that it was required to ask for the space’s region in order to proceed.
We would likely expect this task to have similar results given its more basic nature, but even at this stage, the agent using the storyblok-use-mcp completed its task more quickly, and described the guidelines it was operating under.
Creating a story
Next, we tasked our agents with a mutating action: creating a story from scratch. For this, we gave our agents a bit more instruction to see how they would navigate the MCP server to create the requested story.
This task is testing our agents’ ability to use the MCP server to create a story, not our agents’ ability to construct a story using blocks from a suggested design or product brief. For this comparison, see the article on the storyblok-model-content skill.
Without skills
We will want to reuse the output from this task in later stages, so to our unskilled agent we gave the following instructions:
Create a new folder in "MCP Demo Space" with name "Agentic Content" and the slug "agentic-content". In this folder, create an article with the title "Story created by an unskilled agent" and the slug "unskilled-story". The article's body should just read "This article was created by Claude without using the `storyblok-use-mcp` skill."The unskilled agent began by analyzing existing articles in the space to try and match their content structure, before creating the folder and story as requested. Upon completion, it left the following notes about the actions taken and decisions made:
Let me look at an existing article to match its content structure.
Articles use the article-page component, with a headline field and a rich-text text field. Next I'll create the folder.
I created the folder and the article in MCP Demo Space. The article is saved as a draft, since you didn't ask me to publish it.
┌─────────┬─────────────────────────────────────┬─────────────────────────────────┬─────────────────┐
│ │ Name │ Full slug │ ID │
├─────────┼─────────────────────────────────────┼─────────────────────────────────┼─────────────────┤
│ Folder │ Agentic Content │ agentic-content │ 227964654854673 │
├─────────┼─────────────────────────────────────┼─────────────────────────────────┼─────────────────┤
│ Article │ Story created by an unskilled agent │ agentic-content/unskilled-story │ 227964671652370 │
└─────────┴─────────────────────────────────────┴─────────────────────────────────┴─────────────────┘
- Content type: I checked an existing article first to see its structure. The new one uses the same article-page content type, with the title in headline and the body in the rich-text text field.
- Body: "This article was created by Claude without using the storyblok-use-mcp skill." The skill name is formatted as inline code, as in your request.
- Fields left empty: image, categories, meta title/description and call to action. Your other articles have these filled in, so the page may look sparse until you add them.
- Folder's default content type: Storyblok set it to default-page. Stories you add to this folder later will start as that type, not as articles, unless you change it.With skills
For the skilled agent, we adjusted the prompt for easier identification and gave it the following task:
Create a new folder in "MCP Demo Space" with name "Agentic Content" and the slug "agentic-content". In this folder, create an article with the title "Story created by a skilled agent" and the slug "skilled-story". The article's body should just read "This article was created by Claude using the storyblok-use-mcp skill."The skilled agent read a pair of files, called Storyblok a few times, and ran a shell command, before indicating what it intended to do prior to taking action:
I'll create two things in MCP Demo Space (987654321098765):
1. Folder Agentic Content, slug agentic-content (root level)
2. Story Story created by a skilled agent, slug skilled-story inside it, content type article-page — headline set to the title, text richtext holding the one sentence, all other fields (image, categories, CTA, meta) left empty. Created as a draft, since you didn't ask for it published.Once it relayed this information, the skilled agent called Storyblok two more times and completed its task, with the following report when complete:
Both created.
Folder — Agentic Content · agentic-content · id 123456789012371 · root level
Story — Story created by a skilled agent · agentic-content/skilled-story · id 123456789012373 · draft (not published)
article-page
headline: Story created by a skilled agent
text (richtext): This article was created by Claude using the
storyblok-use-mcp skill.
image: —
categories: —
call_to_action: —
meta_title / meta_description: —
Two notes on judgment calls I made:
- You gave a title but the content type has both a story name and a headline field, so I put the title in both.
- You didn't say to publish, so it's a draft. Say the word and I'll publish it.Performance comparison
Once again, the ultimate results of both agents attempting this task were quite similar—in both cases, the folder “Agentic Content” was successfully created to the specifications given, as well as the article-type story with the desired text. Additionally, in both cases, the agent saved the story as a draft rather than publishing it, even though both agents had the ability to publish stories in this example.
Using a single access token which grants agents the ability to both write and publish is not recommended, but is being used in this instance to test what the agents will do with minimal instruction with or without the storyblok-use-mcp skill.
For more information on why you should be more strict with agent guardrails, read Mistakes, Malfunctions, and Malice: Protecting yourself from rogue agents.
While both succeeded in the task given, taking roughly the same amount of time and tokens, there were a few notable differences in approach:
- The skilled agent told the user what it intended to do before doing it.
- While it did not pause the procedure, if a user noticed something wrong about the agent’s interpretation of the request, they would have time to cancel the operation.
- The skilled agent gave a breakdown of the new story’s metadata, including fields left blank.
The skilled agent worked faster than the unskilled agent thanks to guidance granted to it by the storyblok-use-mcp skill, and provided quality-of-life improvements over the unskilled results, with better readability, more quickly identifying information, and even a heads up as to what was going to be done before it proceeded.
Updating a story
For the next task, we aimed to have each agent update the story it previously created. Before doing so, both articles were moved into the same “Agentic Content” folder and published, in order to observe how each agent responded to handling a story whose content was currently live.
Without skills
Because we were updating two stories with different content, we also used slightly different prompts to append additional text to the existing articles. For the unskilled agent, we gave the following instructions:
Update the story “Story by an unskilled agent” in the Agentic Content folder by adding the following text at the end of the article in a new paragraph: “This is a test to examine the performance of an agentic MCP integration that does not use the storyblok-use-mcp skill. It will be compared to the performance of an integration that does use the skill.”The feedback we receive from the unskilled agent is brief—it updates the story, displays the two paragraphs now present within it, and acknowledges that updateStory replaces all properties of a story and requires the entire set of fields in order to not lose data.
It notably saved the update as a draft, after determining this as the correct course of action since publishing the article would push it live immediately (while offering to do so if asked).
Updated agentic-content/unskilled-story (id 123456789012372). The rich-text body now has two paragraphs:
1. "This article was created by Claude without using the storyblok-use-mcp skill."
2. "This is a test to examine the performance of an agentic MCP integration that does not use the storyblok-use-mcp skill. It will be compared to the performance of an integration that does use the skill."
All other fields (headline, categories, call_to_action, meta fields) were carried over unchanged — updateStory replaces content wholesale, so I re-sent the full object.
Saved as a draft: the story is still published at the old version and now shows unpublished_changes: true. I didn't publish since that pushes to live content. Say the word and I'll publish it.With skills
For the skilled agent, we used instructions similar to those given to the unskilled agent, but with the references to skilled or unskilled use swapped:
Update the story “Story by a skilled agent” in the Agentic Content folder by adding the following text at the end of the article in a new paragraph: “This is a test to examine the performance of an agentic MCP integration that uses the storyblok-use-mcp skill. It will be compared to the performance of an integration that does not use the skill.”The skilled agent read a file and called Storyblok twice before declaring its intent to update the story it was instructed to change, as was detailed by the storyblok-use-mcp skill file. Because the article was already live, and the prompt did not include any instruction to specifically not republish with the described changes, it also stated it would republish the story when finished:
About to change one story — agentic-content/skilled-story (id 123456789012373) in MCP Demo Space: appending one new paragraph to its text richtext field, keeping the existing paragraph, headline and all other fields as they are, and republishing (it's currently live). Nothing else is touched.After this, it called Storyblok once, updated and republished the story, and displayed the metadata as it had before, followed by a mention of correcting the use of a double space in the original prompt. Clever!
Updated and republished.
Story created by a skilled agent — agentic-content/skilled-story (id 123456789012373) · published, no unpublished changes
- article-page
- headline: Story created by a skilled agent
- text (richtext):
- This article was created by Claude using the storyblok-use-mcp skill.
- This is a test to examine the performance of an agentic MCP integration that uses the storyblok-use-mcp skill. It will be compared to the performance of an integration that does not use the skill.
- categories: *(empty)* · call_to_action: *(empty)* · meta_title / meta_description: *(empty)*
The original paragraph, the block's _uid and every other field carried through unchanged. One note: your text had a double space after "skill." — I set it as a single space.Performance comparison
Once again, both agents were able to successfully perform the task asked of them, though as usual, there are some important differences in the approach:
- The skilled agent once again informed us of the mutating action it was about to take before taking it.
- In this case, a user who did not wish to republish the content immediately would likely halt the action and rewrite their prompt with more explicit instructions.
- The skilled agent once again displayed the relevant metadata for easy inspection.
- The skilled agent performed its task roughly 30% faster than the unskilled agent, using half the tokens as well.
- The skilled agent republished the story once changes have been made.
This last difference is important, and highlights the importance of clear instructions for agentic behavior. While it may not always behave this way, the instruction given was to update a live article, using a token which allows the agent to publish.
Mutating changes do not mandate user confirmation by default, as the user may prefer for their agent to have this ability, but if this is an action you do not want your agent to take, the publish permission should not be enabled for the agent’s token’s stories scope, or instructions should be clear about whether or not to publish changes made to live pages.
Deleting a story
Finally, we compared how the unskilled and skilled agents handled deleting stories with minimal instruction. The Storyblok MCP Server requires confirmation before performing destructive actions, so we should expect some level of prompting the user to confirm before anything is removed.
Without skills
For the unskilled agent, we gave the simple prompt:
Delete the story named “Story created by an unskilled agent” in the Agentic Content folder.After a few seconds and a few calls to Storyblok, the unskilled agent recognized the story in question is currently live, and prompted the user to either confirm the intent to delete the story, simply unpublish it, cancel the request altogether, or type something in order to give further instructions:
One exact match, and it's currently published (live). Confirming before I remove it:
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
☐ Confirm
│ Delete "Story created by an unskilled agent" (id 123456789012372, slug agentic-content/unskilled-story)? It's currently published/live. Storyblok moves deleted stories to the trash, so it can be restored.
❯ 1. Yes, delete it
Delete story 123456789012372 from the Agentic Content folder. It goes to the space's trash.
2. Unpublish instead
Take it off the live site but keep the story in the folder as a draft.
3. Cancel
Leave the story as-is.
4. Type something.Upon confirming the intent to delete the content, the agent called Storyblok once and the content was deleted. The complete operation took 36 seconds, and the agent identified that the folder now only contained the skilled counterpart story:
Deleted. Story created by an unskilled agent (agentic-content/unskilled-story, id 123456789012372) was removed and is now in the space's trash — restorable from there if needed.
The Agentic Content folder is still there and is now empty. Tell me if you want it removed too.With skills
For the skilled agent, we gave it a similar instruction to the one given to the unskilled agent:
Delete the story named “Story created by a skilled agent” in the Agentic Content folder.The skilled agent immediately recognized the intent to perform a destructive action and signaled this to the user, as well as indicating its investigation into what was being requested for deletion:
Destructive operation — let me look at exactly what would be lost first.After a few more seconds, the skilled agent too paused the operation to not only request confirmation of the action (with the same four options presented to the user), but also walk through the details of the delete request.
Here's what the delete would remove:
Story created by a skilled agent — agentic-content/skilled-story (id 123456789012373)
- Type: article-page, currently published (live on the site)
- Created 2026-09-25 14:00, last updated 14:02
- Headline: "Story created by a skilled agent"
- Body: two paragraphs describing it as a test of the storyblok-use-mcp skill, to be compared against an integration without the skill
- Empty: categories, call to action, meta title, meta description
One thing worth flagging before I proceed: it's published, so deleting takes a live URL down. Deleting is not reversible from here.
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
☐ Delete
│ Confirm deleting the published story "Story created by a skilled agent" (agentic-content/skilled-story)?
❯ 1. Yes, delete it
Permanently delete the story and take its live URL down. Cannot be undone from here.
2. Unpublish instead
Take it off the live site but keep the story and its content in the space.
3. Cancel
Leave the story exactly as it is.
4. Type something.Once the delete request was confirmed, the agent completed the operation and informed the user that the story could be recovered from the trash if desired.
I deleted Story created by a skilled agent (agentic-content/skilled-story, ID 123456789012373), so the live page is gone. Storyblok moved it to the trash rather than erasing it, so you can restore it from there for a while. The Agentic Content folder is still there and is now empty.Performance comparison
As with the other operations, both agents were ultimately able to successfully complete their tasks, up to and including giving the same four options for how to resolve the request for deleting a published story.
However, there were once more some notable differences in their approach and their execution:
- The skilled agent immediately recognized the destructive operation request and acted accordingly
- The skilled agent gave an abridged view of the content in order for the user to make an informed decision.
- The skilled agent was able to identify the significance of the story the user tasked it with deleting as well as possible reasons to reconsider based on extra context it discovered.
- The skilled agent performed the task 10% faster than the unskilled agent.
Final comparison
It may seem like there isn’t much separating unskilled and skilled use of the Storyblok MCP server, but even with the minor differences above there is a clear improvement when using the storyblok-use-mcp skill. The skilled agent was more proactive about warning the user about mutating and destructive changes, added context where the unskilled agent didn’t, and even performed requested actions anywhere from 10–25% faster.
Considering the tasks given to these agents were very small, one can easily imagine how much these contrasts add up over the course of a much larger prompt or an entire project. Additionally, storyblok-use-mcp serves as the backbone for a number of other skills for which you’ll want those recommended best practices, and that direct line to how the MCP server operates best.
Get the skills
To make use of the skill library in your projects, simply install the Storyblok Agent Plugin; it sets up everything your agent needs to perform at the level of an experienced Storyblok Developer.
We want your feedback
We would love to hear back from you on how you use these skills and how they are working for you! Let us know in our Discord.
