MCP-Server-Referenz

EmDash enthält einen integrierten Model Context Protocol (MCP) Server unter /_emdash/api/mcp, der Content-Management-Operationen als Tools für KI-Assistenten bereitstellt.

Diese Seite behandelt die Protokolldetails: Authentifizierung, Transport, Tool-Spezifikationen, OAuth-Discovery und Fehlerbehandlung.

Authentifizierung

Der MCP-Server unterstützt drei Authentifizierungsmethoden:

Session-Cookies (aus der Admin-UI) funktionieren ebenfalls, sind aber für externe MCP-Clients nicht praktikabel.

Scopes

Token sind eingeschränkt, um zu begrenzen, welche Operationen ein Client ausführen kann. Scopes werden während der OAuth-Autorisierung angefordert und bei jedem Tool-Aufruf durchgesetzt. Auf der Zustimmungsseite des Authorization-Code-Flows sind alle angeforderten Scopes standardmäßig ausgewählt; der Benutzer kann Scopes vor der Genehmigung entfernen, aber keine hinzufügen, die der Client nicht angefordert hat. Die effektive Berechtigung wird auch durch die registrierten Scopes des Clients und die Rolle des Benutzers eingeschränkt, und EmDash lehnt eine leere Berechtigung ab.

Der admin-Scope gewährt Zugriff auf Kernoperationen, aber nicht auf Plugin-MCP-Zugriff. Plugin-Tools erfordern immer mcp:tools oder den passenden plugin-spezifischen Scope. Session-basierte Auth hat Zugriff basierend auf der Benutzerrolle und der expliziten Admin-Aktivierung des Plugins.

content:write gewährt implizit taxonomies:manage und menus:manage, damit Personal-Access-Token, die vor der Aufteilung dieser Scopes ausgestellt wurden, weiterhin ohne Neuausstellung funktionieren. Neue Token sollten die granularen Scopes anfordern.

Rollenanforderungen

Zusätzlich zu Scopes erfordern einige Tools eine Mindest-RBAC-Rolle. Beide müssen erfüllt sein — ein Token mit dem richtigen Scope schlägt trotzdem fehl, wenn die Rolle des aufrufenden Benutzers zu niedrig ist.

Plugin-Tools verwenden die Berechtigung, die von ihrer zugrunde liegenden Route deklariert wird. Sie fehlen in tools/list, bis ein Administrator die MCP-Oberfläche dieses Plugins aktiviert. Tool-Namen verwenden die deterministische Form <pluginId>__<localName>, und Aufrufe werden im Audit-Log mit Plugin-, Tool-, Routen- und Akteur-Provenienz aufgezeichnet.

Siehe den Authentifizierungsleitfaden für Rollendefinitionen.

Transport

Der Server verwendet den Streamable-HTTP-Transport im zustandslosen Modus. Jede Anfrage ist unabhängig — es gibt keine Sessions oder langlebigen Verbindungen.

• POST /_emdash/api/mcp — JSON-RPC-Tool-Aufrufe senden
• GET /_emdash/api/mcp — Gibt 405 zurück (kein SSE im zustandslosen Modus)
• DELETE /_emdash/api/mcp — Gibt 405 zurück (keine Session zum Schließen)

Antworten folgen dem JSON-RPC 2.0-Format. Fehler verwenden Standard-JSON-RPC-Fehlercodes, mit MCP-spezifischen Codes für Scope- und Berechtigungsfehler.

Tools

Der Server stellt Tools in acht Domänen bereit: Inhalt, Schema, Medien, Suche, Taxonomien, Menüs, Revisionen und Einstellungen. Jedes Tool gibt Ergebnisse als JSON-Textinhalt zurück oder eine Fehlermeldung mit isError: true bei Fehlern.

Inhalts-Tools

content_list

Listet Inhaltselemente in einer Sammlung mit optionaler Filterung und Paginierung auf.

Scope: content:read | Nur-Lesen: Ja

content_get

Ruft ein einzelnes Inhaltselement nach ID oder Slug ab. Gibt alle Feldwerte, Metadaten und ein _rev-Token für optimistische Nebenläufigkeit zurück.

Scope: content:read | Nur-Lesen: Ja

content_create

