MCP Server

The Storyblok MCP server lets an AI agent or assistant work directly in a Storyblok space using natural language.

The Model Context Protocol (MCP) is an open standard that connects AI assistants and agents to external systems using a set of pre-defined tools. Storyblok’s MCP server exposes the Management API and makes it available to any MCP-compatible AI client.

Quickstart

Copy the following prompt and paste it into an MCP-compatible AI client:

Fetch https://www.storyblok.com/docs/tooling/mcp-server/setup.md and follow the setup instructions for this client.

When to use the MCP server

The MCP server enables conversational, exploratory work driven by an LLM. Because the LLM mediates every call, results are non-deterministic and unsuited for repeatable, high-volume work.

Use the MCP for one-off changes, prototyping, and tasks where you describe an outcome in natural language and let the LLM pick the correct operations.
Otherwise, use Storyblok’s CLI for deterministic, efficient, and reproducible operations, including CI/CD pipelines and large-scale changes.

The CLI offers dry runs, idempotency guarantees, reference-mapping via manifest files, and scriptable commands, which makes it ideal for batch operations, such as bulk content updates, space-to-space syncs, and schema or CMS migrations.

How the MCP server works

The server is a hosted, stateless HTTP endpoint available at https://mcp.storyblok.com/mcp.

Instead of exposing a separate tool for each API endpoint—and overwhelming the LLM—the server offers generic tools that cover the entire API. This architecture allows an AI client to manage all content in a Storyblok space. The server exposes the Management API only, so it can’t read published content through the Content Delivery API.

To ensure safe and accurate API calls, the server enforces a three-step workflow:

Search: to find matching operation IDs and behavior hints, call search with a keyword.
Describe: to get all parameters and the request body schema, call describe with the operation ID and returns which execute_ tool to use.
Execute: call the tool with the operation ID, resolved parameters, and optional fields filter. Most operations are scoped to a space, so they require a space ID.

The principle is to describe outcomes, not endpoints. For example, instead of instructing the AI client to create a story using POST /v2/spaces/{space_id}/stories, the LLM automatically identifies the correct operation and executes it.

Ask only for the fields you need. For large lists, be specific in your prompt. For example, write “give me the names and slugs” of every story. The AI client then passes a tighter fields filter, and the server trims the response before returning it, which keeps the context small and the calls fast. Calls are subject to the Management API’s rate limits, so narrower responses also go further.

Tools

Tool	Purpose
`search`	Discovers available Storyblok Management API operations by keyword. Returns matching operation IDs, behavior hints, summaries, and available response fields.
`describe`	Gets full parameter details for an operation: path and query parameters with descriptions and schemas, and the request body schema for write operations.
`execute_readonly`	Executes safe read operations (`GET`). Use for listing and fetching resources.
`execute_mutating`	Executes mutating operations (`POST`, `PUT`, `PATCH`). Use for creating and updating resources.
`execute_destructive`	Executes destructive operations (`DELETE`). Requires explicit confirmation from the user before use.
`upload_asset`	Creates an asset record and gets a signed S3 upload URL with a ready-to-use cURL command. To finalize the upload, call `upload_asset_finish`.
`upload_asset_finish`	Finalizes and validates the asset upload to S3 (via cURL or manually). Learn more in the Upload and Replace Assets guide.

Working safely

An LLM mediates every call the MCP server makes, so it decides which operation runs and against which space. You set the guardrails around that decision.

Grant least privilege. Limit the connection to only the spaces and permissions the AI client needs.
Read the plan back before executing. Ask the AI client to summarize the operation, parameters, and target before any mutating call. Catching a wrong space ID, slug, or block name now is cheaper than reverting it later.
Verify identifiers on destructive operations. Before approving an execute_destructive prompt, verify the story ID, asset ID, or block name. Don’t hide the prompt or run the server inside autonomous automation.
Test in an environment. Verify any new automation in an environment — a sandbox space that mirrors production — rather than against the live space.