MCP Server

Überblick

@cmssy/mcp-server ist ein Model-Context-Protocol-Server, der KI-Agenten (Claude Code, Claude Desktop, jedes MCP-fähige Tool) mit einem Cmssy-Workspace verbindet. Einmal konfiguriert, kann der Agent Seiten auflisten und bearbeiten, Blöcke hinzufügen oder entfernen, Entwürfe veröffentlichen, Formulare verwalten und mehr — ohne je den Editor zu verlassen.

Er läuft auf zwei Wegen: Claude verbindet sich nach der Anmeldung bei cmssy mit dem gehosteten Server unter https://api.cmssy.io/mcp, und jeder MCP-Client kann das npm-Paket über stdio mit einem API-Token starten. Keiner der beiden braucht einen eigenen, dauerhaft laufenden Server.

Was ihn vom HTTP-API unterscheidet

• Workspace-scoped — ein einziges Paar aus Token + Workspace-ID, alles serverseitig durchgesetzt
• High-Level-Tools — add_block_to_page, publish_page, patch_block_content, kein rohes GraphQL
• Tenant-Isolation eingebaut — jede Query wird nach deinem Workspace gefiltert; du kannst nicht versehentlich einen anderen Tenant anfassen

Claude verbinden (ohne Token)

Claude im Web, Claude Desktop und Claude Code verbinden sich mit dem gehosteten Server unter https://api.cmssy.io/mcp. Du meldest dich bei cmssy an und wählst die Workspaces, die Claude nutzen darf - kein Token zum Kopieren, nichts zu installieren.

Claude im Web oder auf dem Desktop

1. Öffne Settings → Connectors und wähle Add custom connector.
2. Füge https://api.cmssy.io/mcp ein und füge ihn hinzu.
3. Klicke Connect, melde dich bei cmssy an, hake die Workspaces für Claude an und wähle Nur lesen oder Lesen und schreiben.

Ein auf claude.ai hinzugefügter Connector steht auch in Claude Desktop bereit.

Claude Code

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

Führe dann /mcp in Claude Code aus und authentifiziere dich: Dieselbe Anmeldung und Workspace-Auswahl öffnen sich im Browser.

Im Admin zeigt Konto → Verbundene Apps → Mit Claude verbinden dieselbe URL und denselben Befehl mit Kopier-Buttons.

Was Claude kann

• Deine Rolle, pro Workspace - Claude handelt als du, mit der Rolle, die du in jedem angehakten Workspace hast. Nur lesen beschränkt es aufs Lesen, auch wenn deine Rolle schreiben dürfte.
• Mehrere Workspaces gleichzeitig - jedes Tool nimmt ein workspace-Argument (org-slug/workspace-slug), und list_workspaces listet die freigegebenen. Ein Workspace, dem du später beitrittst, kommt nicht automatisch dazu - verbinde dich erneut, um ihn aufzunehmen.
• Destruktive Tools fragen zuerst - Claude fragt dich vor einem Tool, das löscht oder veröffentlicht, und die serverseitige Bestätigung (unten) gilt weiterhin.
• Auditiert auf deinen Namen - eine Änderung von Claude landet im Audit-Log des Workspace unter deinem Namen, wie eine Änderung, die du im Admin machst.

Trennen

Konto → Verbundene Apps → Trennen schneidet Claude von allen Workspaces auf einmal ab. Ein Workspace-Admin kann einen Workspace aus der App eines Mitglieds entfernen, unter Einstellungen → Verbundene Apps; die übrigen Workspaces des Mitglieds funktionieren weiter. Verlierst du den Zugang zu einem Workspace, fällt er aus deinen Verbindungen.

Was Claude erreicht

Nur der Inhalt der angehakten Workspaces und nur das, was ein Tool-Aufruf zurückgibt. cmssy speichert die Verbindung selbst (welche App, welche Workspaces, Lesen oder Schreiben) und gehashte Tokens - nie eine Kopie der Unterhaltung.