Erstellt ein neues Inhaltselement. Das data-Objekt sollte Feldwerte enthalten, die dem Schema der Sammlung entsprechen — verwenden Sie schema_get_collection, um zu prüfen, welche Felder verfügbar sind. Elemente werden standardmäßig als draft erstellt.

Scope: content:write

content_update

Aktualisiert ein bestehendes Inhaltselement. Nur Felder einschließen, die geändert werden sollen — nicht angegebene Felder bleiben unverändert.

Scope: content:write

content_delete

Löscht ein Inhaltselement weich, indem es in den Papierkorb verschoben wird. Verwenden Sie content_restore zum Rückgängigmachen oder content_permanent_delete zum endgültigen Entfernen.

Scope: content:write | Destruktiv: Ja

content_restore

Stellt ein weich gelöschtes Inhaltselement aus dem Papierkorb wieder her.

Scope: content:write

content_permanent_delete

Löscht ein im Papierkorb befindliches Inhaltselement dauerhaft und unwiderruflich. Das Element muss sich zuerst im Papierkorb befinden.

Scope: content:write | Destruktiv: Ja

content_publish

Veröffentlicht ein Inhaltselement und macht es auf der Site live. Erstellt eine veröffentlichte Revision aus dem aktuellen Entwurf. Weitere Bearbeitungen erstellen einen neuen Entwurf, ohne die Live-Version zu beeinflussen, bis sie erneut veröffentlicht wird.

Scope: content:write

content_unpublish

Setzt ein veröffentlichtes Element auf den Entwurfsstatus zurück. Es wird auf der Live-Site nicht mehr sichtbar sein, aber sein Inhalt bleibt erhalten.

Scope: content:write

content_schedule

Plant ein Inhaltselement für zukünftige Veröffentlichung. Es wird automatisch zum angegebenen Datum/Zeitpunkt veröffentlicht.

Scope: content:write

content_unschedule

Hebt eine zuvor geplante Veröffentlichung auf. Das Element behält seinen aktuellen Status; nur der scheduledAt-Zeitstempel wird gelöscht. Idempotent — der Aufruf bei einem nicht geplanten Element ist eine No-Op.

Scope: content:write

content_compare

Vergleicht die veröffentlichte (Live-)Version eines Inhaltselements mit seinem aktuellen Entwurf. Gibt beide Versionen und ein Flag zurück, das anzeigt, ob es Änderungen gibt.

Scope: content:read | Nur-Lesen: Ja

content_discard_draft

Verwirft den aktuellen Entwurf und kehrt zur letzten veröffentlichten Version zurück. Funktioniert nur bei Elementen, die mindestens einmal veröffentlicht wurden.

Scope: content:write | Destruktiv: Ja

content_list_trashed

Listet weich gelöschte Inhaltselemente im Papierkorb einer Sammlung auf.

Scope: content:read | Nur-Lesen: Ja

content_duplicate

Erstellt eine Kopie eines bestehenden Inhaltselements. Das Duplikat wird als Entwurf erstellt mit „(Kopie)” am Titel angehängt und einem automatisch generierten Slug.

Scope: content:write

content_translations

Ruft alle Locale-Varianten eines Inhaltselements ab. Gibt die Übersetzungsgruppe und eine Zusammenfassung jeder Locale-Version zurück. Nur relevant, wenn i18n aktiviert ist.

Scope: content:read | Nur-Lesen: Ja

Schema-Tools

schema_list_collections

Listet alle im CMS definierten Inhaltssammlungen auf. Gibt Slug, Label, unterstützte Features und Zeitstempel zurück.

Keine Parameter.

Scope: schema:read | Mindestrolle: Editor | Nur-Lesen: Ja

schema_get_collection

Ruft detaillierte Informationen über eine Sammlung ab, einschließlich aller Felddefinitionen. Felder beschreiben das Datenmodell: Name, Typ, Einschränkungen und Validierungsregeln. Verwenden Sie dies, um zu verstehen, was content_create und content_update erwarten.

Scope: schema:read | Mindestrolle: Editor | Nur-Lesen: Ja

schema_create_collection

Erstellt eine neue Inhaltssammlung. Dies erstellt eine Datenbanktabelle und Schemadefinition. Der Slug muss aus Kleinbuchstaben, Ziffern und Unterstrichen bestehen und mit einem Buchstaben beginnen.

Scope: schema:write | Mindestrolle: Admin

schema_delete_collection

