Cursor et MCP : ajouter la recherche dans votre documentation à l'éditeur

Pour donner à Cursor un accès à votre documentation, il suffit de déclarer un serveur MCP dans le fichier `.cursor/mcp.json` de votre projet, avec une clé API dans un en-tête. L'agent de Cursor peut alors interroger une base de connaissances pendant qu'il code et vous montrer les passages sur lesquels il s'appuie. Ce tutoriel donne la configuration exacte, les outils disponibles, des prompts types et les solutions aux erreurs les plus fréquentes.

Pourquoi brancher une documentation sur Cursor via MCP ?

Cursor lit très bien le code de votre dépôt. En revanche, il ignore tout ce qui vit à côté : vos conventions d'API internes, le guide d'intégration d'un prestataire, les règles de facturation que votre module doit respecter. Faute d'information, l'agent devine, et une supposition glissée dans du code généré coûte cher à repérer en revue.

Le Model Context Protocol (MCP) est un standard ouvert qui permet à un client d'IA comme Cursor d'appeler des outils externes. Un serveur de documentation expose un outil de recherche ; l'agent décide quand l'appeler, reçoit des passages et construit sa réponse ou sa modification à partir d'eux. Concrètement, vous y gagnez :

• Des réponses fondées sur une source choisie plutôt que sur les souvenirs d'entraînement du modèle.
• Des citations vérifiables : chaque réponse arrive avec des passages numérotés.
• La fin du copier-coller de pages entières dans le chat, ce qui préserve la fenêtre de contexte pour le code.
• Une seule source de vérité pour l'équipe : le même serveur fonctionne dans Claude, ChatGPT et d'autres clients MCP.

Pour une vue d'ensemble des agents connectés à une base, lisez connecter une base de connaissances aux agents IA avec MCP. Ici, on reste centré sur Cursor.

Les prérequis

1. Une version récente de Cursor, avec la prise en charge de MCP.
2. Une base à interroger : une base publique du catalogue Kopik, ou votre propre documentation déposée en base privée. La création d'une base est gratuite : vous déposez des PDF, des fichiers Word, du texte ou du Markdown, Kopik extrait, découpe et indexe pour une recherche hybride.
3. Une clé API Kopik, créée depuis le tableau de bord, qui commence par `kpk_`. Seul l'outil gratuit `list_bases` fonctionne sans clé.
4. Le droit d'ajouter un fichier à la racine du projet.

Étape 1 : écrire le fichier .cursor/mcp.json

À la racine du projet, créez un dossier `.cursor` puis, dedans, un fichier `mcp.json`. Collez ce contenu en remplaçant la clé par la vôtre : `{ "mcpServers": { "kopik": { "url": "https://kopik.io/api/mcp", "headers": { "Authorization": "Bearer kpk_…" } } } }`. Si vous voulez le serveur dans tous vos projets, placez le même contenu dans le `mcp.json` du dossier `.cursor` de votre répertoire personnel.

Restreindre le serveur à une seule base

L'URL ci-dessus donne accès à tout le catalogue : l'agent précise la base à chaque appel. Si le projet n'a besoin que d'une documentation, utilisez plutôt l'adresse propre à la base, `https://kopik.io/api/mcp?base=slug-de-votre-base`, affichée sur chaque page de base. L'argument `base` disparaît alors des outils, les prompts raccourcissent et l'agent ne peut pas s'égarer ailleurs. Cela fonctionne aussi pour une base privée, avec la clé de son propriétaire.

Étape 2 : vérifier les outils dans Cursor

Ouvrez les réglages MCP de Cursor : le serveur `kopik` doit apparaître actif, avec trois outils. Si vous avez modifié le fichier pendant que Cursor était ouvert, désactivez puis réactivez le serveur, ou rechargez la fenêtre.

Par défaut, Cursor vous demande d'approuver chaque appel d'outil. Gardez ce réglage au début : vous voyez exactement quelle base et quelle question l'agent envoie.

Des prompts types qui fonctionnent

L'agent choisit seul le moment d'appeler un outil, mais nommer l'outil et la base rend son comportement prévisible :

• Trouver une base : « Utilise list_bases avec la requête « TVA micro-entreprise » et dis-moi quelle base convient. »
• Poser une question sourcée : « Demande à la base fr-micro-entrepreneur-fiscalite-tva à partir de quel chiffre d'affaires la franchise en base de TVA cesse de s'appliquer, et cite les passages. »
• Coder d'après votre doc : « Appelle ask_base sur guide-api-interne : comment fonctionne la pagination de l'endpoint commandes ? Puis adapte fetchOrders dans ce fichier. »
• Récupérer des passages bruts : « Utilise search_base sur guide-api-interne pour « politique de relance et clés d'idempotence », écris le wrapper de relance et indique les numéros de passages en commentaire. »
• Plafonner la dépense : « Pose la question avec maxPriceCents à 10. »

Deux réflexes changent tout. Demandez les passages, pas seulement la conclusion, pour vérifier avant de fusionner. Et préférez `search_base` quand l'agent va de toute façon écrire du code : il reçoit les preuves brutes et raisonne dans votre contexte, au même prix.

Dépannage : quand le serveur MCP ne répond pas

Si vous scriptez vos appels, sachez que les lots JSON-RPC sont limités à 10 requêtes. Tout le détail, y compris l'API REST équivalente, se trouve dans la documentation développeurs.

Sécurité et coûts avant de déployer en équipe

Le texte récupéré est une donnée, pas une consigne. Kopik encadre le contenu des bases par des balises kopik-untrusted pour que le client le distingue de votre prompt, ce qui limite l'injection d'instructions cachées dans un document. Gardez l'approbation des appels activée dans les sessions où l'agent peut aussi modifier des fichiers ou lancer des commandes.

Côté budget, les appels par API et MCP sont toujours facturés au prix de la base, sur des crédits prépayés ; les questions offertes sur le site ne s'appliquent pas ici. Vos propres bases restent gratuites dans la limite d'un usage raisonnable.