Was wir bauen

Am Ende dieser Anleitung erstellt Claude Code eine Seite, füllt sie mit Inhalt, veröffentlicht sie und bearbeitet sie erneut, und eine Next.js-App auf deinem Rechner rendert jede Änderung. Niemand öffnet ein Admin-Panel.

Drei Bausteine sind beteiligt, und es hilft, sie auseinanderzuhalten:

Deine Next.js-App rendert die Website. Hier ist es simple-blog aus dem cmssy-Beispiel-Repository. cmssy rendert oder hostet sie nie.
Dein cmssy-Workspace speichert die Inhalte und liefert sie über die Delivery-API an die App.
@cmssy/mcp-server verbindet Claude Code mit diesem Workspace. Claude liest und schreibt Inhalte darüber. Er fasst deinen Code nicht an: Der Server schreibt keine Dateien und hält keinen lokalen Zustand.

Voraussetzungen

Node 22.13 oder neuer und pnpm (npm funktioniert auch)
Installiertes Claude Code
Ein cmssy-Workspace. Der kostenlose Plan reicht für diese Anleitung.

Schritt 1: Die Beispiel-App starten

Klone das Beispiel-Repository und starte simple-blog:

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

Öffne http://localhost:3000. Die Startseite leitet auf /blog weiter, das Inhalte aus einem öffentlichen Demo-Workspace rendert. Für diesen Schritt brauchst du kein Konto. Als Nächstes richtest du die App auf deinen eigenen Workspace aus.

Schritt 2: Einen API-Token erstellen

Öffne im cmssy-Dashboard API Tokens und klicke auf Create Token. Vergib einen Namen und wähle unter Workspace den Workspace, den dieses Projekt verwendet. Ein Token, der auf einen Workspace begrenzt ist, kann nur diesen Workspace öffnen - mehr braucht ein Agent in einem Repository nicht.

Kopiere den Wert cs_..., sobald er erscheint. Er wird nur einmal angezeigt.

Ein Token hat keine eigenen Berechtigungen. Er handelt als du, mit der Rolle, die du in diesem Workspace hast: Der Token eines Editors kann bearbeiten, der Token eines Mitglieds mit Leserechten kann nur lesen.

Schritt 3: Die App mit deinem Workspace verknüpfen

npx @cmssy/cli link --token cs_your_token

link holt deinen Organization-Slug, den Workspace-Slug und das Draft-Secret und schreibt sie in .env.local. Hat der Workspace noch kein Block-Manifest, schiebt es zusätzlich das der App hoch. Dieses Manifest ist die Liste der Block-Typen, die die App rendern kann, hier prose und blog-index. Starte danach pnpm dev neu.

Das Manifest ist der Grund, warum Claude keinen Block auf eine Seite setzt, den deine Website nicht rendern kann: Der Server lehnt Block-Typen ab, die nicht im Manifest stehen.

Schritt 4: Die Workspace-ID finden

Der MCP-Server braucht neben dem Token eine Workspace-ID. Öffne die Settings deines Workspace. Die ID steht unter Workspace Information.

Schritt 5: Den MCP-Server registrieren

Lege eine .mcp.json im Projektstamm an. Sie enthält keine Geheimnisse, du kannst sie also committen:

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

Den Token behältst du besser in deiner Shell. Der Server liest CMSSY_API_TOKEN und CMSSY_WORKSPACE_ID aus seiner Umgebung, und Claude Code startet ihn mit deiner:

export CMSSY_API_TOKEN=cs_your_token
export CMSSY_WORKSPACE_ID=your_workspace_id
claude

Wenn du claude zum ersten Mal im Projekt startest, fragt Claude Code, ob du dem MCP-Server aus der .mcp.json vertraust. Bestätige das und führe dann /mcp aus. Du solltest cmssy als verbunden sehen.

Der Server akzeptiert auch die Flags --token und --workspace-id. Nutze sie für einen schnellen lokalen Test, halte den Token aber aus eingecheckten Dateien heraus.

Schritt 6: Fragen, was die Website rendern kann

Beginne mit etwas, das nur liest:

Welche Block-Typen kann meine Website rendern, und welche Seiten gibt es?

Claude ruft list_block_types und list_pages auf. Die Block-Typen, die es auflistet, stammen aus dem Manifest deiner App, samt ihrer Felder. So weiß Claude, dass prose ein Rich-Text-Feld body hat, bevor es etwas schreibt.

