Dokumentation

MCP-Connector aktivieren.

Drei Schritte: einen Schalter in der Setzkasten-Konfig umlegen, im Admin-UI die Verbindungs-URL holen, dem KI-Client einmalig anlernen. Keine Env-Vars, kein manuelles Schlüssel-Handling. Setzkasten erzeugt und persistiert den Signing-Key selbst im Config-Repo.

Voraussetzungen

Setzkasten-Installation läuft (Single- oder Multi-Mode, beides funktioniert).
Pro- oder Enterprise-Lizenz ist aktiv, denn der MCP-Connector ist ein bezahltes Feature.
Die GitHub-App, die der Manifest-Wizard angelegt hat, ist auf der Site installiert (gleicher Zustand wie beim normalen Editor-Login).
Im Admin-UI ist mindestens ein Redakteur in _editors.json eingetragen. Wer da nicht drinsteht, hat im MCP genauso wenig Rechte wie im UI.
Die Installation ist öffentlich über HTTPS erreichbar — der MCP-Client wird die Discovery-URLs (/.well-known/oauth-authorization-server etc.) direkt anfragen.

Schritt 1

MCP in `setzkasten.config.ts` einschalten.

Ein neuer Block in der bestehenden Konfig — fertig. Erst durch enabled: true werden die OAuth- und MCP-Routes vom Astro-Integration- Plugin registriert.

// setzkasten.config.ts
export default defineConfig({
  storage: { /* ... */ },
  auth: { /* ... */ },
  mcp: {
    enabled: true,
    // Nur wenn ihr auf mehrere Container skaliert (Vercel Autoscale,
    // Cloudflare): optionaler Upstash-Redis-Endpoint.
    // kvUrl: 'https://eu1-xxx.upstash.io',
    // kvToken: 'AX...',
  },
})

Schritt 2

Im Admin-UI die Verbindungs-Adresse abholen.

Im Admin: „Einstellungen → MCP-Connector" öffnen. Setzkasten zeigt dort:

Den Status (aktiv / nicht aktiv).
Die Endpoint-URL, die du in den KI-Client einträgst.
Die Discovery-URLs zur Verifikation.
Die Liste der bereits verbundenen KI-Clients (Claude.ai, ChatGPT, …) mit Einzel-Revoke-Button.
Den Signing-Key-Status — beim ersten Aufruf wird ein RSA-Key generiert und als content/_mcp-signing-key.json ins Config-Repo committed.

Schritt 3

KI-Client verbinden.

Claude.ai (Browser & Desktop)

Einstellungen → Connectors → „Add custom connector".
Name: Setzkasten, URL aus dem Admin-Panel kopieren.
Beim ersten Aufruf erscheint die Login-Bridge → Google-Anmeldung → fertig.
Im Chat als Tool-Quelle aktivieren.

ChatGPT (Plus / Pro)

Settings → Connectors → „Custom MCP Server" (Beta).
URL aus dem Admin-Panel einfügen.
Authorization-Flow durchklicken — DCR registriert ChatGPT automatisch.
Im Chat erwähnen, dass der Setzkasten-Connector genutzt werden soll.

Cursor

Settings → Features → MCP → Add server.
Typ „Streamable HTTP", URL aus dem Admin-Panel.
Auth-Popup durchlaufen.
In jedem Workspace verfügbar, in dem du Cursor benutzt.

Eigene Bots

JSON-RPC 2.0 über POST, Session-ID im Mcp-Session-Id-Header, Authentifizierung per Bearer-JWT. Discovery-URLs liefern alles Nötige; DCR steht offen für jeden Client mit einer gültigen Redirect-URI.

Hosting & Skalierung

Wo läuft was?

Setzkasten teilt sich in drei Schichten, die unabhängig voneinander gehostet werden können. Wichtig: die verwaltete Website darf weiterhin statisch ausgeliefert werden — nur Admin und MCP brauchen einen Node-Host.

Admin-App

Editor-UI + API-Routes

Braucht einen Node-Host (SSR). In Single-Mode steckt das im Astro-Projekt der Website; in Multi-Mode ist es eine eigenständige App.

MCP-Endpoint

Teil der Admin-App

