Référence du Serveur MCP

EmDash inclut un serveur Model Context Protocol (MCP) intégré à /_emdash/api/mcp qui expose les opérations de gestion de contenu comme outils pour les assistants IA.

Cette page couvre les détails du protocole : authentification, transport, spécifications des outils, découverte OAuth et gestion des erreurs.

Authentification

Le serveur MCP prend en charge trois méthodes d’authentification :

Les cookies de session (de l’interface d’administration) fonctionnent également mais ne sont pas pratiques pour les clients MCP externes.

Scopes

Les tokens sont limités à des scopes pour restreindre les opérations qu’un client peut effectuer. Les scopes sont demandés lors de l’autorisation OAuth et appliqués à chaque appel d’outil.

Le scope admin donne accès à tout. L’authentification basée sur la session (sans token) a également un accès complet basé sur le rôle de l’utilisateur.

content:write accorde implicitement taxonomies:manage et menus:manage afin que les tokens d’accès personnel émis avant la séparation de ces scopes continuent de fonctionner sans réémission. Les nouveaux tokens doivent demander les scopes granulaires.

Exigences de Rôle

En plus des scopes, certains outils nécessitent un rôle RBAC minimum. Les deux doivent être satisfaits — un token avec le bon scope échoue quand même si le rôle de l’utilisateur appelant est trop bas.

Consultez le guide d’Authentification pour les définitions de rôles.

Transport

Le serveur utilise le transport HTTP diffusable en mode sans état. Chaque requête est indépendante — il n’y a pas de sessions ni de connexions de longue durée.

• POST /_emdash/api/mcp — Envoyer des appels d’outils JSON-RPC
• GET /_emdash/api/mcp — Renvoie 405 (pas de SSE en mode sans état)
• DELETE /_emdash/api/mcp — Renvoie 405 (pas de session à fermer)

Les réponses suivent le format JSON-RPC 2.0. Les erreurs utilisent des codes d’erreur JSON-RPC standard, avec des codes spécifiques MCP pour les échecs de scope et de permissions.

Outils

Le serveur expose 45 outils répartis sur huit domaines : contenu, schéma, médias, recherche, taxonomies, menus, révisions et paramètres. Chaque outil renvoie des résultats sous forme de contenu texte JSON, ou un message d’erreur avec isError: true en cas d’échec.

Outils de Contenu

content_list

Lister les éléments de contenu dans une collection avec filtrage et pagination optionnels.

Scope : content:read | Lecture seule : Oui

content_get

Obtenir un seul élément de contenu par ID ou slug. Renvoie toutes les valeurs de champ, les métadonnées et un token _rev pour la concurrence optimiste.

Scope : content:read | Lecture seule : Oui

content_create

Créer un nouvel élément de contenu. L’objet data doit contenir des valeurs de champ correspondant au schéma de la collection — utilisez schema_get_collection pour vérifier quels champs sont disponibles. Les éléments sont créés comme draft par défaut.

Scope : content:write

content_update

Mettre à jour un élément de contenu existant. N’incluez que les champs que vous souhaitez modifier — les champs non spécifiés restent inchangés.

Scope : content:write

content_delete

Supprimer doucement un élément de contenu en le déplaçant dans la corbeille. Utilisez content_restore pour annuler, ou content_permanent_delete pour le supprimer définitivement.

Scope : content:write | Destructif : Oui

content_restore

Restaurer un élément de contenu supprimé doucement depuis la corbeille.

Scope : content:write

content_permanent_delete

Supprimer définitivement et irréversiblement un élément de contenu dans la corbeille. L’élément doit d’abord être dans la corbeille.

Scope : content:write | Destructif : Oui

content_publish

Publier un élément de contenu, le rendant visible sur le site. Crée une révision publiée à partir du brouillon actuel. Les modifications ultérieures créent un nouveau brouillon sans affecter la version en ligne jusqu’à republication.

Scope : content:write

content_unpublish

Rétablir un élément publié au statut de brouillon. Il ne sera plus visible sur le site en ligne mais son contenu est préservé.

Scope : content:write

content_schedule

Planifier un élément de contenu pour publication future. Il sera automatiquement publié à la date/heure spécifiée.

Scope : content:write

content_unschedule

Annuler une publication précédemment planifiée. L’élément conserve son statut actuel ; seul le timestamp scheduledAt est effacé. Idempotent — appeler sur un élément non planifié est un no-op.

Scope : content:write

content_compare

Comparer la version publiée (en ligne) d’un élément de contenu avec son brouillon actuel. Renvoie les deux versions et un drapeau indiquant s’il y a des changements.

Scope : content:read | Lecture seule : Oui

content_discard_draft

Rejeter le brouillon actuel et revenir à la dernière version publiée. Ne fonctionne que sur les éléments qui ont été publiés au moins une fois.

Scope : content:write | Destructif : Oui

content_list_trashed

Lister les éléments de contenu supprimés doucement dans la corbeille d’une collection.

Scope : content:read | Lecture seule : Oui

content_duplicate

