---
title: MCP Server
description: The Storyblok MCP server lets AI assistants and agents interact with a Storyblok space through the Management API using natural language. This concept covers when to use the server, how it works, client setup, available tools, and recommended usage patterns.
url: https://www.storyblok.com/docs/libraries/mcp-server
---

# MCP Server

The [Model Context Protocol](https://modelcontextprotocol.io) (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](/docs/api/management) and makes it available to any MCP-compatible AI client.

## Quickstart

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

```text
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](/docs/libraries/storyblok-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](/docs/concepts/cms-migration).

## 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](#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](/docs/concepts/access-tokens#management-api-access-tokens).

> [!WARNING]
> 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):
    
    ```bash
    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`
    
    ```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`
    
    ```toml
      [mcp_servers.storyblok]
      url = "https://mcp.labs.storyblok.com/mcp"
      bearer_token_env_var = "<TOKEN>"
    ```
    
-   Cursor
    
    Add to `.cursor/mcp.json`:
    
    ```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`
    
    ```bash
      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`):
    
    ```json
    {
      "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`
    
    ```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:
    
    ```json
    {
      "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](/docs/api/management/assets/upload-and-replace-assets). |

## 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](/pricing/technical-limits).

## Further resources

[Management API reference](/docs/api/management)

[CMS migration developer concept](/docs/concepts/cms-migration)

[Storyblok CLI](/docs/libraries/storyblok-cli)

[Technical Limits](https://www.storyblok.com/pricing/technical-limits)

## Pagination

-   [Previous: Storyblok CLI](/docs/libraries/storyblok-cli)
-   [Next: Universal API Client](/docs/libraries/js/universal-api-client)