Documentation MCP Server SuperSales — Référence API complète

Vue d'ensemble

Le MCP Server SuperSales expose vos données d'appels commerciaux via le Model Context Protocol (MCP), un standard ouvert qui permet aux agents IA de découvrir et d'appeler des tools exposes par une application.

Le serveur est strictement read-only. Aucun tool ne peut creer, modifier ou supprimer une donnée. Les agents IA connectes peuvent uniquement consulter les informations autorisées par la cle MCP et le rôle de l'utilisateur associe.

Transport

Streamable HTTP

Endpoint

/api/mcp

Protocole

JSON-RPC 2.0

7 tools disponibles

list_recent_calls get_call_analysis search_calls get_rep_performance get_team_coaching_summary get_objection_trends get_deal_risk_summary

Fichier d'instructions pour agents IA

Téléchargez le fichier supersales-mcp.md et ajoutez-le au contexte de votre agent IA. Il contient toutes les instructions nécessaires : tools, paramètres, scopes, rate limits et cas d'usage.

.md

Démarrage rapide

Trois étapes pour connecter SuperSales a votre agent IA.

Creer une cle MCP

Dans SuperSales, ouvrez Paramètres > Integrations > MCP Server. Cliquez sur "Creer une cle MCP" et donnez-lui un nom (ex: "Claude Desktop"). Copiez la cle immediatement — elle ne sera plus affichee.

Configurer votre client MCP

Ajoutez le serveur SuperSales dans la configuration de votre client MCP avec l'endpoint et la cle en Bearer token.

Tester

Demandez a votre agent IA : "Liste mes derniers appels commerciaux". Le tool list_recent_calls sera appele automatiquement.

Configuration MCP (format universel)

{
  "mcpServers": {
    "supersales": {
      "url": "https://supersales.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer ss_mcp_VOTRE_CLE"
      }
    }
  }
}

Authentification

Toutes les requêtes MCP (sauf initialize, notifications/initialized et ping) nécessitent une clé API MCP valide.

Format de la cle

Les clés MCP SuperSales suivent le format ss_mcp_{prefix}_{secret} ou :

ss_mcp est le prefixe fixe
prefix est un identifiant court (10 caracteres hex) utilise pour la recherche rapide
secret est une chaine aleatoire de 32 octets en base64url

Comment envoyer la cle

Deux méthodes sont acceptées. Le header Authorization est recommandé.

Méthode 1 — Authorization Bearer (recommandé)

POST /api/mcp HTTP/1.1
Host: supersales.dev
Content-Type: application/json
Authorization: Bearer ss_mcp_a1b2c3d4e5_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Méthode 2 — Header X-API-Key

POST /api/mcp HTTP/1.1
Host: supersales.dev
Content-Type: application/json
X-API-Key: ss_mcp_a1b2c3d4e5_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Important

La clé complète n'est affichée qu'une seule fois lors de la création. SuperSales stocke uniquement le hash SHA-256 de la cle. Si vous perdez la cle, révoquez-la et créez-en une nouvelle.

Protocole JSON-RPC

Le serveur MCP SuperSales utilise le transport Streamable HTTP avec le protocole JSON-RPC 2.0. Toutes les requetes sont des POST vers /api/mcp.

Méthodes système

Méthode	Auth requise	Description
`initialize`	Non	Initialise la session MCP. Retourne la version du protocole, les capacités du serveur et les infos serveur.
`notifications/initialized`	Non	Notification envoyee par le client apres initialisation. Retourne 204 No Content.
`ping`	Non	Vérifie la disponibilité du serveur. Retourne un objet vide.
`tools/list`	Oui	Liste les tools MCP disponibles avec leurs schemas d'entree.
`tools/call`	Oui	Execute un tool MCP. Necessite les parametres name et arguments.

Exemple : initialisation

Requete

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "mon-agent", "version": "1.0.0" }
  }
}

Reponse

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": { "listChanged": false }
    },
    "serverInfo": {
      "name": "supersales-mcp",
      "version": "0.1.0"
    }
  }
}

Exemple : appeler un tool

Requete

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_recent_calls",
    "arguments": {
      "limit": 5
    }
  }
}