Löscht eine Sammlung und ihre Datenbanktabelle. Dies ist unwiderruflich und löscht alle Inhalte in der Sammlung.

Scope: schema:write | Mindestrolle: Admin | Destruktiv: Ja

schema_create_field

Fügt einer Sammlung ein neues Feld hinzu. Dies fügt der Datenbanktabelle eine Spalte hinzu.

Feldtypen: string, text, number, integer, boolean, datetime, select, multiSelect, portableText, image, file, reference, json, slug.

Für select- und multiSelect-Typen geben Sie erlaubte Werte in validation.options an.

Scope: schema:write | Mindestrolle: Admin

schema_delete_field

Entfernt ein Feld aus einer Sammlung. Dies löscht die Spalte und alle Daten in diesem Feld. Unwiderruflich.

Scope: schema:write | Mindestrolle: Admin | Destruktiv: Ja

Medien-Tools

media_list

Listet hochgeladene Mediendateien mit optionaler MIME-Typ-Filterung und Paginierung auf.

Scope: media:read | Nur-Lesen: Ja

media_upload

Lädt eine Mediendatei aus base64-codierten Daten oder einer externen URL hoch und registriert sie in der Medienbibliothek. Gibt das Medienelement mit id, storageKey und url zurück — bereit zur Referenzierung aus Inhaltsfeldern (z.B. featured_image) über content_create / content_update.

Uploads werden nach Inhaltshash dedupliziert: Erneutes Hochladen identischer Bytes gibt das bestehende Element mit deduplicated: true zurück. Bild-Uploads werden automatisch mit Abmessungen, einem Blurhash-Platzhalter und der dominanten Farbe angereichert.

Scope: media:write | Mindestrolle: Contributor

media_create

Registriert eine Mediendatei, die bereits in den Speicher hochgeladen wurde. Der Aufrufer ist dafür verantwortlich, die Datei unter storageKey zu platzieren. Dieses Tool persistiert den Metadatensatz, damit die Datei über media_list / media_get auffindbar ist und von Inhalten referenziert werden kann.

Scope: media:write | Mindestrolle: Author

media_get

Ruft Details einer einzelnen Mediendatei nach ID ab. Gibt Metadaten einschließlich Dateiname, MIME-Typ, Größe, Abmessungen, Alternativtext und URL zurück.

Scope: media:read | Nur-Lesen: Ja

media_update

Aktualisiert Metadaten einer hochgeladenen Mediendatei. Die Datei selbst kann nicht geändert werden.

Scope: media:write

media_delete

Löscht eine Mediendatei dauerhaft. Entfernt den Datenbankeintrag und die Datei aus dem Speicher. Inhalte, die auf dieses Medium verweisen, haben defekte Referenzen.

Scope: media:write | Destruktiv: Ja

media_usage_repair

Repariert Inhalts-Mediennutzungsindizes für eine Sammlung oder alle Sammlungen. Die Reparatur läuft synchron und kann bei großen Sites langsam oder teuer sein; bevorzugen Sie den Sammlungsumfang wenn möglich.

Das Ergebnis hat einen strukturierten status von complete, partial, failed oder stale, plus aggregierte und pro-Sammlung-Quellenzählungen. Alle vier Status sind erfolgreiche MCP-Tool-Ergebnisse, daher müssen Aufrufer status prüfen anstatt sich auf isError zu verlassen. Authentifizierungs-, Validierungs- oder unerwartete Reparaturfehler geben isError: true zurück.

Scope: admin | Mindestrolle: Admin

Such-Tool

search

Volltextsuche über Inhaltssammlungen. Sammlungen müssen search in ihrer supports-Liste haben und Felder müssen als searchable markiert sein.

Scope: content:read | Nur-Lesen: Ja

Taxonomie-Tools

taxonomy_list

Listet alle Taxonomie-Definitionen auf (z.B. Kategorien, Tags). Gibt Name, Label, ob hierarchisch, und zugehörige Sammlungen zurück.

Keine Parameter.

Scope: content:read | Nur-Lesen: Ja

taxonomy_list_terms

Listet Terme in einer Taxonomie mit Paginierung auf.

Scope: content:read | Nur-Lesen: Ja

taxonomy_create_term

