Connecteur MCP (Claude, ChatGPT, Cursor…)

Astrolabe expose un serveur MCP (Model Context Protocol) : branchez Claude, ChatGPT, Cursor, n8n ou tout client MCP sur vos bases de connaissances et laissez l’assistant chercher dedans (RAG souverain), avec votre clé sk-….

• URL du serveur : https://api.astrolabe.chat/v1/mcp
• Transport : Streamable HTTP (stateless)
• Authentification : clé sk-… — en en-tête ou dans l’URL (selon le client, voir ci-dessous)

Créez une clé dédiée

Générez une clé API dédiée au MCP dans le portail (Clés API), distincte de votre clé principale. Cochez la seule permission « Connecteur MCP » : la clé ne pourra alors ni lancer d’inférence ni modifier vos bases — uniquement la recherche RAG en lecture seule. Vous pourrez la révoquer indépendamment, et — pour les clients qui mettent la clé dans l’URL — elle n’expose ni votre clé de facturation principale ni vos autres accès.

---

Outils disponibles

Le serveur est en lecture seule (il ne modifie jamais vos bases) et expose 7 outils :

Outil	Rôle
search	Recherche sémantique (questions ouvertes) ou analytique (compter / lister exactement) dans vos bases — par défaut toutes, ou knowledge_base ciblée. Renvoie les extraits, leur score et leur source.
search_all	Recherche globale pour retrouver un document : cross-bases (granularité document). Deux régimes via mode — pertinence (sémantique) ou exploration (facettes + tri + recherche par titre + pagination profonde + total). Idéal pour « où est ce document ? ». Pour compter/agréger ou filtrer finement, préférez search sur une base.
fetch	Récupère un document entier à partir de l’id renvoyé par search.
list_knowledge_bases	Liste vos bases (slug, nom, intention, rôle, volumétrie).
list_facets	Décrit les facettes filtrables d’une base — valeurs présentes et min/max (avec scope optionnel).
search_facet_values	Cherche les valeurs d’une facette par sous-chaîne (une ou plusieurs bases). Pour retrouver la valeur exacte à filtrer quand une facette a trop de valeurs pour être listée entièrement par list_facets.
list_facets_all	Facettes filtrables cross-bases (pendant global de list_facets) : sépare les facettes partagées (≥ 2 bases) des spécifiques. Pour préparer un search_all sur tout le compte.

La recherche embedde votre requête (facturée à l’usage, comme un appel d’embedding classique) ; la requête n’est jamais stockée et le contenu reste chiffré au repos. Le mode analytique (sans query) ne consomme aucun embedding.

Écriture (optionnelle)

Par défaut le serveur est en lecture seule. Si votre clé porte la permission « Écriture des bases » (kb:write), quatre outils supplémentaires apparaissent — ils permettent à l’assistant de modifier vos documents :

Outil	Rôle
add_document	Ajoute un document, ou le remplace s’il existe déjà (upsert par external_id).
update_document	Met à jour ses métadonnées (titre, date, identifiant métier, lien).
update_document_content	Remplace son contenu (avec rechunk: true pour ré-indexer aussitôt).
append_document_content	Ajoute du texte à la fin sans toucher au reste (vous ne fournissez que la nouvelle section). Idéal pour journaliser dans une fiche sans en écraser le contenu.
delete_document	Supprime définitivement un document.

• Ces outils n’apparaissent pas si la clé ne peut pas écrire : une clé de lecture ne les voit même pas, et l’assistant ne peut pas les tenter.
• Le découpage par IA n’est jamais utilisé côté MCP (il consommerait des crédits sans que vous l’ayez demandé) : passez par l’API /v1/kb ou le portail pour ce mode. Sinon, l’écriture MCP suit le découpage par défaut de la base (simple ou whole), et chunk_size reste réglable à l’appel.
• La création et la suppression de bases ne sont pas exposées en MCP : elles restent au portail et à l’API. Une base à laquelle vous êtes abonné (catalogue) est en lecture seule.

L’assistant modifie vraiment vos données

Donner kb:write à une clé MCP, c’est autoriser un assistant externe à créer, modifier et supprimer des documents. Réservez cette permission à une clé dédiée, et gardez une clé de lecture seule pour l’usage courant.

Vos systèmes connectés (connecteurs API)

Si votre clé porte la permission « Connecteurs » (connections), l’assistant peut aussi interroger — et modifier — les systèmes que vous avez connectés (Airtable, Pennylane, Notion, Google…) via trois outils :