Einrichtung mit API-Token (stdio)

Für CI, Skripte oder einen Agenten ohne Browser startest du stattdessen das npm-Paket mit einem API-Token.

1. Erstelle ein API-Token

Workspace Settings → API Tokens → Create token. Kopiere den cs_…-Wert sofort — Tokens werden nur einmal angezeigt. Der Scope ist reine Authentifizierung; was das Token darf, bestimmen deine Rolle und das isSuperAdmin-Flag.

Kein Browser? Ein Agent kann Konto, Organisation, Workspace und Token über das API erstellen - siehe Ein Token ohne Browser erstellen.

2. Finde deine Workspace-ID

Workspace Settings → General hat einen Kopier-Button neben der ID. Es ist derselbe Workspace, an den dein API-Token gebunden ist.

3. Trage ihn in die MCP-Config deines Editors ein

Für Claude Code bearbeite .mcp.json im Projekt-Root (oder registriere ihn für alle Projekte mit claude mcp add --scope user):

{
  "mcpServers": {
    "cmssy": {
      "command": "npx",
      "args": [
        "-y",
        "@cmssy/mcp-server@latest",
        "--token", "cs_your_token_here",
        "--workspace-id", "507f1f77bcf86cd799439011"
      ]
    }
  }
}

Umgebungsvariablen-Äquivalente werden ebenfalls unterstützt: CMSSY_API_TOKEN, CMSSY_WORKSPACE_ID, CMSSY_API_URL. Nützlich, wenn du das Token nicht in einer committeten Config-Datei haben willst.

--api-url (oder CMSSY_API_URL) ist der Origin des API und steht standardmäßig auf https://api.cmssy.io; der Server hängt /graphql selbst an, lass es also weg.

4. Editor neu starten

Claude Code lädt den Server beim nächsten Sessionstart. Du solltest einen cmssy-MCP-Eintrag mit den verfügbaren Tools sehen.

Verfügbare Tools

Die vollständige Liste, mit der Berechtigung, die jedes Tool braucht, steht unter MCP-Tools - der Server erzeugt sie bei jedem Release, sie entspricht also immer dem, was deine Version bereitstellt. Die Tools folgen einem Namensschema - list_* und get_* zum Lesen, create_* / update_* / delete_* zum Schreiben, dazu Verben für Zustandsübergänge - und gliedern sich in diese Gruppen:

• Seiten und Blöcke - Seitenbaum, Blöcke, Layout-Regionen, Seitentypen und Veröffentlichung: get_page, add_block_to_page, patch_block_content, publish_page. Rufe vor dem Hinzufügen eines Blocks list_block_types auf: Es liefert die Blocktypen, die deine Site tatsächlich registriert.
• Modelle und Records - Schemas und ihre Einträge, inklusive Massen-import_records. delete_record verweigert, solange ein Block den Record noch nutzt, und nennt die Seiten, die ihn nutzen; übergib force: true, um trotzdem zu löschen.
• Medien - Uploads und Ordner.
• Formulare - Formulare und ihre Einsendungen.
• Commerce - Produkte, Bestellungen (manuelle Bestellungen, Zahlungen, Rechnungen, Erstattungen, Fulfillment, die Bestell-Pipeline), Warenkörbe, Rabatte und Kunden.
• Webhooks - Abonnements, Zustellungen und Signatur-Secrets. list_webhook_event_types ist die Allowlist der abonnierbaren Events; ein Signatur-Secret kommt einmal zurück, beim Erstellen und beim Rotieren.
• Workspace - get_workspace_info (Plan, Limits, Nutzung), get_site_config, Team und Rollen.

Die Volltextsuche search_content ist im MCP-Server nicht gebunden; sie ist über den Assistenten im Admin erreichbar. Nichts in diesem Set fasst deinen Code an: Kein Tool schreibt eine Datei, bearbeitet eine Komponente oder öffnet einen Pull Request - die KI bearbeitet Content, und Block-Schemas bleiben in deinem Repository unter Review.

