Connecter SMOC avec MCP à Claude ou tout autre client basé sur l’IA

Guide simple montrant comment connecter SMOC à des clients IA et des outils de développement via MCP (Model Context Protocol). Une fois connecté, des outils comme Claude Desktop, Claude Code, Cursor ou VS Code peuvent lire directement vos données SMOC — contacts, entreprises, actifs d'entreprise, organigrammes, analyses de parcours, conversations LinkedIn inbox et conversations de parcours de messages — dans le périmètre de votre entreprise. Les appels HTTP doivent utiliser la référence API REST v2.

Obtenez votre clé API

L'intégration MCP de SMOC s'authentifie avec une clé API privée. Générez-en une dans la console SMOC :

1. Allez dans Paramètres → Intégrations → MCP.
2. Donnez éventuellement un nom à la clé et une date d'expiration (7, 30 ou 90 jours). Laissez l'expiration sur Aucune expiration si vous ne souhaitez pas qu'elle expire.
3. Générez la clé et copiez-la immédiatement — elle n'est affichée qu'une seule fois, donc stockez-la en lieu sûr.

Votre clé est liée à votre entreprise. Chaque requête effectuée avec elle est automatiquement limitée à vos données — vous ne verrez que les contacts, entreprises, analyses, conversations inbox et conversations qui vous appartiennent. Générer une nouvelle clé ne révoque pas les clés existantes. Les clés émises sont listées sur la même page — révoquez les clés inutilisées à cet endroit.

Les pages API et Zapier utilisent le même nom, expiration, bannière de copie unique et liste des clés émises.

Ce à quoi vous pouvez accéder

Après connexion, les outils suivants deviennent disponibles (la disponibilité exacte dépend des permissions de votre compte et des liaisons configurées sur le serveur). Les clés sont en lecture seule par défaut. Cochez Autoriser les écritures limitées lors de la création d'une clé pour activer les écritures listées ci-dessous.

Découverte

• whoami — rôle actuel, périmètre d'entreprise et permissions
• mcp_capabilities — outils visibles, superpouvoirs et tout ce qui est actuellement indisponible
• skills_search — trouver une recette à partir d'une courte phrase de tâche
• skills_get — entrées exactes et exemple pour un superpouvoir

Entreprises & actifs

• companies_get — profil d'entreprise (titre, clé, URL, langues, paramètres)
• company_assets_get — produits, positionnement, liens de site web et fichiers
• company_asset_extraction_results_list — résumés des résultats d'extraction
• company_asset_extraction_results_get — un résultat d'extraction, éventuellement avec données extraites
• company_asset_extraction_templates_list — modèles, tags et fraîcheur

Les clés super-utilisateur peuvent aussi appeler companies_list pour parcourir toutes les entreprises avant de sélectionner un companyId.

Contacts

• contacts_search — recherche avec filtres, tri et pagination
• contacts_get — un contact anonymisé par id
• contacts_get_stats — totaux et résumé d'engagement
• contacts_get_filter_options — valeurs de filtre valides (localisation, parcours, appareil, etc.)
• contact_tags_list — tags de contact
• prospect_lists_list / prospect_lists_get — listes de prospects

Inbox & conversations

• inbox_threads_list — conversations LinkedIn (et autres) inbox, avec filtres non lus / sans réponse / expéditeur / parcours
• inbox_threads_get — une conversation ; définissez includeMessages: true pour inclure les messages récents
• inbox_messages_list — historique des messages pour une conversation, y compris les conversations fusionnées
• conversations_list — exécutions de parcours de messages (inscription, statut, nœud actuel)
• conversations_get — une exécution de conversation, y compris les jalons

Les outils inbox nécessitent la permission inbox:read. Ils peuvent lire les corps des messages. Les clés avec écriture activée peuvent aussi archiver, marquer comme non lu/traité, et envoyer une réponse texte uniquement avec inbox_threads_send (nécessite threadId, body et idempotencyKey). Ils ne peuvent pas joindre de fichiers, éditer des graphes de parcours, publier des parcours ou lancer des campagnes LinkedIn. Les clés super-utilisateur peuvent sauvegarder des brouillons de parcours Mongo et de thèmes (flowcharts_save, flowcharts_create, themes_save et appels associés), y compris les types web/message et chat/parcours en cartes. Ces écritures ne publient pas.

Organigrammes

• flowcharts_list — organigrammes statiques de l'entreprise
• flowcharts_get — résumé ou graphe complet d'un organigramme
• flowchart_recommendations_list — documents de recommandation pour un organigramme
• flowcharts_versions_list, themes_get, studio_generation_categories_list, portefeuilles de ciblage, et lectures de génération/traduction de jobs
• Écritures de brouillons super-utilisateur : flowcharts_save, flowcharts_restore_version, flowcharts_create (flowType web ou message, webFormat chat ou parcours en cartes), flowcharts_duplicate, themes_save. Ces écritures créent des brouillons Mongo et ne publient pas.
• Lectures CPCS : cpcs_overview, URLs, crawls, extractions, modèles, planification