Créer une copie d’un élément de contenu existant. Le duplicata est créé comme brouillon avec “(Copy)” ajouté au titre et un slug auto-généré.

Scope : content:write

content_translations

Obtenir toutes les variantes de locale d’un élément de contenu. Renvoie le groupe de traduction et un résumé de chaque version de locale. Pertinent uniquement lorsque i18n est activé.

Scope : content:read | Lecture seule : Oui

Outils de Schéma

schema_list_collections

Lister toutes les collections de contenu définies dans le CMS. Renvoie le slug, le label, les fonctionnalités prises en charge et les timestamps.

Aucun paramètre.

Scope : schema:read | Rôle minimum : Editor | Lecture seule : Oui

schema_get_collection

Obtenir des informations détaillées sur une collection incluant toutes les définitions de champ. Les champs décrivent le modèle de données : nom, type, contraintes et règles de validation. Utilisez ceci pour comprendre ce que content_create et content_update attendent.

Scope : schema:read | Rôle minimum : Editor | Lecture seule : Oui

schema_create_collection

Créer une nouvelle collection de contenu. Cela crée une table de base de données et une définition de schéma. Le slug doit être alphanumérique en minuscules avec des underscores, commençant par une lettre.

Scope : schema:write | Rôle minimum : Admin

schema_delete_collection

Supprimer une collection et sa table de base de données. C’est irréversible et supprime tout le contenu de la collection.

Scope : schema:write | Rôle minimum : Admin | Destructif : Oui

schema_create_field

Ajouter un nouveau champ au schéma d’une collection. Cela ajoute une colonne à la table de base de données.

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

Pour les types select et multiSelect, fournissez les valeurs autorisées dans validation.options.

Scope : schema:write | Rôle minimum : Admin

schema_delete_field

Supprimer un champ d’une collection. Cela supprime la colonne et toutes les données dans ce champ. Irréversible.

Scope : schema:write | Rôle minimum : Admin | Destructif : Oui

Outils Multimédias

media_list

Lister les fichiers multimédias téléchargés avec filtrage optionnel par type MIME et pagination.

Scope : media:read | Lecture seule : Oui

media_create

Enregistrer un fichier multimédia qui a déjà été téléchargé vers le stockage. L’appelant est responsable de placer le fichier à storageKey (typiquement en utilisant une URL de téléchargement signée de l’interface d’administration ou d’une API séparée). Cet outil persiste l’enregistrement de métadonnées pour que le fichier soit découvrable via media_list / media_get et puisse être référencé par du contenu.

Scope : media:write | Rôle minimum : Author

media_get

Obtenir les détails d’un seul fichier multimédia par ID. Renvoie les métadonnées incluant le nom de fichier, le type MIME, la taille, les dimensions, le texte alt et l’URL.

Scope : media:read | Lecture seule : Oui

media_update

Mettre à jour les métadonnées d’un fichier multimédia téléchargé. Le fichier lui-même ne peut pas être modifié.

Scope : media:write

media_delete

Supprimer définitivement un fichier multimédia. Supprime l’enregistrement de base de données et le fichier du stockage. Le contenu référençant ce média aura des références brisées.

Scope : media:write | Destructif : Oui

Outil de Recherche

search

Recherche plein texte à travers les collections de contenu. Les collections doivent avoir search dans leur liste supports et les champs doivent être marqués comme searchable.

Scope : content:read | Lecture seule : Oui

Outils de Taxonomie

taxonomy_list

Lister toutes les définitions de taxonomie (ex. catégories, étiquettes). Renvoie le nom, le label, si hiérarchique et les collections associées.

Aucun paramètre.

Scope : content:read | Lecture seule : Oui

taxonomy_list_terms

Lister les termes dans une taxonomie avec pagination.

Scope : content:read | Lecture seule : Oui

taxonomy_create_term

Créer un nouveau terme dans une taxonomie. Pour les taxonomies hiérarchiques, spécifiez un parentId pour créer un terme enfant. La chaîne d’ancêtres du parent ne doit pas dépasser 100 niveaux.

Scope : taxonomies:manage | Rôle minimum : Editor

taxonomy_update_term

Mettre à jour un terme existant dans une taxonomie. Tout champ peut être omis pour le laisser inchangé. Renommer un slug ne doit pas entrer en collision avec un autre terme dans la même taxonomie. Définir parentId à null pour détacher d’un parent. Le nouveau parent doit exister, appartenir à la même taxonomie et ne pas introduire de cycle.

Scope : taxonomies:manage | Rôle minimum : Editor

taxonomy_delete_term

Supprimer définitivement un terme d’une taxonomie. Tout contenu étiqueté avec le terme perd l’association. Ne peut pas supprimer un terme qui a des enfants — supprimez d’abord les enfants.

Scope : taxonomies:manage | Rôle minimum : Editor | Destructif : Oui

Outils de Menu

menu_list

Lister les menus de navigation. Les menus sont par locale : passez locale pour ne renvoyer que les lignes d’une locale, ou omettez-le pour lister chaque variante de locale.

