Cursor MCP einrichten: Dokumentation direkt im Editor durchsuchen

Damit Cursor Ihre Dokumentation durchsuchen kann, tragen Sie einen MCP Server in die Datei `.cursor/mcp.json` Ihres Projekts ein und hinterlegen einen API-Schlüssel im Header. Danach ruft der Agent die Suche selbstständig auf, während er Code schreibt, und zeigt Ihnen die Textstellen, auf die er sich stützt. Dieses Tutorial liefert die exakte Konfiguration, erklärt die verfügbaren Tools, zeigt bewährte Prompts und hilft bei der Fehlersuche.

Warum Dokumentation per MCP an Cursor anbinden?

Cursor kennt den Code in Ihrem Repository sehr gut. Was außerhalb liegt, bleibt ihm verborgen: interne API-Konventionen, das Integrationshandbuch eines Zulieferers, die Datenschutzvorgaben Ihres Unternehmens. Fehlt dieses Wissen, rät der Agent, und eine geratene Annahme im generierten Code fällt im Review oft erst spät auf.

Das Model Context Protocol (MCP) ist ein offener Standard, über den KI-Clients wie Cursor externe Tools aufrufen. Ein Dokumentations-Server stellt eine Suche als Tool bereit; der Agent entscheidet, wann er sie nutzt, erhält passende Textstellen und baut seine Antwort oder Codeänderung darauf auf. Dahinter steckt eine Retrieval-Pipeline, wie sie RAG as a Service ohne eigene Infrastruktur bereitstellt.

• Antworten aus einer Quelle, die Sie bestimmen, nicht aus dem Trainingswissen des Modells.
• Überprüfbare Belege: Jede Antwort enthält nummerierte Textstellen.
• Kein Kopieren ganzer Seiten in den Chat mehr, das Kontextfenster bleibt für den Code frei.
• Eine Wissensquelle für das ganze Team: Derselbe Server funktioniert auch in Claude, ChatGPT und anderen MCP-Clients.

Voraussetzungen

1. Eine aktuelle Cursor-Version mit MCP-Unterstützung.
2. Eine Wissensdatenbank. Entweder eine öffentliche Basis aus dem Katalog oder Ihre eigene Dokumentation als private Basis. Das Anlegen einer Basis ist kostenlos: Sie laden PDF-, Word-, Text- oder Markdown-Dateien hoch, Kopik extrahiert, zerlegt und indexiert sie für eine hybride Suche.
3. Ein Kopik API-Schlüssel aus dem Dashboard, beginnend mit `kpk_`. Nur das kostenlose Tool `list_bases` funktioniert ohne Schlüssel.
4. Schreibrechte im Projektverzeichnis.

Schritt 1: die Datei .cursor/mcp.json anlegen

Legen Sie im Projektstamm einen Ordner `.cursor` an und darin eine Datei `mcp.json`. Fügen Sie folgenden Inhalt ein und ersetzen Sie den Schlüssel durch Ihren eigenen: `{ "mcpServers": { "kopik": { "url": "https://kopik.io/api/mcp", "headers": { "Authorization": "Bearer kpk_…" } } } }`. Soll der Server in allen Projekten verfügbar sein, legen Sie denselben Inhalt in die `mcp.json` im Ordner `.cursor` Ihres Home-Verzeichnisses.

Den Server auf eine einzige Basis festlegen

Die obige URL öffnet den gesamten Katalog, der Agent nennt bei jedem Aufruf eine Basis. Braucht das Projekt nur eine Dokumentation, verwenden Sie die eigene URL der Basis: `https://kopik.io/api/mcp?base=ihr-basis-slug`, die auf jeder Basisseite angezeigt wird. Das Argument `base` entfällt dann, Prompts werden kürzer, und der Agent kann nicht in fremde Bestände abschweifen. Das funktioniert auch für private Basen mit dem Schlüssel des Eigentümers.

Schritt 2: die Tools in Cursor prüfen

