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/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 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.

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, 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.

Set up an AI client

All clients connect to https://mcp.storyblok.com/mcp. We recommend authenticating with OAuth.

Connect with OAuth

Copy the snippet that matches your client. On first use, the client opens a browser window where you sign in to Storyblok and choose which permissions and spaces to grant.

Caution

Grant only the permissions and spaces the AI client actually needs. This is your main safeguard for limiting what it can read or change. Review the selection carefully before you allow access.

Claude Code

Add the server (add --scope user or --scope project, depending on your needs), then run /mcp and select Storyblok to authenticate:

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

Claude.ai & Claude Desktop

Connect the server as a custom connector. Follow Set up the connector in Claude for detailed steps, including for organization accounts.

Cursor

Add to .cursor/mcp.json, then approve the sign-in prompt in Cursor. Cursor detects a remote server from the url, and doesn’t require a type field:

{
  "mcpServers": {
    "Storyblok": {
      "url": "https://mcp.storyblok.com/mcp"
    }
  }
}

VS Code

Add to .vscode/mcp.json (note the servers key, not mcpServers), then approve the sign-in prompt:

{
  "servers": {
    "Storyblok": {
      "type": "http",
      "url": "https://mcp.storyblok.com/mcp"
    }
  }
}

Codex

Add the server to ~/.codex/config.toml:

[mcp_servers.storyblok]
url = "https://mcp.storyblok.com/mcp"

Then log in to trigger the browser sign-in (oauth is the default auth mode):

codex mcp login storyblok

Gemini CLI

Add to Gemini CLI’s configuration file (~/.gemini/settings.json). With dynamic_discovery, the CLI opens the browser sign-in on first use:

{
  "mcpServers": {
    "Storyblok": {
      "httpUrl": "https://mcp.storyblok.com/mcp",
      "authProviderType": "dynamic_discovery"
    }
  }
}

Other

For any client that supports the HTTP transport, point it at the server URL. The client discovers the OAuth flow automatically:

{
  "mcpServers": {
    "Storyblok": {
      "type": "http",
      "url": "https://mcp.storyblok.com/mcp"
    }
  }
}

Set up the connector in Claude

Add Storyblok as a custom connector in Claude’s settings. The flow is identical in Claude.ai and Claude Desktop.

Personal account

1. In Claude, open Settings → Connectors.
2. Select Add → Add custom connector.
3. Enter a name (shown in the connectors list, for example Storyblok MCP) and the URL https://mcp.storyblok.com/mcp. Leave the optional OAuth client ID and secret under Advanced settings blank, then select Add.
4. Sign in to Storyblok and grant access.
5. Back in Claude, review Tool permissions. The read-only and write/delete tools default to Needs approval; adjust them per tool if needed.

Organization

On Team and Enterprise plans, only an owner or primary owner can add a custom connector.

1. In Claude, open Organization settings → Connectors.
2. Select Add
3. Hover over Custom and select Web.
4. Enter the URL https://mcp.storyblok.com/mcp. Leave the optional OAuth client ID and secret blank, then select Add.

Owners can set org-wide tool permissions:

• Under Customize → Connectors, select Always allow, Needs approval, or Blocked.
• Then, each member opens Customize → Connectors, finds Storyblok, and selects Connect.
• Finally, members complete the OAuth authorization individually.

Connect with a personal access token

OAuth is the recommended default. Use a personal access token when you need a static credential, such as scripted or non-interactive use, or a client without OAuth support. Prefer a scoped token limited to the spaces and permissions the AI client needs.

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. Learn more about personal access tokens.

Any client that supports the HTTP transport can send the token as a bearer header. Replace <TOKEN> with your personal access token:

{
  "mcpServers": {
    "Storyblok": {
      "type": "http",
      "url": "https://mcp.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

• 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.
• 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.
• Test on a development space. Verify any new automation on a non-production space.

Notes

• The server exposes the Management API only. It can’t read published content through the Content Delivery API.
• The MCP scopes most operations to a space and requires a space ID.
• Calls are subject to the Management API’s rate limits.

Further resources

Management API reference

CMS migration developer concept

Storyblok CLI

Technical Limits