Schritt 7: Eine Seite bauen und veröffentlichen

Erstelle eine /blog-Seite mit einem Blog-Index, der ihre Unterseiten auflistet.
Lege darunter einen Beitrag namens "Hello from Claude Code" an, mit zwei kurzen
Absätzen in einem prose-Block. Befülle jede Sprache, die im Workspace
aktiviert ist, und veröffentliche dann beide Seiten.

Claude arbeitet sich durch get_site_config (um deine Sprachen zu sehen), create_page, add_block_to_page und publish_page. Claude Code fragt vor jedem Tool nach, das du noch nicht erlaubt hast, du siehst also jeden Schreibvorgang, bevor er passiert.

Lade http://localhost:3000/blog neu. Der Index listet den neuen Beitrag, und der Beitrag wird über die prose-Komponente der App gerendert.

Schritt 8: Bearbeiten und erneut veröffentlichen

Schreib den ersten Absatz von "Hello from Claude Code" so um, dass er
MCP erwähnt, und ändere den SEO-Titel. Veröffentliche ihn danach.

Änderungen landen zuerst im Entwurf der Seite. Deine Website liefert nur die veröffentlichte Version aus, also ändert sich in der App nichts, bis publish_page läuft. Danach lädst du neu und der neue Text ist da: In der Entwicklung rendert Next jede Anfrage frisch.

Für einen einzelnen Absatz in einem langen Artikel kann Claude patch_block_content nutzen, das nur den geänderten Teil sendet statt des gesamten HTML.

Festlegen, was Claude ungefragt tun darf

Claude Code fragt vor jedem MCP-Aufruf nach, den du nicht erlaubt hast. Lesezugriffe kannst du bedenkenlos erlauben. Lass Schreibzugriffe, und besonders publish_page und delete_page, bei der Rückfrage. In .claude/settings.json:

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

Der Server kennzeichnet seine Tools für den Client: Lese-Tools als schreibgeschützt, und die, die löschen, veröffentlichen oder eine Erstattung erfassen, als destruktiv.

Der Weg in die Produktion

In der Produktion cached simple-blog jede Seite bis zu einer Stunde (revalidate = 3600), eine Veröffentlichung würde also verspätet erscheinen. Aktiviere sofortige Updates mit einer Revalidate-Route und einem Webhook:

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

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

Lege das in app/api/revalidate/route.ts ab und abonniere dann einen Webhook auf content.changed, der darauf zeigt. Claude kann den Webhook mit create_webhook anlegen. Das Signing-Secret kommt nur einmal zurück, trage es also direkt in CMSSY_WEBHOOK_SECRET bei deinem Host ein. Die Route prüft die Signatur und verwirft die cmssy-Cache-Tags.

Kein Token? Stattdessen anmelden

Claude Code kann auch den gehosteten MCP-Server von cmssy nutzen, der dich statt mit einem Token über den Browser anmeldet:

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

Führe /mcp aus und authentifiziere dich. Du wählst, welche Workspaces Claude nutzen darf und ob es nur Lese- oder Lese- und Schreibzugriff bekommt. Die Tools sind dieselben, aber jedes nimmt den Workspace als org/workspace, sodass eine Verbindung mehrere Workspaces bedienen kann. Nutze die Token-Variante für CI oder alles ohne Browser.

Fehlerbehebung

Jeder Aufruf liefert "Not authorized": Der Token ist widerrufen oder abgelaufen, oder er kann den Workspace in CMSSY_WORKSPACE_ID nicht öffnen. Der Server startet auch mit einem fehlerhaften Token, daher beweist ein "connected" in /mcp nicht, dass der Token gültig ist.
Der Server erscheint nicht: Die Variablen wurden nicht in der Shell exportiert, die claude gestartet hat. Ohne Token beendet sich der Server beim Start.
Ein erwartetes Tool fehlt: npx hat womöglich einen alten Build im Cache. Vergleiche npx -y @cmssy/mcp-server --version mit npm view @cmssy/mcp-server version.
Ein Block wird abgelehnt: Sein Typ steht nicht im Workspace-Manifest. Bitte Claude, list_block_types auszuführen und einen Typ zu verwenden, der dort steht.

Die vollständige Referenz, einschließlich aller Tools und der jeweils nötigen Berechtigung, steht in den MCP-Server-Docs. Tokens werden unter API tokens behandelt.

Claude Code über MCP mit deinem Headless-CMS verbinden