MCP Server

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/libraries/mcp-server.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 model 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.labs.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.

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

1. Search: to find matching operation IDs and behavior hints, call search with a keyword.
2. Describe: to get all parameters and the request body schema, call describe with the operation ID and returns which execute_ tool to use.
3. Execute: call the tool with the operation ID, resolved parameters, and optional fields filter.

The principle is to describe outcomes, not endpoints. For example, you don’t need to instruct the AI client to create a story using POST /v2/spaces/{space_id}/stories; the LLM automatically identifies the correct operation and executes it.

Set up an AI client

All clients use the same server URL (https://mcp.labs.storyblok.com/mcp) and the same access token. Copy the snippet that matches your client, and replace <TOKEN> with your Storyblok personal access token.

Caution

Personal access tokens are sensitive credentials. Never commit them to version control, and store them in environment variables whenever possible. If a token is exposed, revoke it immediately and generate a new one.

Claude Code

Add to Claude Code’s local configuration (add --scope user or --scope project, depending on your needs):

claude mcp add --transport http Storyblok https://mcp.labs.storyblok.com/mcp --header "Authorization: Bearer <TOKEN>"

Claude Desktop

Add to Claude Desktop’s global configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude-desktop/claude_desktop_config.json

{
  "mcpServers": {
    "storyblok": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.labs.storyblok.com/mcp",
        "--header",
        "Authorization: Bearer <your_token>"
      ]
    }
  }
}

Codex

Add to Codex’s global configuration file (set the token in an environment variable):

• macOS/Linux: ~/.codex/config.toml
• Windows: %USERPROFILE%\.codex\config.toml

  [mcp_servers.storyblok]
  url = "https://mcp.labs.storyblok.com/mcp"
  bearer_token_env_var = "<TOKEN>"

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "Storyblok": {
      "type": "http",
      "url": "https://mcp.labs.storyblok.com/mcp",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}

Gemini CLI

Add to Gemini CLI’s global configuration file:

• macOS/Linux: ~/.gemini/settings.json
• Windows: %USERPROFILE%/.gemini/settings.json

  gemini mcp add --transport http Storyblok https://mcp.labs.storyblok.com/mcp --header "Authorization: Bearer <TOKEN>"

VS Code

Add to .vscode/mcp.json (note the servers key, not mcpServers):

{
  "servers": {
    "Storyblok": {
      "type": "http",
      "url": "https://mcp.labs.storyblok.com/mcp",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}

Devin Desktop (Windsurf)

Add to Devin Desktop’s global configuration file:

• macOS/Linux: ~/.config/devin/config.json
• Windows: %APPDATA%\devin\config.json

{
  "mcpServers": {
    "Storyblok": {
      "url": "https://mcp.labs.storyblok.com/mcp",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}

Other

Use a generic configuration to add the MCP server to any client that supports HTTP transport:

{
  "mcpServers": {
    "Storyblok": {
      "type": "http",
      "url": "https://mcp.labs.storyblok.com/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN>"
      }
    }
  }
}

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.

Recommended usage patterns

• Prefer narrow, scoped roles. The role defined for the personal access token is a reliable safeguard.
• 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 on a development space. Verify any new automation on a non-production space.

Limitations

• Calls are subject to the Management API’s rate limits.

Further resources

Management API reference

CMS migration developer concept

Storyblok CLI

Technical Limits