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 supporte trois méthodes d’authentification :

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

Scopes

Les tokens ont une portée limitée 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. Sur la page de consentement du code d’autorisation, tous les scopes demandés sont sélectionnés par défaut ; l’utilisateur peut retirer des scopes avant approbation mais ne peut pas en ajouter que le client n’a pas demandés. L’octroi effectif est aussi restreint par les scopes enregistrés du client et le rôle de l’utilisateur, et EmDash rejette un octroi vide.

Le scope admin accorde l’accès aux opérations principales, mais pas l’accès MCP des plugins. Les outils de plugins nécessitent toujours mcp:tools ou le scope spécifique au plugin correspondant.

content:write accorde implicitement taxonomies:manage et menus:manage pour que les tokens émis avant la séparation de ces scopes continuent de fonctionner. Les nouveaux tokens devraient 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.

Les outils de plugins utilisent la permission déclarée par leur route sous-jacente. Ils sont absents de tools/list tant qu’un administrateur n’a pas activé la surface MCP de ce plugin. Les noms d’outils utilisent la forme déterministe <pluginId>__<localName>, et les invocations sont enregistrées dans le journal d’audit.

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

Transport

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

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

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

Outils

Le serveur expose des outils dans huit domaines : contenu, schéma, média, recherche, taxonomies, menus, révisions et paramètres. Chaque outil retourne des résultats en contenu texte JSON, ou un message d’erreur avec isError: true en cas d’échec.

Outils de contenu

content_list

Liste les éléments de contenu d’une collection avec filtrage et pagination optionnels.

Scope : content:read | Lecture seule : Oui

content_get

Obtient un élément de contenu unique par ID ou slug. Retourne toutes les valeurs de champs, métadonnées et un token _rev pour la concurrence optimiste.

Scope : content:read | Lecture seule : Oui

content_create

Crée un nouvel élément de contenu. L’objet data doit contenir des valeurs de champs 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

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

Scope : content:write

content_delete

Supprime un élément de contenu de manière réversible en le déplaçant vers la corbeille. Utilisez content_restore pour annuler, ou content_permanent_delete pour le supprimer définitivement.

Scope : content:write | Destructif : Oui

content_restore

Restaure un élément supprimé de manière réversible depuis la corbeille.

Scope : content:write

content_permanent_delete

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

Scope : content:write | Destructif : Oui

content_publish

Publie 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’à re-publication.

Scope : content:write

content_unpublish

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

Scope : content:write

content_schedule

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

Scope : content:write

content_unschedule

Annule une publication précédemment planifiée. L’élément garde 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

Compare la version publiée (en ligne) d’un élément avec son brouillon actuel. Retourne les deux versions et un indicateur de changements.

Scope : content:read | Lecture seule : Oui

content_discard_draft

Abandonne le brouillon actuel et revient à la dernière version publiée. Ne fonctionne que sur des éléments publiés au moins une fois.

Scope : content:write | Destructif : Oui

content_list_trashed

Liste les éléments supprimés de manière réversible dans la corbeille d’une collection.

Scope : content:read | Lecture seule : Oui

content_duplicate

Crée une copie d’un élément existant. Le doublon est créé comme brouillon avec « (Copie) » ajouté au titre et un slug auto-généré.

Scope : content:write

content_translations

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

Scope : content:read | Lecture seule : Oui

Outils de schéma

schema_list_collections

Liste toutes les collections de contenu définies dans le CMS.

Aucun paramètre.

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

schema_get_collection

Obtient des informations détaillées sur une collection y compris toutes les définitions de champs.

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

schema_create_collection

Crée une nouvelle collection de contenu. Crée une table de base de données et une définition de schéma.

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

schema_delete_collection

Supprime une collection et sa table de base de données. Irréversible et supprime tout le contenu.

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

schema_create_field

Ajoute un nouveau champ au schéma d’une collection.

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

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

schema_delete_field

Supprime un champ d’une collection. Supprime la colonne et toutes les données. Irréversible.

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

Outils média

media_list

Liste les fichiers média uploadés avec filtrage optionnel par type MIME et pagination.

Scope : media:read | Lecture seule : Oui

media_upload

Upload un fichier média depuis des données encodées en base64 ou une URL externe et l’enregistre dans la bibliothèque de médias.

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

media_create

Enregistre un fichier média déjà uploadé dans le stockage.

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

media_get

Obtient les détails d’un fichier média par ID.

Scope : media:read | Lecture seule : Oui

media_update

Met à jour les métadonnées d’un fichier média. Le fichier lui-même ne peut pas être changé.

Scope : media:write

media_delete

Supprime définitivement un fichier média.

Scope : media:write | Destructif : Oui

media_usage_repair

Répare les index d’utilisation de médias dans le contenu pour une collection ou toutes les collections.

Scope : admin | Rôle minimum : Admin

Outil de recherche

search

Recherche plein texte dans les collections de contenu.

Scope : content:read | Lecture seule : Oui

Outils de taxonomie

taxonomy_list

Liste toutes les définitions de taxonomie.

Aucun paramètre.

Scope : content:read | Lecture seule : Oui

taxonomy_list_terms

Liste les termes d’une taxonomie avec pagination.

Scope : content:read | Lecture seule : Oui

taxonomy_create_term

Crée un nouveau terme dans une taxonomie.

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

taxonomy_update_term

Met à jour un terme existant dans une taxonomie.

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

taxonomy_delete_term

Supprime définitivement un terme d’une taxonomie.

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

Outils de menu

menu_list

Liste les menus de navigation.

Scope : content:read | Lecture seule : Oui

menu_get

Obtient un menu par nom avec tous ses éléments dans l’ordre.

Scope : content:read | Lecture seule : Oui

menu_create

Crée un nouveau menu de navigation.

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

menu_update

Met à jour le label d’un menu.

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

menu_delete

Supprime un menu et tous ses éléments. Irréversible.

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

menu_set_items

Remplace la liste complète des éléments d’un menu en un seul appel. Atomique.

Chaque MenuItem a :

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

Outils de révision

revision_list

Liste l’historique des révisions d’un élément, plus récente en premier.

Scope : content:read | Lecture seule : Oui

revision_restore

Restaure un élément à une révision précédente. N’est pas automatiquement publié — utilisez content_publish ensuite 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 SEO par défaut.

settings_get

Obtient tous les paramètres du site.

Aucun paramètre.

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

settings_update

Met à jour un ou plusieurs paramètres du site. Mise à jour partielle.

L’objet seo accepte :

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

Découverte OAuth

La plupart des clients MCP gèrent cela automatiquement ; cette section est pour construire un client MCP directement contre EmDash.

Métadonnées de la ressource protégée

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

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

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

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

Quand une requête non authentifiée atteint le point de terminaison MCP :

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

Gestion des erreurs

Les erreurs d’outils sont retournées comme contenu texte avec isError: true. Le message est préfixé d’un [CODE] stable :

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

Les erreurs de scope et de permission utilisent la même enveloppe :

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

Les erreurs au niveau du transport retournent le code d’erreur JSON-RPC -32603 (Erreur interne) sans divulguer les détails d’implémentation.