/api/setzkasten/mcp, OAuth-Routes und /.well-known/* werden über dieselben API-Routes ausgeliefert wie das Admin-UI — kein zweites Deployment.

Verwaltete Website

Bleibt frei wählbar

Die öffentliche Website darf weiterhin statisch liegen — Cloudflare Pages, Netlify CDN, GitHub Pages, S3. Setzkasten committet via GitHub-App, das Hosting baut automatisch neu.

Hoster-Optionen für Admin + MCP

Host	MCP-Eignung	Bemerkung
Eigener Server, VPS, Hetzner, Coolify	Ideal	Long-running Node-Prozess, Session-Map lebt natürlich.
Railway, Fly.io, Render	Ideal	Ein Prozess pro Region, autostart, ohne Cold-Starts.
Vercel, Netlify (Serverless)	Funktioniert	Container-ephemer: MCP-Sessions können nach Cold-Start verloren gehen, der Client reconnectet transparent. Für mehr Last `mcp.kvUrl` + `mcp.kvToken` in `setzkasten.config.ts` setzen.
Cloudflare Workers	Mit Anpassung	Stateless-Modell, in-memory funktioniert nicht. `mcp.kvUrl` mit Upstash-REST (oder einer KV-Implementierung über Durable Objects) erforderlich.

Skalierung: gemeinsamer KV-Store

Sobald mehr als ein Prozess parallel den MCP-Endpoint bedient, braucht es einen geteilten Speicher für Mcp-Session-Id und ausgestellte Authorization-Codes. In setzkasten.config.ts reicht:

mcp: {
  enabled: true,
  kvUrl: 'https://eu1-xyz.upstash.io',
  kvToken: 'AX...REST-Token...',
}

Kompatibel mit jedem Upstash-Redis-Endpoint (REST-API) oder einem selbst gehosteten Redis-Proxy mit gleicher Schnittstelle. Auf einem Single-Container- Host weglassen — der eingebaute In-Memory-Store reicht.

Referenz

Welche Tools stehen den KI-Agenten zur Verfügung?

25 Tools in vier Gruppen: Session-Management, Discovery & Schema, Content-Operationen, Change-Sets & Preview. Alle Content-Tools arbeiten auf der aktiven Site und respektieren die Editor-Berechtigungen — Schreib-Tools laufen (im Auto-Modus) auf den Session-Draft-Branch.

Session

list_my_sites Welche Websites darf ich bearbeiten?
switch_site Aktive Website für die Connection wählen.
get_current_site Welche Site ist gerade aktiv?

Discovery & Schema

list_pages Welche Seiten gibt es auf der aktiven Site?
search_content GitHub-Code-Search auf Sektionen, Seiten oder Assets.
list_tree Verzeichnisstruktur des Branches durchforsten.
get_template_schema JSON-Schema eines Catalog-Templates abrufen (mit allowedTags für Rich-Text).

Content

read_file Datei lesen (Pfad, Content, SHA, Größe).
write_file Datei in einem atomaren Commit schreiben (Schema- & Sanitize-Check).
upload_asset Bild oder Datei (base64) unter content/assets/ ablegen.
add_section Neue Section atomar anlegen — File + Page-Config in einem Commit. Position via after/before/index, Key-Mint mit Suffix-Handling.
remove_section Section löschen — File weg + Page-Config aktualisieren, ein Commit.
reorder_sections Komplette Permutation der Section-Reihenfolge auf einer Page; lehnt fehlende oder zusätzliche Keys ab.
append_to_text Server-seitiges Anhängen an ein Rich-Text-Feld. Agent sieht den Bestand nie — keine Halluzination.
replace_in_text String-Replace in einem Feld mit expectMatches-Sicherheitsnetz. Falsche Trefferzahl → 409, kein Commit.

Change-Sets & Preview

begin_change_set Draft-Branch öffnen (mcp-cs-…). Liefert Review-URL und Preview-URL zurück.
end_change_set Squash-Merge nach main oder PR-Mode für Review-Required-Setups.
cancel_change_set Draft verwerfen — Branch löschen, Eintrag als cancelled markieren.
revert_change_set Bereits gemergten Change-Set linear zurückrollen (gleicher Pfad wie History-Rollback).
list_my_change_sets Eigene offene und kürzlich gemergte Drafts.
get_change_set_preview Review-URL, Branch-Deploy-URL und Build-Status für einen Draft.
request_preview_deploy Im Manuell-Modus den Hoster-Build explizit auslösen. Pollbar bis ready.

Assets & History

list_assets Alle Dateien unter content/assets/ auflisten (optional mit Sub-Prefix). Für SEO/Alt-Text-Sweeps.
read_asset Asset (Bild/PDF/…) als base64 + MIME-Typ lesen. Vision-fähige Agenten holen Bilder direkt via MCP.
get_file_history Recent commits für einen Pfad (Default 10, max 50). Reporting-/Audit-Antworten ("wer hat zuletzt geändert").

Optional

Preview-Branch-Deploy einrichten.

Damit Drafts nicht nur im Admin-Page-Builder sichtbar sind, sondern als echte Preview-URL aus deinem Hoster: konfiguriere die Branch-Deploy-Vorlage entweder in der Setzkasten-Config oder im Admin-Panel Einstellungen → Preview (Pro+).

// setzkasten.config.ts
export default defineConfig({
  storage: { /* ... */ },
  auth: { /* ... */ },
  mcp: { enabled: true },
  preview: {
    // {branch} wird durch den Draft-Branch ersetzt
    branchDeployUrl: 'https://{branch}.example.pages.dev',

    // 'auto' = Hoster baut bei jedem Push (Vercel/CFP/Netlify Default)
    // 'manual' = Build erst nach request_preview_deploy
    deployMode: 'auto',

    // Pflicht im manual-Modus:
    // deployHookUrl: 'https://api.vercel.com/v1/integrations/deploy/...',
  },
})

