MCP Datactive — Référence des 14 tools

Authentification

Toutes les requêtes MCP requièrent un header Authorization: Bearer <clé>. La clé est générée par chaque utilisateur depuis son espace Datactive (Paramètres → API Keys → Générer). Le système hérite des droits du compte ; un admin a un wildcard sur tous les scopes.

Système de crédits

Chaque appel consomme des crédits débités de credit_balances.credits_used. Solde calculé : credits_total + credits_bonus - credits_used. Coûts indicatifs : 0 crédit pour les métadonnées (plans, balance, campagnes), 1 crédit pour les recherches, 2 crédits pour les profils détaillés.

1. suggest_companies 0 crédit companies:read

Trouver rapidement le SIREN d'une entreprise dont l'utilisateur tape les premiers caractères du nom. Idéal pour résoudre une mention floue avant un drill-down.

Paramètres

Sortie observée

{
  "suggestions": [
    { "siren": "380129866", "denomination": "ORANGE", "ville": "ISSY-LES-MOULINEAUX" },
    { "siren": "384044640", "denomination": "ORANGE", "ville": "PARIS" }
  ]
}

2. search_companies 1 crédit companies:read

Recherche structurée dans les 29 millions d'entreprises SIRENE par dénomination, géographie, code NAF, finances. Au moins un critère requis.

Paramètres (tous optionnels, ≥1 requis)

Sortie observée (denomination=orange, limit=3)

{
  "total": 5115, "count": 3, "limit": 3, "offset": 0,
  "resultats": [
    {
      "siren": "013643192",
      "denomination": "SYNDIC COPROPR RESIDENCE DE L ORANGERIE",
      "activite_principale": "81.10Z",
      "activite_principale_libelle": "Activités combinées de soutien lié aux bâtiments",
      "categorie_juridique": "9110",
      "forme_juridique_libelle": "Syndicat de copropriete",
      "categorie_entreprise": "PME",
      "tranche_effectif_salarie": "01",
      "etat_administratif": "A",
      "date_creation": "1994-12-24T23:00:00.000Z",
      "code_postal": "49300", "commune": "CHOLET",
      "departement": "49", "region": "Pays de la Loire",
      "tva_intracommunautaire": "FR50013643192"
    }
  ]
}

3. get_company_profile 2 crédits companies:read

Rapatrier en un appel l'intégralité de ce que Datactive sait sur une entreprise : identité légale, adresse, dirigeants actifs, dernier bilan, scoring.

Paramètres

Sortie observée (siren=380129866)

{
  "siren": "380129866",
  "identite": {
    "siren": "380129866",
    "tva_intracommunautaire": "FR89380129866",
    "denomination": "ORANGE",
    "forme_juridique": "5599",
    "code_postal": "92130",
    "commune": "ISSY-LES-MOULINEAUX",
    "departement": "92",
    "region": "Ile-de-France"
  },
  "dirigeants": {
    "nb_actifs": 20, "nb_anciens": 0,
    "actifs": [
      {"type_personne":"PP","nom":"CHATELIER","prenoms":"THIERRY","role":"99","actif":1}
    ]
  },
  "dernier_bilan": { /* CA, résultat, effectif, date */ },
  "scoring": { /* indicateurs Datactive */ }
}

4. get_legal_announcements 1 crédit companies:read

Annonces officielles BODACC pour un SIREN — créations, modifications de capital, changements de dirigeants, défaillances, radiations.

5. search_executives 1 crédit executive:read

Retrouver tous les dirigeants français (registre INPI/RNE) correspondant à des critères : nom, prénom, société dirigée, rôle, géographie, âge.

Sortie observée (nom=macron, limit=3)

{
  "total": 432, "count": 218, "limit": 3, "offset": 0,
  "dirigeants": [
    {
      "nom": "MACRON",
      "prenoms": "ARNAUD BERNARD JOSEPH",
      "date_naissance": "1965-01",
      "age": 61, "pays": "FRANCE",
      "mandats": [
        {
          "siren": "327528501",
          "denomination": "SCI DU QUAI",
          "role_libelle": "Entrepreneur individuel",
          "forme_juridique": "6540",
          "code_postal": "75116", "commune": "Paris",
          "actif": 1, "source": "rne",
          "capital": 1524.49, "etat_administratif": "A"
        }
      ]
    }
  ]
}

