Co budujemy

Na końcu tego poradnika Claude Code utworzy stronę, wypełni ją treścią, opublikuje i ponownie zedytuje, a aplikacja Next.js działająca na Twoim komputerze wyrenderuje każdą zmianę. Nikt nie otwiera panelu administracyjnego.

Zaangażowane są trzy elementy i warto trzymać je osobno:

Twoja aplikacja Next.js renderuje stronę. Tutaj jest to simple-blog z repozytorium przykładów cmssy. cmssy nigdy jej nie renderuje ani nie hostuje.
Twój workspace cmssy przechowuje treść i udostępnia ją aplikacji przez delivery API.
@cmssy/mcp-server łączy Claude Code z tym workspace. Claude czyta i zapisuje treść przez niego. Nie dotyka Twojego kodu: serwer nie zapisuje plików i nie trzyma lokalnego stanu.

Wymagania

Node 22.13 lub nowszy oraz pnpm (npm też zadziała)
Zainstalowany Claude Code
Workspace cmssy. Plan darmowy wystarczy do tego poradnika.

Krok 1: Uruchom przykładową aplikację

Sklonuj repozytorium z przykładami i uruchom simple-blog:

git clone https://github.com/cmssy-io/examples
cd examples/simple-blog
pnpm install
cp .env.example .env.local
pnpm dev

Otwórz http://localhost:3000. Strona główna przekierowuje na /blog, który renderuje treść z publicznego workspace demo. W tym kroku nie potrzebujesz konta. Teraz skieruj aplikację na własny workspace.

Krok 2: Utwórz token API

W panelu cmssy otwórz API Tokens i kliknij Create Token. Nadaj mu nazwę, a w polu Workspace wybierz workspace używany przez ten projekt. Token ograniczony do jednego workspace może otwierać tylko ten workspace, czego w zupełności wystarczy agentowi w jednym repozytorium.

Skopiuj wartość cs_... od razu, gdy się pojawi. Jest pokazywana tylko raz.

Token nie ma własnych uprawnień. Działa jako Ty, z rolą, którą masz w tym workspace, więc token redaktora może edytować, a token członka tylko do odczytu może jedynie czytać.

Krok 3: Połącz aplikację z workspace

npx @cmssy/cli link --token cs_your_token

link pobiera slug organizacji, slug workspace i draft secret, a następnie zapisuje je w .env.local. Jeśli workspace nie ma jeszcze manifestu bloków, wysyła też manifest aplikacji. Ten manifest to lista typów bloków, które aplikacja potrafi wyrenderować, tutaj prose i blog-index. Po wszystkim uruchom ponownie pnpm dev.

Manifest sprawia, że Claude nie umieści na stronie bloku, którego Twoja witryna nie wyrenderuje: serwer odrzuca typy bloków, których manifest nie wymienia.

Krok 4: Znajdź ID workspace

Serwer MCP oprócz tokenu przyjmuje ID workspace. Otwórz Settings swojego workspace. ID znajdziesz w sekcji Workspace Information.

Krok 5: Zarejestruj serwer MCP

Dodaj .mcp.json w katalogu głównym projektu. Nie zawiera sekretów, więc możesz go zacommitować:

{
  "mcpServers": {
    "cmssy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cmssy/mcp-server@latest"]
    }
  }
}

Token trzymaj w powłoce. Serwer czyta CMSSY_API_TOKEN i CMSSY_WORKSPACE_ID ze swojego środowiska, a Claude Code uruchamia go z Twoim:

export CMSSY_API_TOKEN=cs_your_token
export CMSSY_WORKSPACE_ID=your_workspace_id
claude

Przy pierwszym uruchomieniu claude w projekcie Claude Code zapyta, czy zaufać serwerowi MCP z .mcp.json. Zatwierdź, a potem uruchom /mcp. Powinieneś zobaczyć cmssy jako połączony.

Serwer przyjmuje też flagi --token i --workspace-id. Użyj ich do szybkiego lokalnego testu, ale nie trzymaj tokenu w zacommitowanych plikach.

Krok 6: Zapytaj, co witryna potrafi wyrenderować

Zacznij od czegoś tylko do odczytu:

Które typy bloków może wyrenderować moja witryna i jakie strony istnieją?

Claude wywołuje list_block_types i list_pages. Typy bloków, które wypisuje, pochodzą z manifestu Twojej aplikacji, razem z ich polami, więc Claude wie, że prose ma pole rich text body, zanim cokolwiek napisze.

Krok 7: Zbuduj i opublikuj stronę

