Documentation MCP Server SuperSales - Reference API complete

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 créer, modifier ou supprimer une donnée. Les agents IA connectes peuvent uniquement consulter les informations autorisées par la clé MCP et le rôle de l'utilisateur associe.

Transport

Streamable HTTP

Endpoint

/api/mcp

Protocole

JSON-RPC 2.0

REST Calls

/api/calls/batch

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

API REST batch calls

Pour les intégrations qui veulent synchroniser des appels en batch, utilisez aussi GET /api/calls/batch. Elle reutilise les memes cles MCP et le scope calls:read.

Lire la doc REST

Démarrage rapide

Trois étapes pour connecter SuperSales a votre agent IA.

Créer une clé MCP

Dans SuperSales, ouvrez Paramètres > Intégrations > MCP Server. Cliquez sur "Créer une clé MCP" et donnez-lui un nom (ex: "Claude Desktop"). Copiez la clé immédiatement — elle ne sera plus affichée.

Configurer votre client MCP

Ajoutez le serveur SuperSales dans la configuration de votre client MCP avec l'endpoint et la clé 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 clé

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 clé

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 clé. Si vous perdez la clé, 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": "[...données 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"
  ]
}

API REST batch calls

En complement du serveur MCP, SuperSales expose un endpoint REST pour recuperer un batch pagine d appels. Il est utile pour synchroniser un data warehouse, alimenter une API interne, construire un workflow no-code ou fournir a un agent custom le titre, le transcript et la video quand elle est disponible côté SuperSales.

Endpoint

GET /api/calls/batch

Scope

calls:read

Batch

10 par defaut, 20 max

Paramètre	Type	Requis	Description
`limit`	number	non	Nombre de calls retournes. Defaut 10, max 20.
`cursor`	string	non	Curseur retourne par la page precedente.
`date_from`	string ISO	non	Date de debut inclusive. Defaut : 7 jours avant date_to.
`date_to`	string ISO	non	Date de fin inclusive. Defaut : maintenant.
`sales_rep_id`	string	non	Filtre par commercial, toujours intersecte avec les droits MCP.

Exemple cURL

curl "https://supersales.dev/api/calls/batch?limit=20" \
  -H "Authorization: Bearer ss_mcp_VOTRE_CLE"

Reponse simplifiee

{
  "data": [
    {
      "callRecordId": "6651a3f2e8b4c1a2d3e4f567",
      "title": "Discovery call - Acme",
      "meetingDate": "2026-06-02T09:30:00.000Z",
      "salesRepName": "Sarah Martin",
      "transcript": "Prospect: ...",
      "videoUrl": "https://...",
      "videoUrlExpiresAt": "2026-06-02T10:30:00.000Z",
      "videoStatus": "available"
    }
  ],
  "nextCursor": "eyJzY2hlZHVsZWRTdGFydFRpbWUiOiIyMDI2...",
  "limit": 20,
  "resultCount": 1
}

Videos disponibles

Quand la vidéo est disponible, l API retourne un lien temporaire et sécurisé. Sinon, le champvideoUrlvaut null etvideoStatusvaut not_available.

Voir la reference REST complete

Référence des tools

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

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 clé MCP est associée à un ensemble de scopes qui déterminent quels tools sont accessibles. Les scopes sont attribués automatiquement en fonction du rôle de l'utilisateur qui crée la clé.

Scope	Tools autorises	Description
`calls:read`	list_recent_calls, get_call_analysis, search_calls, GET /api/calls/batch	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 clé. Le client MCP ne peut jamais élargir ce périmètre.

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'accéder aux données 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 clé. 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 clé	1 minute	10 requêtes	À la création de la clé
Par utilisateur	1 heure	60 requêtes	À la création de la clé
Par organisation	1 jour (UTC)	250 requêtes	Via mcpSettings de l'organisation
Par organisation	1 mois (UTC)	7 500 requêtes	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 requêtes 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 requête 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 réponse 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 immédiatement.

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 accéder aux données d'une autre organisation.

Read-only strict

Aucun tool MCP ne peut écrire, modifier ou supprimer une donnée. Il n'existe aucune méthode 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 données limitée

Les requêtes de données sont limitées à 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 > Intégrations. La révocation prend effet immédiatement.

FAQ

Le MCP Server SuperSales peut-il modifier mes données ?

Non. Le serveur MCP est strictement read-only. Aucun tool ne peut créer, modifier ou supprimer une donnée. Les agents IA connectés peuvent uniquement lire les analyses, scores, objections et performances autorisées par la clé 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 accès admin. Un manager avec des managedTags voit uniquement les appels des commerciaux dont les tags correspondent à son périmètre. Les autres appels sont invisibles via MCP.

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

Le contrôle d'acces est automatique et basé sur le rôle de l'utilisateur associe a la clé. 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 défaut, une organisation dispose de 250 requêtes par jour et 7 500 par mois. Chaque clé 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 séparer les usages (une clé pour Claude Desktop, une autre pour un agent automatisé). Chaque clé a ses propres limites de débit.

Que se passe-t-il si l'utilisateur associé à la clé est désactivé ?

La clé cesse de fonctionner immédiatement. Le serveur vérifie que l'utilisateur est actif (isActive: true, isDeleted: false) à chaque requête. Révoquer la clé n'est pas necessaire car elle sera automatiquement bloquée.

La fenêtre de dates est-elle limitée ?

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 clé et par utilisateur peuvent aussi être ajustées.

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