6. get_executive_profile 1 crédit executive:read

Identité unique consolidée d'un dirigeant à partir de nom (+ prénom et/ou date de naissance pour précision). Sans les mandats — utiliser list_executive_mandates pour ceux-ci.

Sortie observée (nom=macron, prenom=emmanuel)

{
  "total": 1,
  "identites": [
    {
      "id": 10546535,
      "nom": "MACRON", "prenoms": "EMMANUEL",
      "date_naissance": "1977-12",
      "nb_mandats": 1, "nb_entreprises": 1,
      "confiance": "haute"
    }
  ]
}

7. list_executive_mandates 1 crédit executive:read

Mandats actuels et passés d'une personne identifiée — détail des sociétés où elle a un rôle.

Sortie observée

{
  "total_resultats": 1, "nb_personnes": 1,
  "personnes": [
    {
      "nom": "MACRON", "prenoms": "EMMANUEL",
      "date_naissance": "1977-12", "age": 48,
      "nb_mandats": 1, "nb_mandats_actifs": 1,
      "mandats": [
        {
          "siren": "940771702",
          "denomination": "BREMSELATI",
          "forme_juridique": "6540",
          "role": "75", "actif": true,
          "localisation": "75008 Paris"
        }
      ]
    }
  ]
}

8. search_contacts 1 crédit contact:read

Recherche dans les 4,5 M+ contacts B2B enrichis (Apollo / Explorium) par société, poste, niveau hiérarchique, géographie. Retourne emails et téléphones quand disponibles.

Sortie observée (company_name=orange, limit=3)

{
  "total": 1312717, "page": 1, "limit": 3, "pages": 437573,
  "employees": [
    {
      "id": 3070002,
      "full_name": "_ Optimachines",
      "job_title": "Technico-commercial",
      "management_level": "entry",
      "department_type": "sales",
      "siren": "441620580",
      "company_name": "OPTIMACHINES",
      "naf_code": "46.62Z",
      "naf_libelle": "Commerce de gros (...) machines-outils",
      "dept_geo": "59",
      "primary_email": null,
      "has_email": 0, "has_phone": 0,
      "linkedin_url": null
    }
  ]
}

9. get_contact_profile 2 crédits contact:read

Toutes les coordonnées, l'historique d'enrichissement, la classification IA du poste et l'entreprise associée pour un contact_id.

Sortie observée (contact_id=1)

{
  "contact": {
    "id": 1,
    "siren": "423302421",
    "first_name": "jean-gabriel", "last_name": "schoenhenz",
    "linkedin_url": "https://linkedin.com/in/jean-gabriel-schoenhenz-91583bba",
    "job_title_raw": "quality director",
    "job_title_classified": "Directeur - Opérations",
    "management_level": "director",
    "department": "operations",
    "classification_confidence": 90,
    "classification_version": "v1.0-apollo",
    "location_region": "Auvergne-Rhone-Alpes",
    "source_provider_code": "explorium",
    "enrichment_status": "complete"
  },
  "emails": [
    { "email": "jean-gabriel.schoenhenz@arturia.com", "validation_status": "valid" }
  ],
  "email_sources": [ /* historique fournisseurs */ ],
  "phones": [ /* numéros si dispo */ ],
  "enrichments": [ /* historique multi-sources */ ]
}

10. list_campaigns 0 crédit campaign:read

Lister les campagnes (email + SMS) configurées par l'utilisateur authentifié.

Sortie observée

{
  "campaigns": [
    {
      "id": 5,
      "user_id": 1,
      "nom": "Test SMS Reel - Sprint 7",
      "type_canal": "sms",
      "statut": "",
      "total_destinataires": 2,
      "total_emails_valides": 0,
      "date_envoi_effective": "2026-04-05T12:54:26.000Z",
      "sms_text": "Bonjour {nom}, decouvrez Datactive...",
      "nb_destinataires": 2,
      "nb_emails": 2,
      "nb_emails_valides": 0
    }
  ]
}

