Serveur MCP Humind

Connectez Claude, ou tout agent IA compatible MCP, directement à votre boutique Humind. Un seul endpoint, votre clé API existante, et un agent peut lire vos settings, récupérer l'analytics, chercher dans les conversations, gérer votre base de connaissances et parcourir votre catalogue : les mêmes opérations que celles disponibles via l'API REST publique, exposées comme des tools qu'un LLM peut appeler.

Qu'est-ce que MCP ?

Model Context Protocol est un standard ouvert pour connecter des applications IA à des outils et données externes. Si vous utilisez déjà Claude Code, Claude Desktop, ou un autre client MCP, ajouter Humind suit le même flow "ajouter un serveur" que pour n'importe quelle autre intégration.

Endpoint

https://api.thehumind.com/public/mcp

• Transport : Streamable HTTP.
• Modèle de session : stateless. Chaque requête est autonome, il n'y a pas de session à maintenir ou reconnecter. Seul POST est supporté ; GET/DELETE (les verbes de gestion de session de la spec) renvoient 405.
• Auth : exactement la même clé API Bearer hmd_* que vous utilisez pour l'API REST. Pas de credential MCP séparé à générer.

Authentification

Générez une clé depuis votre dashboard sur Settings → Developer → Credentials, exactement comme décrit dans Authentication. Passez-la comme un bearer token standard :

Authorization: Bearer hmd_live_aB3xK9qLm2pR7sT5wY8zN1_4f7c2e9a

Il n'y a rien de spécifique à MCP dans le credential : la même clé que vous utilisez pour curl /public/v1/products fonctionne ici.

Le catalogue de tools

Dix-sept tools, groupés selon les mêmes scopes que l'API REST. Un tool n'apparaît dans tools/list que si votre clé possède le scope requis : le catalogue s'adapte automatiquement, donc un agent connecté avec une clé read-only ne voit même jamais update_settings ou upsert_knowledge comme option, plutôt que de le voir et de recevoir un 403.

Tool	Scope requis	Ce qu'il fait
get_store_overview	(aucun, toute clé valide)	Nom de la company, locales configurées, devise/pays par défaut, les scopes accordés à cette clé, des compteurs en direct (produits, documents de connaissance, conversations), la dernière sync catalogue, et si le widget est installé.
get_setup_status	(aucun, toute clé valide)	Checklist d'onboarding de la boutique : quelles étapes de configuration sont faites et, pour chaque étape restante, l'action suggérée, y compris le tool MCP qui peut la compléter.
search_docs	(aucun, toute clé valide)	Recherche par mots-clés dans cette documentation développeur (guides, référence API, dépannage), en anglais ou en français.
get_doc_page	(aucun, toute clé valide)	Le markdown complet d'une page de documentation, par le chemin renvoyé par search_docs.
list_settings	settings:read	Valeur actuelle de chaque setting marchand.
get_settings_schema	settings:read	Le contrat machine-readable de chaque setting (clé, type, bornes) ; à appeler avant update_settings.
update_settings	settings:write	Mettre à jour un ou plusieurs settings en un seul appel all-or-nothing.
search_conversations	conversations:read	Lister ou chercher en texte libre dans les conversations visiteur, avec les mêmes filtres que l'endpoint REST.
get_conversation	conversations:read	Transcription complète d'une conversation, avec optionnellement le contact identifié.
get_kpis	analytics:read	Métriques clés sur une période, avec tendance.
get_top_questions	analytics:read	Questions visiteur groupées : volume, tendance, taux de non-réponse.
list_products	catalog:read	Produits du catalogue, paginés.
get_product	catalog:read	Un produit avec ses variants, traductions, images.
list_knowledge	knowledge:read	Documents de la base de connaissances sur lesquels l'IA ancre ses réponses.
get_knowledge	knowledge:read	Un document de connaissance avec son contenu complet.
upsert_knowledge	knowledge:write	Créer ou mettre à jour un document de connaissance par external_id.
delete_knowledge	knowledge:write	Archiver (défaut) ou supprimer définitivement un document de connaissance.

Cette documentation fait partie du serveur