Öffnen Sie die MCP-Einstellungen von Cursor. Der Server `kopik` sollte aktiv sein und drei Tools anzeigen. Haben Sie die Datei bei geöffnetem Editor geändert, schalten Sie den Server aus und wieder ein oder laden Sie das Fenster neu.

`maxPriceCents` ist eine Kostenbremse: Kostet die Basis mehr, wird der Aufruf abgelehnt, ohne dass etwas berechnet wird. Fragen an Ihre eigenen Basen sind im Rahmen einer fairen Nutzung (etwa 200 pro Tag) kostenlos.

Bewährte Prompts für den Alltag

Der Agent entscheidet selbst, wann er ein Tool aufruft. Wenn Sie Tool und Basis ausdrücklich nennen, wird sein Verhalten vorhersehbar:

• Basis finden: „Nutze list_bases mit der Suche ‚AI Act‘ und sag mir, welche Basis zu Fragen über Hochrisiko-Systeme passt.“
• Mit Quellen fragen: „Frag die Basis eu-ai-act-essentials, welche Pflichten Anbieter von Hochrisiko-KI-Systemen haben, und zitiere die Textstellen.“
• Code nach eigener Doku: „Ruf ask_base auf interne-api-richtlinien auf: Wie funktioniert die Paginierung am Endpunkt für Bestellungen? Passe dann fetchOrders in dieser Datei an.“
• Rohe Textstellen: „Nutze search_base auf interne-api-richtlinien für ‚Wiederholungsstrategie und Idempotenzschlüssel‘, schreib den Retry-Wrapper und vermerke die Stellennummern im Kommentar.“
• Kosten deckeln: „Stell die Frage mit maxPriceCents 10.“

Zwei Gewohnheiten zahlen sich aus. Verlangen Sie die Textstellen und nicht nur das Ergebnis, damit Sie vor dem Merge prüfen können. Und formulieren Sie Fragen so, wie sie in der Dokumentation stehen würden: Fachbegriffe, Endpunktnamen und Paragrafen finden die Suche zuverlässiger als vage Umschreibungen. Liefert eine Basis keine passende Stelle, sagt die Antwort das ausdrücklich; dann lohnt sich ein Blick auf eine andere Basis statt einer Umformulierung ins Blaue.

Fehlerbehebung: wenn der Server stumm bleibt

Für eigene Skripte gilt zusätzlich: JSON-RPC-Batches sind auf 10 Anfragen begrenzt. Alle Details inklusive der REST-API finden Sie in der Entwicklerdokumentation.

Sicherheit und Kosten im Teambetrieb

Abgerufener Text ist ein Datum, keine Anweisung. Kopik umschließt Inhalte aus Basen mit kopik-untrusted-Tags, damit der Client sie vom eigentlichen Prompt unterscheiden kann. Das erschwert Prompt Injection über präparierte Dokumente, ein Thema, auf das auch das BSI in seinen Veröffentlichungen zu KI-Systemen hinweist. Lassen Sie die Freigabe einzelner Tool-Aufrufe in Cursor aktiv, solange der Agent in derselben Sitzung auch Dateien ändern oder Befehle ausführen darf.

API- und MCP-Aufrufe werden immer zum Preis der jeweiligen Basis aus vorausbezahltem Guthaben abgerechnet; die Gratisfragen auf der Website gelten hier nicht. Ihre eigenen Basen bleiben im Rahmen fairer Nutzung kostenlos.

Bevor Sie das Setup im ganzen Team ausrollen, klären Sie drei Punkte: welche Basen das Projekt abfragen darf, welcher Standardwert für `maxPriceCents` in den Agent-Anweisungen des Teams steht und wer für den API-Schlüssel verantwortlich ist. Ein gemeinsamer Schlüssel ist bequem, persönliche Schlüssel machen es aber deutlich leichter, Zugänge beim Ausscheiden eines Mitarbeiters zu widerrufen und Kosten nachzuvollziehen.