---
title: Set up the MCP server
description: Connect an AI client to the Storyblok MCP server, and how the server's tools and search-describe-execute workflow work.
url: https://www.storyblok.com/docs/tooling/mcp-server/setup
---

# Set up the MCP server

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.

> [!WARNING]
> 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:
    
    ```bash
    claude mcp add --transport http Storyblok https://mcp.storyblok.com/mcp
    ```
    
-   Claude.ai & Claude Desktop
    
    Install Storyblok from the connector directory, or add it as a custom connector. Follow [Set up the connector in Claude](#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:
    
    ```json
    {
      "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:
    
    ```json
    {
      "servers": {
        "Storyblok": {
          "type": "http",
          "url": "https://mcp.storyblok.com/mcp"
        }
      }
    }
    ```
    
-   Codex
    
    Add the server to `~/.codex/config.toml`:
    
    ```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):
    
    ```bash
    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:
    
    ```json
    {
      "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:
    
    ```json
    {
      "mcpServers": {
        "Storyblok": {
          "type": "http",
          "url": "https://mcp.storyblok.com/mcp"
        }
      }
    }
    ```

## Set up the connector in Claude

In Claude.ai and Claude Desktop, install Storyblok from the connector directory. The flow is identical in both.

-   Personal account
    
    1.  In Claude, open **Settings** → **Customize** → **Connectors**.
    2.  Select **+** → **Browse connectors**.
    3.  Find **Storyblok** and select **Connect**. You can also open the [Storyblok listing](https://claude.ai/directory/storyblok) directly and select **Connect**.
    4.  Sign in to Storyblok. On the authorization screen, choose which permissions to grant. Define read and write permissions per scope, select the spaces the connector can access, then select **Allow 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
    
    If your Claude account is part of an organization, whether you can connect directly depends on the organization’s connector permissions.
    
    1.  If you have permission, connect as above. Without permission, select **Request** on the Storyblok listing to notify your admins.
    2.  An owner or primary owner enables Storyblok under **Organization settings** → **Connectors** and sets org-wide tool permissions (**Always allow**, **Needs approval**, or **Blocked**).
    3.  Each member then opens **Settings** → **Customize** → **Connectors**, finds Storyblok, selects **Connect**, and completes the OAuth authorization individually.
    

> [!NOTE]
> If Storyblok isn’t in your directory yet, add it manually as a custom connector: in **Settings** → **Customize** → **Connectors**, select **Add** → **Add custom connector**, enter the URL `https://mcp.storyblok.com/mcp`, and leave the OAuth fields blank.

## 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](/docs/concepts/access-tokens#management-api-access-tokens) limited to the spaces and permissions the AI client needs.

> [!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. Learn more about [personal access tokens](/docs/concepts/access-tokens#management-api-access-tokens).

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

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

## Pagination

-   [Previous: Introduction](/docs/tooling/mcp-server)