Reponse

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[...donnees JSON...]"
      }
    ],
    "structuredContent": {
      "data": [...],
      "resultCount": 5
    },
    "isError": false
  }
}

Endpoint de decouverte (GET)

Un GET /api/mcp retourne les informations de base du serveur sans authentification, utile pour la decouverte automatique.

Reponse GET /api/mcp

{
  "name": "SuperSales MCP Server",
  "protocolVersion": "2025-06-18",
  "transport": "streamable-http",
  "endpoint": "/api/mcp",
  "tools": [
    "list_recent_calls",
    "get_call_analysis",
    "search_calls",
    "get_rep_performance",
    "get_team_coaching_summary",
    "get_objection_trends",
    "get_deal_risk_summary"
  ]
}

Référence des tools

Le serveur MCP expose 7 tools en lecture seule. Chaque tool necessite un ou plusieurs scopes et respecte le controle d'acces de la cle.

list_recent_calls

Liste les appels recents avec leurs scores, statuts et metadonnees.

calls:read

Paramètre	Type	Requis	Description
`date_from`	string	non	Date ISO inclusive. Défaut : 30 jours avant date_to.
`date_to`	string	non	Date ISO inclusive. Défaut : maintenant.
`sales_rep_id`	string	non	Filtre par commercial. Toujours intersecte avec les droits MCP.
`limit`	number	non	Nombre maximum de résultats. Défaut 20, max 50.

Champs retournes : id, call_record_id, sales_rep_name, prospect, type_of_call, note_globale_total, vente_effectuee, no_show, pitch_effectue, next_action, title, meeting_date, actual_duration

Exemple d'utilisation

{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_recent_calls",
    "arguments": {
      "date_from": "2026-05-01",
      "date_to": "2026-05-28",
      "limit": 10
    }
  }
}

get_call_analysis

Retourne le detail complet d'une analyse d'appel : resume, score, evaluation des competences, objections, forces, axes d'amelioration et coaching.

calls:read

Paramètre	Type	Requis	Description
`id`	string	oui	ID de l'analyse d'appel a recuperer.
`include_transcript_excerpt`	boolean	non	Si true, inclut un extrait de transcription (max 2 000 caractères). Défaut : false.

Champs retournes : tous les champs de l'analyse incluant resume_de_lappel, note_globale_total, evaluation_competences (JSON), objections_lead (JSON), resume_forces (JSON), axes_amelioration (JSON), lead_scoring (JSON), prochaines_actions (JSON), temps_de_parole_closeur, temps_de_parole_client, deal_value, vente_effectuee

Exemple d'utilisation

{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_call_analysis",
    "arguments": {
      "id": "6651a3f2e8b4c1a2d3e4f567",
      "include_transcript_excerpt": true
    }
  }
}

search_calls

Recherche full-text dans les titres, noms de prospects, noms de commerciaux, resumes et objections des appels.

calls:read

Paramètre	Type	Requis	Description
`query`	string	oui	Texte à rechercher (minimum 2 caractères).
`date_from`	string	non	Date ISO inclusive. Défaut : 30 jours avant date_to.
`date_to`	string	non	Date ISO inclusive. Défaut : maintenant.
`sales_rep_id`	string	non	Filtre par commercial.
`limit`	number	non	Nombre maximum de résultats. Défaut 20, max 50.

Exemple : chercher les appels ou le prix a ete mentionne

{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_calls",
    "arguments": {
      "query": "trop cher",
      "date_from": "2026-05-01"
    }
  }
}

get_rep_performance

Retourne les metriques de performance par commercial : volume d'appels, deals gagnes, revenu, score moyen, taux de closing, no-shows et pitchs.

coaching:read

Paramètre	Type	Requis	Description
`date_from`	string	non	Date ISO inclusive.
`date_to`	string	non	Date ISO inclusive.
`sales_rep_id`	string	non	Filtre par commercial.
`limit`	number	non	Nombre maximum de resultats.

Champs retournes : sales_rep_id, sales_rep_name, total_calls, deals_won, total_revenue, avg_score, win_rate, no_show_count, pitch_count

Exemple : performances du mois en cours

{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_rep_performance",
    "arguments": {
      "date_from": "2026-05-01",
      "date_to": "2026-05-31"
    }
  }
}