Auto-Modus

Branch-Push triggert beim Hoster automatisch einen Build. Du bezahlst eine Build-Quota pro Draft. Im Admin erscheint „Externe Vorschau ansehen".

Manuell-Modus

Beim Hoster Auto-Build für mcp-cs-* und draft-* abschalten. Setzkasten triggert via Deploy-Hook nur, wenn jemand „Externe Vorschau deployen" klickt oder der Agent request_preview_deploy aufruft. Kostenkontrolle.

Troubleshooting

Häufige Fehlercodes – und wie sie zu beheben sind.

no_active_site

Erst switch_site mit einer erlaubten siteId aufrufen.

site_not_allowed

Die Site ist nicht in claims.sites – Editor-Whitelist (Admin-UI) erweitern.

page_not_allowed

Editor hat keinen Zugriff auf diese Page-Key. _editors.json prüfen.

path_forbidden

Pfad muss unter content/_sections/, content/pages/ oder content/assets/ liegen. Keine `..`-Segmente, kein führender `/`.

schema_violation

Content passt nicht zum Template. Erst get_template_schema lesen, dann anpassen. Rich-Text-Tags außerhalb der Whitelist werden gestrippt.

sha_mismatch

Datei wurde zwischen read_file und write_file von jemand anderem geändert. read_file erneut aufrufen und mit dem neuen SHA committen.

unauthenticated

Bearer-Token fehlt, ist abgelaufen oder ungültig. Im MCP-Client neu verbinden, ggf. erneut über Setzkasten anmelden.

invalid_position

add_section: Referenz-Section in position.after / position.before existiert nicht. Aktuelle Section-Liste steht in der Fehler-Payload.

invalid_order

reorder_sections: Set der übergebenen Keys stimmt nicht mit existierenden Keys überein. Payload listet missing / extra.

section_not_found

remove_section / append_to_text / replace_in_text: Section- oder Page-Key existiert nicht.

match_count_mismatch

replace_in_text: tatsächliche Trefferzahl ≠ expectMatches. Suchstring präzisieren oder expectMatches anpassen.

preview_deploy_not_configured

request_preview_deploy: keine deployHookUrl im Admin oder setzkasten.config.ts gesetzt. Im Manuell-Modus Pflicht.

merge_conflict

end_change_set: Draft hinter main durch parallelen Merge. Review-UI bietet Rebase oder Discard.

Bereit für den ersten Edit?

Ein mcp.enabled: true in der Konfig, ein Deploy, ein Klick im Admin-Panel — und Claude/ChatGPT/Cursor sind dran.

Was ist Setzkasten + MCP? Hilfe beim Setup anfragen