Bestätigung vor destruktiven Aktionen

Tools, deren Wirkung sich am schwersten rückgängig machen lässt - zum Beispiel delete_page, publish_page, refund_order, bulk_delete_products - handeln nicht beim ersten Aufruf. Sie antworten mit needsConfirmation: true, einer einzeiligen summary dessen, was passieren würde, und einer ref - und nichts ändert sich. Der Agent zeigt dir die Zusammenfassung; nach deiner Zustimmung ruft er dasselbe Tool mit denselben Argumenten plus _confirm: "<ref>" erneut auf.

• Eine Ref gilt einmal, für die in expiresInSeconds genannte Zeit, und nur mit den Argumenten, für die sie ausgestellt wurde - ändere ein Argument, und der Server fragt erneut.
• Ein Tool, das eine Bestätigung braucht, hat einen _confirm-Parameter in seinem Input-Schema, ein Client erkennt es also an tools/list.
• Dieselbe Regel gilt im KI-Assistenten im Admin, wo du per Button im Chat bestätigst.

Dev-Drafts: ein Block, der noch nicht deployt ist

Jedes Write-Tool nimmt ein optionales target. "draft" (Standard) bearbeitet den gemeinsamen Seitenentwurf; "devDraft" bearbeitet dein eigenes Overlay pro Benutzer, das von der aktuellen Seite ausgeht und niemandes Vorschau verändert.

Genau das macht es sicher, eine Seite um einen Blocktyp herum zu bauen, den es bisher nur auf deinem Rechner gibt. Ist der Block ausgeliefert, schiebt promote_dev_draft dein Overlay auf den gemeinsamen Entwurf. get_page mit target: "devDraft" liefert das Overlay neben dem gemeinsamen Entwurf - oder null, wenn du keines hast.

patch_block_content — chirurgische Edits

Für gezielte Edits an Multi-KB-Content (Docs-Artikel, lange Blogposts) sendet patch_block_content nur den Diff — nicht den ganzen String. Dahinter steckt MongoDB findOneAndUpdate mit $set + arrayFilters, tenant-scoped, atomar. Typischerweise ~10× günstiger in Tokens, als das ganze HTML über update_block_content erneut zu senden.

Drei Operationstypen

insert_before / insert_after

Füge HTML direkt vor/nach einem eindeutigen Marker ein. Der Marker MUSS genau eine Stelle treffen — null oder mehrere Treffer lehnen die Operation mit BAD_USER_INPUT ab.

{
  "op": "insert_after",
  "marker": "<h2>Pricing</h2>",
  "html": "<p>Plans start at $0/month.</p>"
}

replace_section

Ersetze alles von startMarker (inklusive) bis endMarker (exklusive). Beide Marker müssen sich eindeutig auflösen lassen.

{
  "op": "replace_section",
  "startMarker": "<h2>Pricing</h2>",
  "endMarker": "<h2>FAQ</h2>",
  "html": "<h2>Pricing</h2><p>New plans here.</p>"
}

Mehrere Ops in einem Aufruf

Operationen werden der Reihe nach auf das laufende Ergebnis angewendet. Jeder Fehler (fehlender Marker, mehrdeutig usw.) bricht den gesamten Patch ab — kein halb angewendeter Zustand.

{
  "pageId": "...",
  "blockId": "...",
  "locale": "en",
  "operations": [
    {
      "op": "insert_before",
      "marker": "<h2>Appendix</h2>",
      "html": "<h2>New Section</h2><p>…</p>"
    },
    {
      "op": "replace_section",
      "startMarker": "<h2>Pricing</h2>",
      "endMarker": "<h2>FAQ</h2>",
      "html": "<h2>Pricing</h2><p>Updated.</p>"
    }
  ]
}