get_team_coaching_summary

Synthese des indicateurs de coaching pour le périmètre autorise : score moyen, taux de closing, ratios de parole, et les 5 appels prioritaires a coacher (scores les plus bas).

team:readcoaching:read

Paramètre	Type	Requis	Description
`date_from`	string	non	Date ISO inclusive.
`date_to`	string	non	Date ISO inclusive.
`sales_rep_id`	string	non	Filtre par commercial.
`limit`	number	non	Nombre maximum de resultats.

Structure de reponse : un objet summary (total_calls, active_reps, average_score, deals_won, win_rate, no_show_count, pitch_count, pitch_rate, avg_closer_talk_ratio, avg_client_talk_ratio) et un tableau priority_coaching_calls (les 5 appels avec les scores les plus bas).

Exemple : synthese coaching du trimestre

{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_team_coaching_summary",
    "arguments": {
      "date_from": "2026-03-01",
      "date_to": "2026-05-31"
    }
  }
}

get_objection_trends

Agrege les objections detectees par l'IA dans les appels avec leur frequence, type et taux de resolution.

analytics:read

Paramètre	Type	Requis	Description
`date_from`	string	non	Date ISO inclusive.
`date_to`	string	non	Date ISO inclusive.
`sales_rep_id`	string	non	Filtre par commercial.
`limit`	number	non	Nombre maximum de resultats.

Champs retournes : objection, objection_type, total_count, resolved_count, resolution_rate

Exemple : objections du mois

{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_objection_trends",
    "arguments": {
      "date_from": "2026-05-01"
    }
  }
}

get_deal_risk_summary

Liste les deals/appels a risque selon plusieurs criteres : no-show, score bas (<60), pitch absent, ou next action risquee (perdu, relance, r2_decision).

analytics:read

Paramètre	Type	Requis	Description
`date_from`	string	non	Date ISO inclusive.
`date_to`	string	non	Date ISO inclusive.
`sales_rep_id`	string	non	Filtre par commercial.
`limit`	number	non	Nombre maximum de resultats.

Champs retournes : tous les champs de l'appel plus un champ risk_reason indiquant le motif du risque : no_show, low_score, pitch_missing, risky_next_action, attention_required.

Exemple : deals à risque du mois

{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_deal_risk_summary",
    "arguments": {
      "date_from": "2026-05-01",
      "limit": 20
    }
  }
}

Scopes et permissions

Chaque cle MCP est associee a un ensemble de scopes qui determinent quels tools sont accessibles. Les scopes sont attribués automatiquement en fonction du rôle de l'utilisateur qui cree la cle.

Scope	Tools autorises	Description
`calls:read`	list_recent_calls, get_call_analysis, search_calls	Lecture des appels et de leurs analyses.
`coaching:read`	get_rep_performance, get_team_coaching_summary	Consultation des performances individuelles et coaching equipe.
`team:read`	get_team_coaching_summary	Acces aux syntheses equipe (combine avec coaching:read).
`analytics:read`	get_objection_trends, get_deal_risk_summary	Analyse des tendances objections et des deals à risque.

Attribution automatique des scopes

Role	Scopes attribues
Admin / Super Admin / Head of Sales / Owner	calls:read, coaching:read, team:read, analytics:read
Manager	calls:read, coaching:read, team:read, analytics:read
Commercial (default)	calls:read, coaching:read

Controle d'acces

Le serveur MCP applique automatiquement un périmètre de données basé sur le rôle de l'utilisateur associe a la cle. Le client MCP ne peut jamais elargir ce perimetre.

organization

Accès organisation

Roles : Admin, Super Admin, Head of Sales, Owner

Voit tous les appels et toutes les performances de l'organisation. Peut filtrer par sales_rep_id mais n'est pas restreint.

managed_tags

Accès par tags gérés

Roles : Manager avec managedTags

Voit uniquement les appels des commerciaux dont les tags correspondent a ses managedTags, plus ses propres appels. Le filtre est appliqué côté serveur.

self

Accès personnel

Roles : Commercial

Voit uniquement ses propres appels et analyses. Toute tentative d'acceder aux donnees d'un autre commercial retourne une erreur FORBIDDEN.