Erstellt einen neuen Term in einer Taxonomie. Für hierarchische Taxonomien geben Sie eine parentId an, um einen untergeordneten Term zu erstellen. Die Vorfahrenkette des übergeordneten Terms darf 100 Ebenen nicht überschreiten.

Scope: taxonomies:manage | Mindestrolle: Editor

taxonomy_update_term

Aktualisiert einen bestehenden Term in einer Taxonomie. Jedes Feld kann weggelassen werden, um es unverändert zu lassen. Das Umbenennen eines Slugs darf nicht mit einem anderen Term in derselben Taxonomie kollidieren. Setzen Sie parentId auf null, um vom übergeordneten Element zu lösen. Der neue übergeordnete Term muss existieren, zur selben Taxonomie gehören und keinen Zyklus erzeugen.

Scope: taxonomies:manage | Mindestrolle: Editor

taxonomy_delete_term

Löscht einen Term dauerhaft aus einer Taxonomie. Alle mit dem Term getaggten Inhalte verlieren die Zuordnung. Kann keinen Term mit untergeordneten Termen löschen — löschen Sie zuerst die untergeordneten.

Scope: taxonomies:manage | Mindestrolle: Editor | Destruktiv: Ja

Menü-Tools

menu_list

Listet Navigationsmenüs auf. Menüs sind pro Locale: Übergeben Sie locale, um nur die Zeilen eines Locales zurückzugeben, oder lassen Sie es weg, um alle Locale-Varianten aufzulisten.

Scope: content:read | Nur-Lesen: Ja

menu_get

Ruft ein Menü nach Name ab, einschließlich aller Einträge in Reihenfolge. Einträge haben ein Label, eine URL, einen Typ und optionalen Parent für Verschachtelung. Wenn derselbe Menüname in mehreren Locales existiert, übergeben Sie locale, um die beabsichtigte Übersetzung aufzulösen.

Scope: content:read | Nur-Lesen: Ja

menu_create

Erstellt ein neues Navigationsmenü. Der name ist der stabile Bezeichner, der von Site-Templates verwendet wird; label ist der menschenlesbare Name, der im Admin angezeigt wird. Menüs sind pro Locale, übergeben Sie also locale, wenn derselbe Menüname in mehreren Übersetzungen existiert. Fügen Sie Einträge anschließend mit menu_set_items hinzu. Wenn translationOf gesetzt ist, muss auch locale gesetzt sein.

Scope: menus:manage | Mindestrolle: Editor

menu_update

Aktualisiert das Label eines Menüs. Der name (stabiler Bezeichner) kann nicht geändert werden. Bei mehrsprachigen Installationen übergeben Sie locale, damit die richtige Übersetzung aktualisiert wird.

Scope: menus:manage | Mindestrolle: Editor

menu_delete

Löscht ein Menü und alle seine Einträge. Kann nicht rückgängig gemacht werden. Bei mehrsprachigen Installationen übergeben Sie locale, damit nur die beabsichtigte Übersetzung entfernt wird.

Scope: menus:manage | Mindestrolle: Editor | Destruktiv: Ja

menu_set_items

Ersetzt die gesamte Eintragsliste eines Menüs in einem Aufruf. Atomar: Bestehende Einträge werden gelöscht und die neue Liste wird in der angegebenen Reihenfolge eingefügt. Verwenden Sie dies anstelle von einzelnen Hinzufügen-/Entfernen-Operationen, damit die resultierende Reihenfolge und Parent-Links eindeutig sind. Bei mehrsprachigen Installationen übergeben Sie locale, damit nur die beabsichtigte Übersetzung überschrieben wird.

Einträge werden nach Array-Index positioniert. Verschachtelung wird über parentIndex ausgedrückt — ein Eintrag mit parentIndex: 0 ist unter dem Eintrag an Index 0 verschachtelt. Der Parent muss früher in der Liste erscheinen. Einträge ohne parentIndex sind auf oberster Ebene.

Jedes MenuItem hat:

Scope: menus:manage | Mindestrolle: Editor

Revisions-Tools

revision_list

Listet die Revisionshistorie eines Inhaltselements auf, neueste zuerst. Erfordert, dass die Sammlung revisions unterstützt.

Scope: content:read | Nur-Lesen: Ja

revision_restore