Analyses de parcours

• analytics_flow_list_flows — parcours classés par trafic
• analytics_flow_kpis — totaux, conversion, écarts par rapport à la période précédente
• analytics_flow_timeseries — tendances quotidiennes ou mensuelles
• analytics_flow_dimension_metrics — répartitions par appareil, pays, langue, UTM ou jour de la semaine
• analytics_flow_filter_values — valeurs de filtre d'analyse valides

Les clés client sont toujours limitées à votre propre entreprise. Les clés super-utilisateur peuvent passer companyId sur les outils concernés.

---

Connecter dans Claude (web et desktop)

Ajoutez SMOC comme connecteur personnalisé. Cela fonctionne sur claude.ai et dans l'application Claude Desktop. Vous pouvez vous connecter avec votre compte SMOC, ou avec une clé API.

Démarrage rapide

Point de terminaison MCP : https://api.smoc.ai/mcp

Connexion

1. Dans Claude, ouvrez Personnaliser, puis + Ajouter.
2. Nommez le connecteur SMOC et collez le point de terminaison MCP. Laissez la connexion activée. Ne choisissez pas Pas de connexion et n'ajoutez pas d'en-tête de requête.
3. Lorsque Claude vous demande de vous connecter, connectez-vous avec un compte administrateur d'entreprise.
4. Dans un chat, ouvrez +, choisissez Connecteurs, et activez SMOC. Demandez à Claude d'exécuter whoami.

La connexion est réservée aux administrateurs d'entreprise. Elle peut lire les données de cette entreprise. Les membres et autres rôles sont refusés. Cela n'active pas les écritures limitées que vous choisissez lors de la création d'une clé API. Si vous administrez plusieurs entreprises, utilisez une clé API pour l'entreprise souhaitée.

Sur Team et Enterprise, un Propriétaire ajoute le connecteur dans Paramètres de l'organisation → Connecteurs → + Ajouter → Personnalisé. Les membres l'activent ensuite depuis Personnaliser.

Ou ajouter une clé API

1. Générez une clé API dans Paramètres → Intégrations → MCP et copiez-la.
2. Dans Claude, ouvrez Personnaliser, puis + Ajouter.
3. Nommez le connecteur SMOC et collez le point de terminaison MCP.
4. Choisissez Pas de connexion. Sous En-têtes de requête, sélectionnez authorization et définissez la valeur sur Bearer YOUR_SMOC_API_KEY — incluez le mot Bearer et l'espace. Marquez l'en-tête comme Requis, puis ajoutez le connecteur.

Utilisez une clé si vous souhaitez cibler une entreprise, une expiration ou des écritures limitées. Les en-têtes de requête sont en cours de déploiement. Si + Ajouter n'a pas de section En-têtes de requête, utilisez Claude Code ou le fichier de configuration desktop ci-dessous.

Connecter dans ChatGPT

ChatGPT ajoute SMOC comme application. L'écran de création utilise la connexion et n'a pas de champ pour une clé API. Connectez-vous avec un compte administrateur d'entreprise.

Démarrage rapide

Point de terminaison MCP : https://api.smoc.ai/mcp

1. Ouvrez Paramètres → Applications → Paramètres avancés et activez Mode développeur. Sur Business, Enterprise ou Edu, un administrateur d'espace de travail doit d'abord l'activer dans Paramètres de l'espace de travail → Permissions & Rôles.
2. Ouvrez Applications → Créer. Nommez l'application SMOC et collez le point de terminaison MCP.
3. Choisissez OAuth, puis Analyser les outils. Connectez-vous avec un compte administrateur d'entreprise lorsque ChatGPT le demande, puis cliquez sur Créer.
4. Dans un chat, ouvrez le menu des outils et activez SMOC. Demandez à ChatGPT d'exécuter whoami.

La connexion est réservée aux administrateurs d'entreprise. Elle peut lire les données de cette entreprise. Les membres sont refusés. Les clés API sont pour Claude, Cursor et VS Code. ChatGPT nécessite un plan Plus, Pro, Business, Enterprise ou Edu pour les applications personnalisées.

Connecter Claude Desktop avec un fichier de configuration

Utilisez ceci lorsque la boîte de dialogue du connecteur ne peut pas prendre de clé API. SMOC se connecte alors via un petit pont local (mcp-remote).

1. Ouvrez Claude Desktop → Paramètres → Développeur → Modifier la configuration. Cela ouvre claude_desktop_config.json.
2. Ajoutez SMOC sous mcpServers :