Comment fonctionne le filtre sales_rep_id

Le parametre sales_rep_id permet de filtrer les résultats par commercial. Le serveur l'intersecte toujours avec le périmètre autorise de la cle. Si le commercial demande n'est pas dans le périmètre, une erreur FORBIDDEN est retournée. Pour un accès organization, le filtre est appliqué sans restriction.

Rate limits

Le serveur MCP applique des limites de débit à 4 niveaux pour proteger la plateforme et garantir un usage équitable.

Niveau	Fenêtre	Limite par defaut	Configurable
Par cle	1 minute	10 requetes	A la création de la cle
Par utilisateur	1 heure	60 requetes	A la création de la cle
Par organisation	1 jour (UTC)	250 requetes	Via mcpSettings de l'organisation
Par organisation	1 mois (UTC)	7 500 requetes	Via mcpSettings de l'organisation

Quand une limite est dépassée, le serveur retourne une erreur JSON-RPC avec le code -32029 et le code d'erreur RATE_LIMITED. Les compteurs sont reinitialises automatiquement a l'expiration de la fenêtre.

Désactivation globale

Une organisation peut désactiver complètement le MCP en mettant mcpSettings.enabled = false. Dans ce cas, toutes les requetes MCP retournent une erreur FORBIDDEN avec le message “MCP is disabled for this organization”.

Gestion des erreurs

Les erreurs sont retournées au format JSON-RPC 2.0 standard avec un code numerique et un code d'erreur SuperSales dans le champ data.code.

Code JSON-RPC	Code SuperSales	Description
-32700	`—`	Parse error : le corps de la requete n'est pas du JSON valide.
-32600	`—`	Invalid request : la méthode est manquante.
-32601	`—`	Method not found : la méthode demandée n'existe pas.
-32602	`BAD_REQUEST`	Paramètres invalides : date hors limites, query trop courte, ID manquant.
-32001	`UNAUTHORIZED`	Clé MCP manquante, invalide, ou révoquée.
-32003	`FORBIDDEN`	Scope manquant, acces interdit au commercial demande, ou MCP désactivé.
-32029	`RATE_LIMITED`	Quota dépassé (par minute, heure, jour ou mois).
-32603	`INTERNAL_ERROR`	Erreur interne du serveur.

Exemple de reponse d'erreur

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32003,
    "message": "Missing MCP scope: team:read",
    "data": {
      "code": "FORBIDDEN"
    }
  }
}

Configuration des clients MCP

Exemples de configuration pour les clients MCP les plus courants. Remplacez ss_mcp_VOTRE_CLE par la clé copiée lors de la création.

Claude Desktop

Fichier de configuration : ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows).

claude_desktop_config.json

{
  "mcpServers": {
    "supersales": {
      "url": "https://supersales.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer ss_mcp_VOTRE_CLE"
      }
    }
  }
}

Claude Code (CLI)

Ajoutez le serveur MCP via la commande claude mcp add.

Terminal

claude mcp add supersales \
  --transport http \
  --url https://supersales.dev/api/mcp \
  --header "Authorization: Bearer ss_mcp_VOTRE_CLE"

Cursor

Fichier de configuration : .cursor/mcp.json à la racine du projet ou dans les parametres globaux de Cursor.

.cursor/mcp.json

{
  "mcpServers": {
    "supersales": {
      "url": "https://supersales.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer ss_mcp_VOTRE_CLE"
      }
    }
  }
}

cURL (test manuel)

Terminal

curl -X POST https://supersales.dev/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ss_mcp_VOTRE_CLE" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_recent_calls",
      "arguments": { "limit": 5 }
    }
  }'

Sécurité

Le serveur MCP SuperSales est concu selon le principe du moindre privilege. Voici les mesures de securite en place.

Clés hashées

Les clés MCP sont hashées avec SHA-256. Le serveur ne stocke jamais la clé en clair. La comparaison utilise timingSafeEqual pour prevenir les attaques par timing.

Rattachement utilisateur

Chaque clé est liée a un utilisateur SuperSales spécifique. Si l'utilisateur est désactivé ou supprimé, toutes ses clés MCP cessent de fonctionner immediatement.

Organisation forcée côté serveur