Outil	Rôle
list_connector_operations	Catalogue : vos connecteurs, ce qu’ils contiennent, et les opérations appelables avec leurs paramètres.
call_connector	Appelle une opération et renvoie sa réponse.
aggregate_connector	Calcul exact (compte / somme / moyenne / min / max) sur un champ numérique d’une opération de liste : pagine tout côté serveur et rend le total sans faire défiler les enregistrements. Pour « total des factures impayées », « CA de l’année »… — à préférer à une pagination manuelle.

Trois outils seulement, quel que soit le nombre de connecteurs et d’opérations : l’assistant découvre le catalogue à la demande. C’est volontaire — exposer une centaine d’opérations comme autant d’outils alourdirait chaque échange.

• Chaque opération indique son access : read (consultation) ou write (modifie vos données). Déclarer une opération d’écriture vaut autorisation de l’exécuter.
• Une réponse call_connector trop volumineuse est tronquée au grain enregistrement (jamais au milieu d’un objet) avec une note indiquant combien d’éléments sont affichés : pour un total fiable sur un grand volume, utilisez aggregate_connector plutôt que de paginer à la main.
• Vos identifiants ne quittent jamais Astrolabe : ils sont déchiffrés côté serveur au moment de l’appel (jetons OAuth rafraîchis automatiquement), jamais transmis à l’assistant.
• Les appels de connecteurs sont gratuits (seule votre clé sert à les autoriser).

Pour un membre d’organisation (URL personnelle, voir ci-dessous), les connecteurs accessibles sont ceux que l’administrateur lui a partagés ; les opérations write ne sont appelables que si le partage est marqué en écriture.

---

Deux régimes de recherche (search)

L’outil search couvre deux usages combinables, comme le RAG agentique d’Astrolabe :

• Sémantique — fournissez query : recherche par similarité, idéale pour les questions ouvertes (« qu’a-t-on dit sur tel sujet »). Fonctionne sur toutes les bases à la fois.
• Analytique / exact — omettez query et composez librement des filtres sur autant de facettes que nécessaire : égalité (facets), ensembles (in), comparaisons (gt/gte/lt/lte), sous-chaîne (contains), plages de dates (date_range) — le tout cumulé (ET logique), avec tri et pagination. Traitez la base comme une base de données structurée (factures, dossiers, transactions, contacts, événements, produits…). Le résultat est exact et déterministe.

Soyez créatif dans la composition

Le vrai intérêt du mode analytique, c’est de cumuler beaucoup de critères en une requête : par exemple « les éléments dont le statut est ouvert ou en cours, et dont le montant est entre 1 000 et 5 000, et dont l’intitulé contient subvention, sur 2024, triés par date ». Les exemples ci-dessous sont des schémas à transposer : adaptez les noms de facettes aux vôtres (découvrez-les avec list_facets).

Paramètres de search

Paramètre	Description
query	Requête sémantique. À omettre pour compter/lister exactement.
knowledge_base	Slug d’une base, ou liste de slugs. Absent = toutes les bases.
facets	Filtre d’égalité {clé: valeur}, ex. {"type": "facture"}.
filters	Filtres typés [{key, op, value}] (op ∈ eq/neq/gt/gte/lt/lte/in/contains).
sort	Tri {by: relevance|date|alpha, dir: asc|desc}.
group_by	chunk (défaut) · document · date. Pour compter des enregistrements (réunions, factures…), utilisez document et lisez le champ total (compte exact côté serveur, indépendant de top_k). date = un résultat par jour, réservé aux questions chronologiques ; il fusionne les documents d’un même jour → lisez distinct_documents (nombre réel), pas total_dates (nombre de jours).
date_range	Plage de dates métier {from?, to?} (AAAA-MM-JJ).
aggregate	Facette(s) numérique(s) à agréger (nom, ou liste). La réponse porte aggregates [{field, count, sum, avg, min, max}] — sommes/moyennes exactes côté serveur, par enregistrement. Pour « montant moyen », « total facturé », « MRR cumulé » — n’additionnez jamais à la main.
external_id	Lookup exact par votre identifiant métier (réf facture, id CRM… = la clé d’upsert du document) : une chaîne ou une liste. Restreint la recherche aux documents correspondants — à préférer à une requête sémantique quand vous citez une référence précise. L’external_id est renvoyé dans chaque résultat.
title_contains	Recherche par titre du document (et external_id) : sous-chaîne tolérante aux fautes (« recrutment » retrouve « recrutement »). Pour retrouver un document par son nom, pas par le sens de son contenu (celui-ci passe par query).
top_k	Nombre max de résultats (1–50, défaut 6). Mettez 50 pour lister.
offset	Pagination (0, 50, 100…) pour parcourir un ensemble exhaustif.

Une seule base pour les options avancées