Utwórz stronę /blog z blog index, który wyświetla jej strony podrzędne.
Pod nią dodaj wpis o tytule "Hello from Claude Code" z dwoma krótkimi
akapitami w bloku prose. Wypełnij każdy język włączony w workspace,
a potem opublikuj obie strony.

Claude przechodzi przez get_site_config (by poznać Twoje języki), create_page, add_block_to_page i publish_page. Claude Code pyta przed uruchomieniem każdego narzędzia, na które jeszcze nie pozwoliłeś, więc widzisz każdy zapis, zanim nastąpi.

Odśwież http://localhost:3000/blog. Indeks wyświetla nowy wpis, a wpis renderuje się przez własny komponent prose aplikacji.

Krok 8: Edytuj i opublikuj ponownie

Przepisz pierwszy akapit wpisu "Hello from Claude Code", tak by wspominał
o MCP, i zmień jego tytuł SEO. Potem go opublikuj.

Zmiany trafiają najpierw do wersji roboczej strony. Twoja witryna serwuje tylko wersję opublikowaną, więc nic się w aplikacji nie zmienia, dopóki nie zadziała publish_page. Potem odśwież, a nowy tekst będzie na miejscu: w trybie deweloperskim Next renderuje każde żądanie od nowa.

Przy jednym akapicie w długim artykule Claude może użyć patch_block_content, który wysyła tylko zmienioną część zamiast całego HTML.

Zdecyduj, co Claude może robić bez pytania

Claude Code pyta przed każdym wywołaniem MCP, na które nie pozwoliłeś. Odczyty można bezpiecznie dopuścić. Zapisy, a zwłaszcza publish_page i delete_page, zostaw z pytaniem. W .claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__cmssy__list_block_types",
      "mcp__cmssy__list_pages",
      "mcp__cmssy__get_page",
      "mcp__cmssy__get_site_config"
    ]
  }
}

Serwer oznacza swoje narzędzia dla klienta: narzędzia odczytu jako tylko do odczytu, a te, które usuwają, publikują lub rejestrują zwrot, jako destrukcyjne.

Przejście na produkcję

Na produkcji simple-blog cache'uje każdą stronę do godziny (revalidate = 3600), więc publikacja pojawiłaby się z opóźnieniem. Włącz natychmiastowe aktualizacje za pomocą trasy revalidate i webhooka:

import { createCmssyRevalidateRoute } from "@cmssy/next/server";

export const POST = createCmssyRevalidateRoute({
  secret: process.env.CMSSY_WEBHOOK_SECRET,
});

Umieść to w app/api/revalidate/route.ts, a potem zasubskrybuj webhook na content.changed wskazujący na tę trasę. Claude może utworzyć webhook przez create_webhook. Sekret podpisu wraca tylko raz, więc wpisz go od razu do CMSSY_WEBHOOK_SECRET u swojego hostingodawcy. Trasa weryfikuje podpis i unieważnia tagi cache cmssy.

Bez tokenu? Zaloguj się

Claude Code może też użyć hostowanego serwera MCP cmssy, który loguje Cię przez przeglądarkę zamiast tokenu:

claude mcp add --transport http cmssy https://api.cmssy.io/mcp

Uruchom /mcp i uwierzytelnij się. Wybierasz, których workspace'ów może używać Claude i czy dostaje tylko odczyt, czy odczyt i zapis. Narzędzia są te same, ale każde przyjmuje workspace jako org/workspace, więc jedno połączenie może obsługiwać kilka workspace'ów. Konfiguracji z tokenem używaj w CI i wszędzie tam, gdzie nie ma przeglądarki.

Rozwiązywanie problemów

Każde wywołanie zwraca „Not authorized": token jest unieważniony lub wygasł albo nie może otworzyć workspace z CMSSY_WORKSPACE_ID. Serwer startuje nawet ze złym tokenem, więc „connected" w /mcp nie dowodzi, że token jest poprawny.
Serwer się nie pojawia: zmienne nie zostały wyeksportowane w powłoce, która uruchomiła claude. Bez tokenu serwer kończy działanie przy starcie.
Brakuje oczekiwanego narzędzia: npx mógł zcache'ować starą wersję. Porównaj npx -y @cmssy/mcp-server --version z npm view @cmssy/mcp-server version.
Blok jest odrzucany: jego typu nie ma w manifeście workspace. Poproś Claude o uruchomienie list_block_types i użycie typu, który tam jest.

Pełna dokumentacja, z każdym narzędziem i wymaganym uprawnieniem, jest w dokumentacji serwera MCP. Tokeny opisano w tokenach API.

Połącz Claude Code ze swoim headless CMS przez MCP