{
  "mcpServers": {
    "smoc": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.smoc.ai/mcp",
        "--header",
        "Authorization: Bearer YOUR_SMOC_API_KEY"
      ]
    }
  }
}

3. Remplacez YOUR_SMOC_API_KEY par la clé que vous avez générée.
4. Enregistrez le fichier et redémarrez Claude Desktop.

SMOC apparaîtra maintenant dans votre liste d'outils. Nécessite Node.js installé (pour npx).

---

Connecter Claude Code

Claude Code peut communiquer directement avec le point de terminaison SMOC via un en-tête d'authentification — pas besoin de pont.

claude mcp add --transport http smoc https://api.smoc.ai/mcp \
  --header "Authorization: Bearer YOUR_SMOC_API_KEY"

Sur Claude Code 2.1.1 et plus récent, vous pouvez aussi l'ajouter en JSON :

claude mcp add-json smoc \
  '{"type":"http","url":"https://api.smoc.ai/mcp","headers":{"Authorization":"Bearer YOUR_SMOC_API_KEY"}}'

Vérifiez la connexion en exécutant /mcp dans une session Claude Code — SMOC devrait apparaître comme connecté avec ses outils listés.

---

Connecter d'autres clients (Cursor, VS Code, Windsurf, etc.)

La plupart des éditeurs compatibles MCP utilisent un fichier de configuration JSON (souvent mcp.json). Ajoutez une entrée serveur HTTP pointant vers le point de terminaison SMOC avec votre clé dans l'en-tête Authorization :

{
  "mcpServers": {
    "smoc": {
      "type": "http",
      "url": "https://api.smoc.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SMOC_API_KEY"
      }
    }
  }
}

Consultez la documentation MCP de votre éditeur pour l'emplacement exact du fichier. Après sauvegarde, redémarrez ou rechargez l'éditeur.

---

Vérifier la connexion

• Vérification de santé : le point de terminaison expose GET https://api.smoc.ai/mcp/health.
• Vérification d'identité : demandez à l'IA d'exécuter l'outil whoami — il retourne l'identité connectée et le périmètre d'entreprise. C'est le moyen le plus rapide de confirmer que la clé fonctionne.

Découverte des outils

L'IA n'a pas besoin de connaître à l'avance les noms des outils SMOC. Le parcours prévu est :

1. mcp_capabilities — liste les outils disponibles, votre rôle et votre périmètre.
2. skills_search — décrivez la tâche en une courte phrase pour trouver le bon outil.
3. skills_get — retourne les entrées exactes et un exemple pour l'outil choisi.
4. Appelez l'outil.

En pratique, vous pouvez simplement demander en langage naturel (ex : "rechercher mes contacts SMOC à Oslo" ou "afficher les conversations LinkedIn inbox sans réponse") et le client choisira le bon outil.

Notes de sécurité

• Votre clé API n'est affichée qu'une seule fois à la création — stockez-la dans un gestionnaire de mots de passe ou une variable d'environnement.
• Ne jamais commettre la clé dans un dépôt Git ou la coller dans une configuration partagée/publique.
• Générer une nouvelle clé ne révoque pas les clés existantes. Révoquez les clés inutilisées depuis la liste des clés émises dans Paramètres → Intégrations → MCP.
• Les clés client sont en lecture seule par défaut et limitées aux données de votre entreprise. Les clés avec écriture activée peuvent mettre à jour les contacts, tags, listes, profil d'entreprise, ajouter des URLs CPCS, trier l'inbox et envoyer des réponses texte dans l'inbox. Elles ne peuvent pas supprimer de données, publier des parcours, activer/désactiver le live ou lancer des campagnes LinkedIn.
• Les outils inbox et conversation nécessitent inbox:read sur la clé. Les nouvelles clés depuis Paramètres → Intégrations → MCP l'incluent ; les anciennes nécessitent une rotation.

Dépannage

• Des outils manquent dans la liste : l'IA peut exécuter mcp_capabilities et vérifier unavailableTools — il nomme exactement la permission manquante dont votre clé a besoin.
• Échec de l'authentification : vérifiez que la clé est correcte, non révoquée, et que l'en-tête est exactement Authorization: Bearer <key>.
• Le dialogue + Ajouter de Claude n'a pas d'en-têtes de requête : utilisez la commande Claude Code ou la configuration mcp-remote ci-dessus. Assurez-vous que Node.js est installé, que le JSON de configuration est valide, et que vous avez bien redémarré Claude Desktop après modification.

Voir aussi

• Référence API REST v2 — chaque appel POST /api/v2/{toolName}
• Connecter SMOC avec l'API REST
• API Contacts publique
• MCP pour Claude, Cursor et VS Code