filters, sort, group_by, aggregate et title_contains exigent une seule base (précisez knowledge_base avec un slug) : ils s’appuient sur le schéma de facettes de la base pour rester déterministes. Le mode « toutes les bases » reste une recherche sémantique simple.

search_all — retrouver un document (toutes les bases)

Là où search sert à interroger une base finement, search_all sert à retrouver un document sans savoir où il est : il cherche dans toutes vos bases à la fois (un résultat par document). Pour couvrir une source externe (Airtable, Notion, Pennylane…), synchronisez le connecteur dans une base (cf. Connecteurs API) : ses enregistrements deviennent des documents et sont couverts par la même recherche.

Deux régimes, via mode :

• relevance (défaut si query) : classement par pertinence sémantique. Idéal pour « où est ce document ? ».
• browse (défaut sans query) : exploration cross-bases — facettes + tri + recherche par titre (le texte query filtre alors le titre, tolérant aux fautes), avec pagination profonde (limit/offset) et total exact (nombre de documents).

Paramètre	Description
mode	relevance (sémantique) ou browse (exploration). Défaut : relevance si query, sinon browse.
query	Ce que vous cherchez (sémantique en relevance ; filtre de titre en browse).
knowledge_base	Slug ou liste de slugs. Absent = toutes vos bases.
filters	Filtres de facettes [{key, op, value}] (une base qui ne connaît pas la facette est écartée).
sort	Mode browse : { by: "date" | "alpha", dir: "asc" | "desc" }.
top_k	Mode relevance : nombre de documents (1–50, défaut 10).
limit / offset	Mode browse : taille de page (≤ 100) et pagination profonde.

La réponse contient results (documents), sources (une entrée par base, avec son nombre de hits) et, en mode browse, total / offset / page_size / has_more. Pour compter, agréger ou filtrer finement sur une base, utilisez search.

Cartographier une base avec list_facets

Une fois la bonne base identifiée, appelez list_facets sur cette base : c’est l’étape qui révèle tout ce sur quoi vous pouvez filtrer ou trier (clés, types, valeurs, bornes) avant de composer une requête. Pour chaque facette :

• texte / booléen → les valeurs réellement présentes avec leur fréquence, triées par fréquence et plafonnées aux 50 plus courantes. Le champ distinct_count donne le nombre réel de valeurs distinctes et truncated: true signale qu’il y en a davantage.
• nombre / date → les bornes min/max (pas une énumération).

Champs libres à forte cardinalité

Pour une facette libre (ex. des tags aux milliers de valeurs), list_facets ne renvoie pas toutes les valeurs — seulement les 50 plus fréquentes, avec truncated: true. N’attendez donc pas une liste exhaustive. Trois parades :

• Vous cherchez une valeur précise → search_facet_values (key + query) renvoie les valeurs de la facette qui contiennent votre fragment, avec leur fréquence. Réinjectez ensuite la valeur exacte dans un filtre eq/in.
• Vous connaissez (ou devinez) la valeur → filtrez directement avec contains (sous-chaîne) ou in.
• Vous ignorez tout de la valeur → lancez une recherche sémantique (search avec query) sur le sujet, lisez le champ facets des extraits remontés (ils portent les valeurs réellement utilisées), puis réinjectez la bonne valeur dans un filtre exact.

search_facet_values accepte plusieurs bases (ou toutes, si knowledge_base est omis) ; list_facets_all donne, lui, la carte des facettes cross-bases (partagées vs spécifiques) pour préparer un search_all sur l’ensemble du compte.

Quelques patrons utiles

Tous transposables — « réunions », « montant »… ne sont que des exemples :

