Version de développement

Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.

Serveur MCP de Dodock

Connecter un agent IA ou un client MCP au serveur MCP intégré à Dodock, pour lire et modifier des documents avec les permissions de l'utilisateur connecté.

Serveur MCP de Dodock

Dodock contient un serveur MCP (Model Context Protocol) à l'adresse /api/v2/mcp de chaque site. Un agent IA ou un client compatible MCP peut l'utiliser pour découvrir les types de documents, lire et modifier des documents et appeler des méthodes autorisées. Il travaille avec les permissions de l'utilisateur connecté.

Ce serveur ne demande pas d'application supplémentaire.

Ne confondez pas les serveurs MCP de Dokos :

Le serveur MCP de Dodock, décrit sur cette page. Il fait partie de Dodock.
La passerelle MCP de Dokos AI, utilisée par Dokos Connect. Elle demande l'application Dokos AI.
Les serveurs MCP externes que vous déclarez pour l'assistant. Voir Connecter des outils externes à l'assistant.
Dokos CLI, l'outil en ligne de commande qui contient aussi un serveur MCP. Voir Piloter Dokos depuis un assistant externe.

Prérequis

Le rôle System Manager, pour régler ou désactiver le serveur.
Un utilisateur du bureau (rôle Desk User) pour l'agent. Le serveur refuse les autres utilisateurs.
Des clés d'API de cet utilisateur, ou un jeton OAuth.
Un client compatible MCP, par exemple Claude Desktop ou Claude Code.

Régler le serveur

Le serveur est activé par défaut, aussi sur les sites mis à jour. Si vous le désactivez, l'adresse /api/v2/mcp répond « introuvable » (404).

Les libellés de cette section ne sont pas encore traduits : ils s'affichent en anglais.

Ouvrez Paramètres Système.
Ouvrez l'onglet AI Agents.
Dans la section MCP Settings, remplissez les champs :

Champ	Rôle
Enable MCP	Active le serveur. Cochée par défaut. Décochez-la pour désactiver le serveur sur ce site.
Server Name	Le nom affiché aux clients IA. Vide, il est calculé à partir du nom d'hôte du site (`erp.example.com` devient `erp_example_com`).
Agent Instructions	Un texte qui décrit l'usage du site. Le serveur l'envoie aux agents à la connexion, après ses propres instructions (adresse du site, utilisateur connecté, applications installées). Ce texte ne change pas les permissions. Exemple fictif : « Site de gestion de Dokompany, distributeur de matériel de bureau. Les devis sont en euros. »

Enregistrez.

L'adresse du serveur est https://votre-site.fr/api/v2/mcp.

Connecter un client MCP

Le client envoie ses requêtes en POST, au format JSON, à l'adresse du serveur. Il s'authentifie avec l'en-tête Authorization :

avec des clés d'API : token <clé d'API>:<secret>. Générez les clés dans la section Accès API de l'utilisateur de l'agent ;
avec OAuth : Bearer <jeton>. Le client ouvre la page de connexion du site et vous demande d'autoriser l'accès.

Exemple avec Claude Code :

claude mcp add-json --scope user dokos \
  '{"type":"http","url":"https://votre-site.fr/api/v2/mcp","headers":{"Authorization":"token <clé d'API>:<secret>"}}'

Ne mettez jamais ces identifiants dans un dépôt de code.

Outils disponibles

Le serveur propose 13 outils. Leurs arguments suivent les conventions de l'API REST v2 (filters, fields, order_by…).

Groupe	Outils
Découverte	`search_doctypes`, `get_doctype_schema`, `search_methods`, `get_method_schema`, `list_document_methods`
Documents	`list_documents`, `get_document`, `count_documents`, `create_document`, `update_document`, `delete_document`
Méthodes	`call_method` (méthode autorisée `@frappe.whitelist`), `call_document_method` (méthode autorisée d'un document, par exemple `submit`)

API de découverte

Une API de découverte complète le serveur MCP. Elle permet à un client API d'explorer les méthodes disponibles.

Adresse	Description
`GET /api/v2/discovery`	Vue d'ensemble des ressources de découverte
`GET /api/v2/discovery/search?q={query}`	Recherche dans l'index des méthodes
`GET /api/v2/discovery/method`	Liste des méthodes autorisées
`GET /api/v2/discovery/method/{method}`	Détail d'une méthode
`GET /api/v2/discovery/doctype/{doctype}`	Méthodes des documents d'un type
`GET /api/v2/discovery/doctype/{doctype}/method/{method}`	Détail d'une méthode de document

Le code source d'une méthode est montré seulement si son application active le hook expose_discovery_source.

Permissions

La lecture et l'écriture de documents suivent les permissions habituelles de l'utilisateur connecté.
Un utilisateur du bureau peut voir les schémas et les méthodes, même celles qu'il ne peut pas lire ni appeler.
Les méthodes autorisées font leurs propres contrôles de permission.
Le serveur refuse une requête qui vient d'une autre origine (en-tête Origin), sauf si le site l'autorise dans allow_cors.

Dépannage

Réponse	Vérification
`404`	Le serveur n'est pas activé (Enable MCP), ou l'adresse est fausse.
`405`	La requête n'est pas un `POST`. Une adresse ouverte dans un navigateur envoie un `GET`.
`401`	Les identifiants ou l'en-tête `Authorization` sont absents ou faux.
`403`	L'utilisateur n'est pas un utilisateur du bureau, ou l'origine de la requête n'est pas autorisée.
`406` / `415`	Envoyez `Content-Type: application/json` et acceptez `application/json` dans `Accept`.