11. get_campaign 0 crédit campaign:read

Configuration complète, segment ciblé, statistiques destinataires pour une campagne.

Sortie observée (campaign_id=5)

{
  "campaign": {
    "id": 5,
    "nom": "Test SMS Reel - Sprint 7",
    "type_canal": "sms",
    "stats_destinataires": { "total": 2, "with_email": "2", "valid_email": null },
    "messages": [],
    "events": []
  }
}

12. get_campaign_analytics 0 crédit campaign:read

Taille du segment, qualité des emails, événements récents (ouvertures, clics, désabos) d'une campagne.

Sortie observée

{
  "campaign_id": 5,
  "nom": "Test SMS Reel - Sprint 7",
  "statut": "",
  "type_canal": "sms",
  "destinataires": {
    "total": 2, "with_email": 2, "valid_email": 0,
    "email_quality_rate": 0
  },
  "nb_messages_versions": 0,
  "derniers_evenements": [],
  "note": "Métriques d'envoi (opens/clicks/bounces) disponibles via veille_envois_log côté admin."
}

13. list_plans 0 crédit

Plans tarifaires actifs (abonnements mensuels + packs ponctuels) avec leurs caractéristiques.

Aucun paramètre.

Sortie observée (7 plans)

{
  "plans": [
    {
      "code": "free",
      "label": "Découverte",
      "description": "Accès gratuit avec crédits limités",
      "credits_monthly": 100,
      "credits_included": 0,
      "price_monthly_eur": 0,
      "price_yearly_eur": null,
      "max_users": 1,
      "features": ["recherche", "veille_basique"]
    },
    {
      "code": "starter", "label": "Starter",
      "credits_monthly": 2000, "price_monthly_eur": 29, "price_yearly_eur": 290,
      "max_users": 2,
      "features": ["recherche", "veille", "export", "siretisation"]
    },
    {
      "code": "pro", "label": "Professionnel",
      "credits_monthly": 10000, "price_monthly_eur": 79, "price_yearly_eur": 790,
      "max_users": 5,
      "features": ["recherche", "veille", "export", "siretisation", "geocodage", "api", "lookalike"]
    },
    {
      "code": "enterprise", "label": "Entreprise",
      "credits_monthly": 50000, "price_monthly_eur": 199, "price_yearly_eur": 1990,
      "max_users": 20,
      "features": ["all"]
    },
    { "code": "pack_1000", "label": "Pack 1 000 crédits", "credits_included": 1000, "price_monthly_eur": 15 }
    /* pack_5000 (60€) et pack_20000 (180€) suivent */
  ]
}

14. get_credits_balance 0 crédit credits:read

Solde et détail (total, utilisé, bonus) pour l'utilisateur authentifié, plus son plan actif.

Aucun paramètre.

Sortie observée

{
  "user_id": 1,
  "email": "netitbe40@gmail.com",
  "credits_remaining": 2977.6,
  "credits_total": 3000,
  "credits_used": 22.4,
  "credits_bonus": 0,
  "plan_code": "free",
  "plan_label": "Découverte"
}

Codes d'erreur

Limitations connues du POC v0.1.0

1. Pas de rate limiting côté MCP — le rate_limit sur les api_keys n'est pas encore enforcé. À ajouter avec express-rate-limit.
2. JWT impersonation via secret partagé — quand JWT_SECRET sera rotaté, il faudra synchroniser le .env du MCP. Migration cible : super-clé MCP dédiée côté sirene-api.
3. Pagination hétérogène — search_companies/search_executives = limit/offset, search_contacts = page/pages. À unifier en v1.
4. get_legal_announcements : retour vide observé sur ORANGE — à valider avec un SIREN ayant des annonces.
5. search_contacts.full_name parfois mal nettoyé (préfixes parasites Apollo/Explorium type _ Optimachines) — bug pipeline d'enrichissement, pas du tool.
6. Pas de tests automatisés — chaque tool a été validé manuellement. Suite Jest à ajouter.