• Filtre composite → cumulez plusieurs filters (et facets, date_range) en une requête, avec des bornes min/max sur une même clé numérique, un in sur un statut, un contains sur un libellé…
• Lister tout un sous-ensemble → omettez query, posez vos filtres, top_k: 50, puis paginez avec offset tant que vous recevez 50 résultats.
• Cibler, pas scanner → posez vos filters (gte/lte/eq/in/contains) pour ramener directement le sous-ensemble voulu, plutôt que de tout récupérer et trier à la main.
• Compter des enregistrements (réunions, factures, dossiers… — un enregistrement = un document) → group_by: "document" et lisez total : compte exact côté serveur, indépendant de top_k (pas besoin de paginer ni de compter les résultats vous-même).
• Lister TOUT / croiser (« tous les X », « les X qui sont aussi Y ») → le régime analytique renvoie jusqu’à 50 lignes et pose truncated: true si la page ne couvre pas tout : ne concluez jamais sur une page tronquée, paginez avec offset. Pour la liste des valeurs distinctes d’une facette sous condition (toutes les entités concernées), list_facets avec le filtre en scope les renvoie toutes d’un coup — puis faites l’intersection sur les ensembles complets.
• Vue par jour / chronologique (combien de jours d’activité, occurrences par date) → group_by: "date". ⚠️ Plusieurs documents peuvent tomber le même jour : pour un nombre d’enregistrements, lisez distinct_documents (≥ total_dates), jamais le nombre de jours.
• Énumérer les valeurs d’une facette → list_facets. ⚠️ Ses count par valeur comptent des extraits, pas des enregistrements : pour « combien par valeur », repassez par group_by: "document" filtré sur la valeur (lisez total).
• Valeur la plus élevée / la plus basse (montant, score…) → appelez list_facets avec un scope (facets/filters/date_range) : la réponse donne directement le min/max exact de chaque facette numérique pour ce filtre — déterministe, sans scanner les extraits.
• Somme / moyenne d’un montant (« montant moyen des factures », « total facturé », « MRR cumulé ») → passez aggregate = la facette numérique et lisez aggregates {count, sum, avg, min, max} : calcul exact côté serveur, par enregistrement — n’additionnez jamais à la main.

---

Claude (Desktop & web)

Les connecteurs personnalisés de Claude ne proposent qu’un champ URL (pas de champ « clé »). Mettez donc la clé dans l’URL :

1. Paramètres → Connecteurs → Ajouter un connecteur personnalisé.
2. Nom : Astrolabe
3. URL du serveur MCP distant :

   https://api.astrolabe.chat/v1/mcp/u/VOTRE_CLE_SK

   (remplacez VOTRE_CLE_SK par votre clé dédiée, ex. sk-…)
4. Ajouter. Les outils Astrolabe apparaissent dans la conversation.

ChatGPT

Même principe (connecteur / Deep Research) : URL https://api.astrolabe.chat/v1/mcp/u/VOTRE_CLE_SK. Les outils search et fetch sont reconnus nativement.

Cursor / clients avec en-têtes

Les clients qui acceptent des en-têtes utilisent l’URL propre + Authorization :

{
  "mcpServers": {
    "astrolabe": {
      "url": "https://api.astrolabe.chat/v1/mcp",
      "headers": { "Authorization": "Bearer VOTRE_CLE_SK" }
    }
  }
}

n8n / Make (nœud MCP Client)

• Endpoint : https://api.astrolabe.chat/v1/mcp
• Authentification : Bearer / en-tête Authorization: Bearer VOTRE_CLE_SK (ou l’URL …/v1/mcp/u/VOTRE_CLE_SK si le nœud n’accepte pas d’en-tête).

---

Membres d’une organisation (assistant)

Si vous utilisez l’assistant d’une organisation (vous n’avez pas de clé sk-… à vous), vous pouvez tout de même brancher Claude / ChatGPT sur les bases qui vous sont partagées :

1. Votre administrateur active l’accès MCP externe dans les réglages de l’assistant (Portail → Assistant). C’est un choix de souveraineté : le contenu des bases interrogées transitera par le fournisseur que vous branchez (Claude, ChatGPT…), donc hors de l’infra souveraine — comme le connecteur Slack.
2. Dans l’assistant (/assistant), ouvrez « Connecter à Claude / ChatGPT » : une URL personnelle …/v1/mcp/u/<clé> s’affiche. Collez-la dans le champ « serveur MCP » de votre client.

Cette URL est propre à vous : elle donne accès à vos seules bases partagées (jamais à tout le contenu de l’organisation), ne peut pas lancer d’inférence, et son usage est attribué à votre personne sur le budget de l’organisation. Elle est en lecture seule, sauf si votre administrateur vous a explicitement accordé l’écriture sur une base (matrice de partage) : les outils d’écriture n’apparaissent alors que pour ces bases-là. Vous pouvez la régénérer à tout moment (l’ancienne est alors invalidée) ; elle est automatiquement révoquée si vous quittez l’organisation ou si l’administrateur désactive l’accès.

Ne partagez pas votre URL

L’URL contient une clé personnelle. Ne la diffusez pas ; en cas de doute, régénérez-la.

---

Tester en ligne de commande

curl -X POST https://api.astrolabe.chat/v1/mcp \
  -H "Authorization: Bearer VOTRE_CLE_SK" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Vous devez obtenir la liste des outils : les 7 outils de lecture, plus les outils d’écriture si votre clé porte kb:write. Une clé absente ou invalide renvoie 401.

OAuth bientôt

Une connexion OAuth (« 1 clic », sans manipuler de clé) est prévue. En attendant, l’URL avec clé dédiée est la voie recommandée pour Claude et ChatGPT.