L'organizationId est toujours résolu depuis la clé, jamais depuis les paramètres de la requête. Un client MCP ne peut pas acceder aux donnees d'une autre organisation.

Read-only strict

Aucun tool MCP ne peut ecrire, modifier ou supprimer une donnée. Il n'existe aucune methode d'ecriture dans le serveur.

Transcription limitée

Les transcriptions completes ne sont jamais exposées. Seul un extrait de 2 000 caractères peut être demandé explicitement via include_transcript_excerpt.

Audit log complet

Chaque requête MCP est journalisée avec : tool appele, parametres demandes, périmètre résolu, nombre de résultats, statut, code erreur et duree d'execution.

Fenêtre de donnees limitee

Les requetes de donnees sont limitees a une fenêtre de 90 jours maximum. Il n'est pas possible d'extraire l'historique complet via MCP.

Révocation instantanée

Les clés peuvent être révoquées à tout moment depuis Paramètres > Integrations. La révocation prend effet immédiatement.

FAQ

Le MCP Server SuperSales peut-il modifier mes donnees ?

Non. Le serveur MCP est strictement read-only. Aucun tool ne peut creer, modifier ou supprimer une donnée. Les agents IA connectes peuvent uniquement lire les analyses, scores, objections et performances autorisees par la cle MCP.

Quels clients MCP sont compatibles avec SuperSales ?

Tout client compatible MCP Streamable HTTP peut se connecter : Claude Desktop, Claude Code, Cursor, Windsurf et tout agent IA supportant le protocole MCP avec transport HTTP. La configuration nécessite l'endpoint https://supersales.dev/api/mcp et une clé API en Bearer token.

Un manager voit-il tous les appels de l'organisation ?

Non, sauf s'il dispose d'un acces admin. Un manager avec des managedTags voit uniquement les appels des commerciaux dont les tags correspondent a son perimetre. Les autres appels sont invisibles via MCP.

Comment fonctionne le controle d'acces MCP pour les managers ?

Le controle d'acces est automatique et base sur le rôle de l'utilisateur associe a la cle. Un admin ou head of sales voit toute l'organisation. Un manager avec des managedTags voit uniquement les commerciaux dont les tags correspondent. Un commercial ne voit que ses propres appels. Le périmètre est toujours appliqué côté serveur, jamais côté client.

Quels sont les quotas MCP par defaut ?

Par defaut, une organisation dispose de 250 requetes par jour et 7 500 par mois. Chaque cle est limitée à 10 requêtes par minute, et chaque utilisateur a 60 requêtes par heure. Ces quotas sont configurables par organisation.

Les transcriptions completes sont-elles accessibles via MCP ?

Non. Par defaut, les transcriptions ne sont pas exposées. Le tool get_call_analysis accepte un parametre include_transcript_excerpt qui retourne un extrait limité à 2 000 caractères. La transcription complete n'est jamais accessible via MCP.

Puis-je utiliser plusieurs cles MCP ?

Oui. Chaque utilisateur peut créer plusieurs clés avec des noms différents. C'est utile pour separer les usages (une cle pour Claude Desktop, une autre pour un agent automatise). Chaque cle a ses propres limites de debit.

Que se passe-t-il si l'utilisateur associe a la cle est désactivé ?

La cle cesse de fonctionner immédiatement. Le serveur verifie que l'utilisateur est actif (isActive: true, isDeleted: false) a chaque requete. Révoquer la clé n'est pas necessaire car elle sera automatiquement bloquée.

La fenetre de dates est-elle limitee ?

Oui. La fenetre maximale est de 90 jours. Si date_from et date_to couvrent une periode plus longue, le serveur retourne une erreur BAD_REQUEST. Si aucune date n'est specifiee, le défaut est les 30 derniers jours.

Comment augmenter les quotas MCP de mon organisation ?

Contactez le support SuperSales pour ajuster les limites dailyRequestLimit et monthlyRequestLimit de votre organisation. Les limites par cle et par utilisateur peuvent aussi etre ajustees.

Prêt à connecter vos agents IA ?

Créez votre clé MCP en quelques secondes depuis les parametres SuperSales et commencez à interroger vos données commerciales avec vos agents IA.

Activer SuperSales Voir la presentation MCP