Scope : content:read | Lecture seule : Oui

menu_get

Obtenir un menu par nom incluant tous ses éléments dans l’ordre. Les éléments ont un label, une URL, un type et un parent optionnel pour l’imbrication. Lorsque le même nom de menu existe dans plusieurs locales, passez locale pour résoudre la traduction prévue.

Scope : content:read | Lecture seule : Oui

menu_create

Créer un nouveau menu de navigation. Le name est l’identifiant stable utilisé par les modèles de site ; label est le nom lisible par l’humain affiché dans l’admin. Les menus sont par locale, donc passez locale lorsque le même nom de menu existe dans plusieurs traductions. Ajoutez des éléments après avec menu_set_items. Si translationOf est défini, locale doit aussi être défini.

Scope : menus:manage | Rôle minimum : Editor

menu_update

Mettre à jour le label d’un menu. Le name (identifiant stable) ne peut pas être changé. Sur les installations multi-locales, passez locale pour que la bonne traduction soit mise à jour.

Scope : menus:manage | Rôle minimum : Editor

menu_delete

Supprimer un menu et tous ses éléments. Ne peut pas être annulé. Sur les installations multi-locales, passez locale pour que seule la traduction prévue soit supprimée.

Scope : menus:manage | Rôle minimum : Editor | Destructif : Oui

menu_set_items

Remplacer la liste complète des éléments d’un menu en un seul appel. Atomique : les éléments existants sont supprimés et la nouvelle liste est insérée dans l’ordre fourni. Utilisez ceci plutôt que des opérations d’ajout/suppression par élément pour que l’ordre résultant et les liens parent soient sans ambiguïté. Sur les installations multi-locales, passez locale pour que seule la traduction prévue soit réécrite.

Les éléments sont positionnés par index de tableau. L’imbrication est exprimée via parentIndex — un élément avec parentIndex: 0 est imbriqué sous l’élément à l’index 0. Le parent doit apparaître plus tôt dans la liste. Les éléments sans parentIndex sont de premier niveau.

Chaque MenuItem a :

Scope : menus:manage | Rôle minimum : Editor

Outils de Révision

revision_list

Lister l’historique de révision pour un élément de contenu, le plus récent en premier. Nécessite que la collection prenne en charge revisions.

Scope : content:read | Lecture seule : Oui

revision_restore

Restaurer un élément de contenu à une révision antérieure. Remplace le brouillon actuel par les données de la révision spécifiée. Non publié automatiquement — utilisez content_publish après si nécessaire.

Scope : content:write

Outils de Paramètres

Paramètres du site — titre, slogan, logo, favicon, URL canonique, taille de page par défaut, formatage de date et heure, identifiants sociaux et valeurs par défaut SEO.

settings_get

Obtenir tous les paramètres du site. Les références multimédias (logo, favicon, seo.defaultOgImage) incluent des URLs résolues à côté de la mediaId sous-jacente. Les valeurs non définies sont omises de la réponse.

Aucun paramètre.

Scope : settings:read | Rôle minimum : Editor | Lecture seule : Oui

settings_update

Mettre à jour un ou plusieurs paramètres du site. Mise à jour partielle : seuls les champs fournis sont modifiés ; les champs omis sont laissés tels quels. Renvoie l’objet de paramètres complet après la mise à jour.

Pour définir une référence multimédia (logo, favicon, seo.defaultOgImage), passez un objet avec mediaId (et alt optionnel). L’élément multimédia doit déjà exister — utilisez d’abord media_create.

L’objet seo accepte :

Scope : settings:manage | Rôle minimum : Admin

Découverte OAuth

La plupart des clients MCP gèrent cela pour vous ; cette section est pour construire un client MCP contre EmDash directement. Les clients qui prennent en charge OAuth 2.1 découvrent comment s’authentifier à partir de deux documents de métadonnées que le serveur publie :

Métadonnées de Ressource Protégée

Demandez les métadonnées de ressource protégée au point de terminaison suivant :

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

Le serveur répond avec l’identifiant de ressource, son serveur d’autorisation et les scopes pris en charge :

{
  "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"]
}

Métadonnées du Serveur d’Autorisation

Demandez les métadonnées du serveur d’autorisation au point de terminaison suivant :

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

Le serveur répond avec les points de terminaison, les scopes et les types de grant qu’il prend en charge :

{
  "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"
}

Lorsqu’une requête non authentifiée atteint le point de terminaison MCP, le serveur renvoie :

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

Cela déclenche le flux de découverte standard du client MCP.

Gestion des Erreurs

Les erreurs d’outil sont renvoyées sous forme de contenu texte avec isError: true. Le message est préfixé avec un [CODE] stable, et le même code est répété dans _meta.code :

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

Les erreurs de scope et de permissions utilisent la même enveloppe d’erreur d’outil :

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

Les erreurs au niveau transport (mauvaise configuration du serveur, exceptions non gérées) renvoient le code d’erreur JSON-RPC -32603 (Internal error) sans divulguer les détails d’implémentation.