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)

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.

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.

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.

`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).

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 :

Paramètres → Connecteurs → Ajouter un connecteur personnalisé.
Nom : Astrolabe
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-…)
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).

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 5 outils. Une clé absente ou invalide renvoie 401.