Wenn eine Operation fehlschlägt

• 0 Treffer — Marker nicht gefunden. Prüfe auf exakte zeichengenaue Übereinstimmung; Whitespace und Attributreihenfolge zählen.
• 2+ Treffer — der Marker ist nicht eindeutig. Füge umgebendes HTML zur Disambiguierung hinzu. Überlappende Treffer zählen ("aa" in "aaa" zählt als 2), vermeide also ultrakurze Marker.
• Feld ist kein String — der anvisierte fieldPath löst zu einem Array oder Objekt auf. Nutze update_block_content für strukturierte Felder.
• Layout-Blöcke nicht unterstützt — Header/Footer und andere Layout-Blöcke laufen über update_block_content.

patch_block_content vs update_block_content

Faustregel: Wenn du früher das gesamte HTML erneut geschickt hättest, um einen Absatz zu ändern, nimm patch_block_content. Sonst bleib bei update_block_content.

Troubleshooting

• Jeder Aufruf endet mit 404 - --api-url endet auf /graphql. Gib nur den Origin an (https://api.cmssy.io, der Standard) - der Server hängt den Pfad selbst an.
• „Workspace not found“ — die Person hinter dem Token ist kein Mitglied der angegebenen --workspace-id, oder die ID stimmt nicht. Ein Token authentifiziert eine Person; was es darf, ergibt sich aus deren Rolle in diesem Workspace. Prüfe das Paar in den Workspace Settings.
• „Not authenticated“ — Token abgelaufen oder widerrufen. Erstelle ein neues unter Workspace Settings → API Tokens.
• MCP-Server im Editor nicht sichtbar — starte den Editor nach Config-Änderungen neu. In Claude Code findest du unter Settings → MCP → cmssy die Startup-Logs.
• Rate-Limits / Plan-Limits — der MCP-Server respektiert die Plan-Limits des Workspace (max. Seiten, Storage, KI-Tokens). get_workspace_info zeigt die aktuelle Nutzung vs. Limits.

Response-Modus

Jedes Write-Tool akzeptiert einen optionalen Parameter response: "minimal" | "full" (Default "minimal"). Minimal gibt ein kleines Compact-JSON-Ack (~100-200 Bytes) zurück, nur mit den IDs und dem Zustand, den du zum Verketten des nächsten Aufrufs brauchst — nicht die volle mutierte Ressource.

Minimal-Ack-Formen

• Seiten-Tools (create_page, update_page_blocks, update_page_settings, publish_page, unpublish_page, revert_to_published, update_page_layout) — {id, slug, hasUnpublishedChanges, updatedAt} (+published bei publish/unpublish)
• Block-on-Page-Tools (add_block_to_page, update_block_content, remove_block_from_page) — {pageId, blockId, hasUnpublishedChanges, updatedAt}
• Formular-Tools (create_form, update_form) — {id, slug, status, updatedAt}
• Modell-Tools (create_model, update_model) — {id, slug, updatedAt}
• Record-Tools (create_record, update_record) — {id, status, updatedAt}

Wann du full wählen solltest

Übergib response: "full", wenn du die volle mutierte Ressource wirklich im selben Aufruf brauchst — z. B. um eine komplette Transformation zu verifizieren, ein servergeneriertes Feld zu lesen oder zu debuggen. Andernfalls hänge einen Lese-Tool-Aufruf an (get_page / get_form / get_model / get_record).

Tools ohne response

Geben bereits ein kompaktes Ack zurück und bleiben unverändert: patch_block_content, alle delete_*, update_form_submission_status, import_records.

Version

Nutze @cmssy/mcp-server@latest in .mcp.json, um neue Tools zu bekommen, sobald sie erscheinen; npx @cmssy/mcp-server --version gibt die Version aus, die du ausführst. Jedes Release veröffentlicht MCP-Tools direkt aus dem Server neu, diese Seite entspricht also immer der neuesten Version.