Un agent connecté au serveur MCP n'a pas besoin de parcourir ce site : search_docs et get_doc_page servent ces pages mêmes (dans les deux langues) directement comme tools, il peut donc répondre à « comment j'installe le widget ? » ou « que couvre ce scope ? » depuis la source officielle. Le markdown brut derrière ces tools est aussi public, sur /raw/index.json et /llms.txt, pour tout autre outillage IA que vous utilisez. Ce site est l'unique source de vérité : le serveur MCP lit les pages publiées à l'exécution (avec un cache serveur d'environ une heure), donc ce que les tools servent est toujours cette documentation, avec au plus une heure de décalage.

Chaque appel passe par l'API documentée

Chaque tool délègue exactement au même controller, à la même validation et au même scoping tenant que son équivalent REST : mêmes DTOs, même audit log. Lire le comportement d'un tool dans la référence API vous dit exactement ce que fait le tool ; il n'y a pas de logique séparée propre à MCP à apprendre.

Forme des arguments

Chaque tool publie son schéma d'input exact dans tools/list, et une mauvaise tentative renvoie une erreur de validation qui liste ce qui était attendu : un agent se corrige donc toujours tout seul. Mais quatre formes sont faciles à deviner de travers au premier appel ; les passer correctement économise un aller-retour :

• upsert_knowledge prend le document enveloppé dans un objet document, pas des champs à plat :

{ "document": { "external_id": "faq-retours", "type": "snippet", "title": "Politique de retour", "content": "Les retours sont acceptés sous 30 jours." } }

• get_knowledge et delete_knowledge prennent document_id (un id Humind ou api:<external_id>), pas knowledge_id :

{ "document_id": "api:faq-retours" }

• get_kpis prend un enum period (today, 7_days, 30_days, 90_days, year, total, ou custom avec start_date / end_date), comme l'endpoint REST :

{ "period": "30_days" }

• get_top_questions prend des start_date et end_date explicites (YYYY-MM-DD) ; il n'y a pas de raccourci period :

{ "start_date": "2026-06-29", "end_date": "2026-07-29" }

Connecter un client

Claude Code

claude mcp add --transport http humind https://api.thehumind.com/public/mcp \
  --header "Authorization: Bearer hmd_live_aB3xK9qLm2pR7sT5wY8zN1_4f7c2e9a"

Client MCP générique (config JSON)

Tout client qui lit un bloc mcpServers standard (Claude Desktop, et la plupart des autres hosts MCP) accepte :

{
  "mcpServers": {
    "humind": {
      "type": "http",
      "url": "https://api.thehumind.com/public/mcp",
      "headers": {
        "Authorization": "Bearer hmd_live_aB3xK9qLm2pR7sT5wY8zN1_4f7c2e9a"
      }
    }
  }
}

claude.ai

Si votre plan claude.ai supporte les connecteurs custom, ajoutez-en un pointant vers l'endpoint ci-dessus avec le header Authorization réglé sur votre clé. L'URL et le header suffisent à tout client compatible ; vérifiez les settings de connecteur de votre plan pour savoir où les saisir.

Traitez la clé comme un mot de passe

Partout où vous collez votre clé API (un fichier de config client, une variable d'environnement, un setting de connecteur claude.ai), traitez-la exactement comme vous le feriez dans une intégration REST. Ne la commitez jamais dans un repo et ne la partagez jamais hors de votre secret store. Voir Si une clé fuite.

Bonnes pratiques

• Créez une clé dédiée pour la connexion MCP, séparée de celle utilisée par votre backend ou votre CI. Si un agent se comporte mal ou qu'un client est compromis, vous révoquez une clé sans toucher à votre intégration de production.
• Scopez-la au minimum dont l'agent a besoin. Un agent qui ne fait que lire l'analytics et répondre à des questions "comment se porte la boutique" n'a besoin que de analytics:read, rien de plus ; il ne devrait pas détenir knowledge:write ou settings:write par précaution. Rappel : les scopes sont immuables après création, choisissez étroit, et créez une nouvelle clé plus tard si vous avez besoin de plus.
• Révoquez-la de la même façon que n'importe quelle autre clé : depuis Settings → Developer → Credentials dans votre dashboard. La révocation atteint l'edge de l'API en au plus 60 secondes.

Suite

• Authentication : générer et gérer la clé que vous utiliserez ici.
• Settings : la surface REST derrière list_settings / update_settings.
• Analytics : la surface REST derrière get_kpis / get_top_questions.
• Conversations : la surface REST derrière search_conversations / get_conversation.