Stellt ein Inhaltselement auf eine vorherige Revision wieder her. Ersetzt den aktuellen Entwurf durch die Daten der angegebenen Revision. Wird nicht automatisch veröffentlicht — verwenden Sie bei Bedarf anschließend content_publish.

Scope: content:write

Einstellungs-Tools

Seitenweite Einstellungen — Titel, Untertitel, Logo, Favicon, kanonische URL, Standard-Seitengröße, Datums- und Zeitformatierung, Social-Media-Handles und SEO-Standards.

settings_get

Ruft alle seitenweiten Einstellungen ab. Medienreferenzen (logo, favicon, seo.defaultOgImage) enthalten aufgelöste URLs neben der zugrunde liegenden mediaId. Nicht gesetzte Werte werden aus der Antwort weggelassen.

Keine Parameter.

Scope: settings:read | Mindestrolle: Editor | Nur-Lesen: Ja

settings_update

Aktualisiert eine oder mehrere seitenweite Einstellungen. Teilaktualisierung: Nur die angegebenen Felder werden geändert; weggelassene Felder bleiben unverändert. Gibt das vollständige Einstellungsobjekt nach der Aktualisierung zurück.

Um eine Medienreferenz (logo, favicon, seo.defaultOgImage) zu setzen, übergeben Sie ein Objekt mit mediaId (und optionalem alt). Das Medienelement muss bereits existieren — verwenden Sie zuerst media_create.

Das seo-Objekt akzeptiert:

Scope: settings:manage | Mindestrolle: Admin

OAuth-Discovery

Die meisten MCP-Clients handhaben dies automatisch; dieser Abschnitt ist für den direkten Aufbau eines MCP-Clients gegen EmDash. Clients, die OAuth 2.1 unterstützen, entdecken die Authentifizierungsmethode aus zwei Metadatendokumenten, die der Server veröffentlicht:

Metadaten der geschützten Ressource

Fordern Sie die Metadaten der geschützten Ressource am folgenden Endpunkt an:

GET /.well-known/oauth-protected-resource

Der Server antwortet mit dem Ressourcenbezeichner, seinem Autorisierungsserver und unterstützten Scopes:

{
  "resource": "https://example.com/_emdash/api/mcp",
  "authorization_servers": ["https://example.com/_emdash"],
  "scopes_supported": [
    "content:read", "content:write",
    "media:read", "media:write",
    "schema:read", "schema:write",
    "taxonomies:manage", "menus:manage",
    "settings:read", "settings:manage",
    "admin"
  ],
  "bearer_methods_supported": ["header"]
}

Autorisierungsserver-Metadaten

Fordern Sie die Autorisierungsserver-Metadaten am folgenden Endpunkt an:

GET /.well-known/oauth-authorization-server/_emdash

Der Server antwortet mit den Endpunkten, Scopes und Grant-Typen, die er unterstützt:

{
  "issuer": "https://example.com/_emdash",
  "authorization_endpoint": "https://example.com/_emdash/oauth/authorize",
  "token_endpoint": "https://example.com/_emdash/api/oauth/token",
  "scopes_supported": ["content:read", "content:write", "..."],
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "device_authorization_endpoint": "https://example.com/_emdash/api/oauth/device/code"
}

Wenn eine nicht authentifizierte Anfrage den MCP-Endpunkt erreicht, gibt der Server zurück:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource"

Dies löst den Standard-MCP-Client-Discovery-Flow aus.

Fehlerbehandlung

Tool-Fehler werden als Textinhalt mit isError: true zurückgegeben. Die Nachricht hat ein stabiles [CODE]-Präfix, und derselbe Code wird in _meta.code wiederholt:

{
  "content": [{ "type": "text", "text": "[NOT_FOUND] Collection 'nonexistent' not found" }],
  "isError": true,
  "_meta": { "code": "NOT_FOUND" }
}

Scope- und Berechtigungsfehler verwenden denselben Tool-Fehler-Umschlag:

{
  "content": [
    { "type": "text", "text": "[INSUFFICIENT_SCOPE] Insufficient scope: requires content:write" }
  ],
  "isError": true,
  "_meta": { "code": "INSUFFICIENT_SCOPE" }
}

Transport-Level-Fehler (Serverkonfigurationsfehler, unbehandelte Ausnahmen) geben den JSON-RPC-Fehlercode -32603 (Interner Fehler) zurück, ohne Implementierungsdetails preiszugeben.