Dokumentation

Endpunkt und Transport

• URL: https://api.privatrak.com/mcp. Eine Adresse gilt für alle Ihre Projekte. Eine per Anmeldung hergestellte Verbindung kann mehrere Projekte umfassen, ein API-Schlüssel genau eines.
• Transport: Streamable HTTP. Der Server akzeptiert jede Protokollversion von 2024-11-05 bis 2026-07-28. Senden Sie jede Nachricht als POST mit Content-Type: application/json und Accept: application/json, text/event-stream. Fehlt einer der beiden Typen in Accept, antwortet der Server mit 400. Antworten kommen als einfaches JSON zurück.
• Zustandslos: Der Server hält zwischen Anfragen nichts fest und vergibt keine Mcp-Session-Id, jede Anfrage steht also für sich. GET und DELETE auf /mcp antworten mit 405, weil es keinen Stream zu öffnen oder zu schließen gibt.
• CORS: /mcp erlaubt jede Herkunft, ohne Cookies oder andere Zugangsdaten des Browsers, und unter anderem die Anfrage-Header Authorization, X-API-Key, Mcp-Protocol-Version und Mcp-Session-Id. WWW-Authenticate ist freigegeben, damit browserbasierte Clients wie MCP Inspector den OAuth-Ablauf starten können.

Authentifizierung

/mcp akzeptiert zwei Arten von Zugangsdaten: ein OAuth-Access-Token, das bei der Anmeldung eines Nutzers ausgestellt wird, oder einen der API-Schlüssel eines Projekts. Beide senden Sie als Authorization: Bearer TOKEN.

OAuth

• Ablauf: OAuth 2.1 Authorization Code mit PKCE, nur S256. Clients sind öffentlich (token_endpoint_auth_method: none). Es gibt kein Client Secret und keinen Implicit-, Password- oder Client-Credentials-Grant.
• Erkennung: Jede 401 von /mcp nennt in WWW-Authenticate die Protected Resource Metadata (RFC 9728) unter https://api.privatrak.com/.well-known/oauth-protected-resource/mcp. Sie verweisen auf den Authorization Server, dessen Metadaten (RFC 8414) unter /.well-known/oauth-authorization-server liegen. Die Endpunkte sind /oauth/authorize, /oauth/token, /oauth/register und /oauth/revoke.
• Client-Registrierung: über ein Client ID Metadata Document, also eine client_id mit https-URL, unter der die Metadaten des Clients liegen, oder über Dynamic Client Registration (RFC 7591) unter /oauth/register. Claude nutzt das erste, Cursor und Codex das zweite.
• Scopes: read und write, wobei write read einschließt. Eine Anfrage ohne Scope erhält read. offline_access wird akzeptiert und ändert nichts, weil jede Verbindung ein Refresh-Token erhält.
• Zustimmung: Die Person wählt die Projekte, entweder Alle meine Projekte (auch später angelegte oder beigetretene) oder Nur diese, und den Zugriff, Lesen oder Lesen und schreiben. Lesen und schreiben wird angeboten, wenn der Client write angefragt hat. Was die Person dabei sieht, steht unter KI-Assistenten verbinden.
• Tokens: Access-Tokens gelten 1 Stunde und sind an die Ressource https://api.privatrak.com/mcp gebunden (RFC 8707). Die REST-API akzeptiert sie deshalb nicht. Refresh-Tokens rotieren bei jeder Verwendung und verfallen nach 30 Tagen ohne Verwendung.
• Zugriff: read erhält dieselben Tools wie ein KI-Assistenten-Schlüssel. write ergänzt die schreibenden Tools, die Tools für Setup-Läufe und den Prompt setup_project, also dieselben Schreibrechte wie ein Schlüssel mit vollem Zugriff.
• Widerruf: Die Person trennt einen Client unter Einstellungen › Konto › Verbundene KI-Apps. Dessen Tokens enden damit sofort. Ein Client kann seine eigenen Tokens unter /oauth/revoke widerrufen (RFC 7009).

API-Schlüssel

Senden Sie einen der API-Schlüssel eines Projekts als Authorization: Bearer YOUR_KEY oder X-API-Key: YOUR_KEY. Beide Header mit unterschiedlichen Schlüsseln ergeben 401. Ein Schlüssel gehört zu einem Projekt, und was er darf, hängt von seiner Art ab:

• Ihr KI-Assistent (Typ read): alle lesenden Tools, der Prompt product_review und die Anleitung. Er kann nichts ändern und sieht weder Mitglieder noch Abrechnung noch andere Schlüssel.
• Voller Zugriff (Typ secret): zusätzlich alle schreibenden Tools, die Tools für Setup-Läufe und der Prompt setup_project.
• Ihre Website (Typ public): abgelehnt, weil er im Quelltext Ihrer Seite steht, wo ihn jeder lesen kann.

Diese Anfragen bekommen 401: ohne Zugangsdaten, mit unbekannten, abgelaufenen oder widerrufenen Zugangsdaten oder mit einem Website-Schlüssel. Die Antwort enthält WWW-Authenticate: Bearer realm="privatrak" und die resource_metadata-URL, dazu error="invalid_token", wenn Zugangsdaten mitgeschickt wurden. Im JSON-Body sagt error, was nicht stimmte, und error_code lautet auth_invalid_token. Lassen sich die Zugangsdaten nicht prüfen, weil der Dienst kurz nicht erreichbar ist, lautet die Antwort 503, und ein erneuter Versuch ist unbedenklich.

Projekte

Jedes Tool und jeder Prompt, der sich auf ein Projekt bezieht, nimmt ein optionales Argument project entgegen, eine Projekt-ID aus list_projects. Der Server merkt sich zwischen zwei Aufrufen kein aktuelles Projekt.

• Eine Verbindung mit nur einem Projekt kann es weglassen, ebenso jeder API-Schlüssel. Ein API-Schlüssel lehnt jedes Projekt außer seinem eigenen ab.
• Umfasst eine Verbindung mehr als ein Projekt, ist ein Aufruf ohne project ein Tool-Fehler, der die Projekte auflistet. Der Assistent fragt dann nach, statt zu raten. Die Mitgliedschaft im Projekt wird bei jedem Aufruf geprüft.
• list_projects liefert für jedes Projekt ID, Name, Zeitzone und Zugriff. Für einen API-Schlüssel nennt es dessen einziges Projekt.

Anfragelimit

Jeder API-Schlüssel und jede Verbindung darf 60 Anfragen am Stück senden, aufgefüllt mit einer Anfrage alle zwei Sekunden. Darüber hinaus antwortet der Server mit 429, Retry-After: 2 und dem error_code mcp_rate_limited. Jede Anfrage zählt, auch tools/list.

Datenkonventionen

• Datumsangaben sind Kalendertage im Format YYYY-MM-DD in der Zeitzone des Projekts, die get_project liefert. Zeitstempel in Antworten sind UTC.
• Standardzeitraum: die letzten 28 vollständigen Tage bis gestern. Jede Antwort nennt in period den Zeitraum, den sie verwendet hat. Ein to in der Zukunft wird bei heute abgeschnitten und mit clamped_to_today markiert, ein from nach heute ist ein Fehler.
• Abdeckung: Ein Zeitraum, der beginnt, bevor das Projekt vollständige Daten hat, ist mit starts_before_data und data_from markiert, und gegen ihn wird keine prozentuale Veränderung berechnet. Wochen und Monate, die nur einen Teil ihrer Spanne abdecken, sind mit partial markiert.
• Zählungen: unique_sessions sind Besucher, die pro Tag einmal gezählt werden. Über einen längeren Zeitraum kann dieselbe Person also an mehreren Tagen gezählt werden. Die Zahlen von list_elements, preview_feature_rule und preview_funnel sind Events, keine Besucher. Die Zahlen von list_click_problems sind Seitenaufrufe: Jedes Problem zählt pro Element und Seitenaufruf einmal.
• Zeitraumgrenze: Diese drei Tools lesen rohe Events und akzeptieren höchstens 92 Tage pro Aufruf, ebenso list_click_problems.
• Stunden: run_insights_query mit group_by hour und get_feature_timeseries mit granularity hour liefern die Stunden in der Zeitzone des Projekts. Ein Tag mit Zeitumstellung hat 23 oder 25 Stunden. Beide akzeptieren höchstens 31 Tage, from und to eingeschlossen.

Ergebnisse und Fehler

• Ein Tool-Ergebnis enthält seine Daten als structuredContent und dasselbe JSON als Text, für Clients, die nur Text lesen. Ausgabeschemas werden nicht veröffentlicht.
• Lehnt die API einen Aufruf ab, etwa einen unbekannten Funnel oder einen ungültigen Filter, hat das Ergebnis isError: true und die eigene Meldung der API als Text, damit sich der Assistent korrigieren kann.
• Argumente werden gegen das Eingabeschema des Tools geprüft, bevor etwas passiert. Unbekannte Argumente werden abgelehnt statt ignoriert, und ein unbekanntes Tool ist ein JSON-RPC-Fehler.

Tools

Ihr Client bekommt jedes Tool mit seinem vollständigen Eingabeschema über tools/list. Die Tools tragen die Hinweise von MCP: Lesende Tools sind mit readOnlyHint markiert, Tools, die etwas ändern oder löschen, mit destructiveHint. Daran erkennen Clients, wann sie Sie vorher fragen sollten. openWorldHint ist überall false, weil die Tools immer nur das eine Projekt berühren.

Lesen, mit jeder Verbindung und jedem Schlüssel

Die drei Tools für Klickprobleme nehmen die identity einer Zeile aus list_click_problems: alle fünf Felder genau so, wie sie zurückkamen, null dort, wo null steht. Eine Identität, in der ein Feld fehlt, wird abgelehnt, weil sie kein echtes Element bezeichnen würde. Zeilen, die mit group_by: selector aufgelistet werden, haben keine Identität. Erledigen und Ignorieren blenden eine Zeile nur aus. Keine Zahl ändert sich, und kein Event wird gelöscht.

Prompts und Ressourcen

• product_review, mit den optionalen Argumenten from, to und project in dieser Reihenfolge: eine feste Auswertung der Gesamtveränderung, der Features mit der größten Bewegung, der Absprünge in Funnels, der meistgenutzten Elemente, die noch zu keinem Feature zählen, und der nächsten Schritte, die sich lohnen. Die Auswertung ist unter Fragen zu Ihren Daten beschrieben. Jede Verbindung und jeder Schlüssel.
• setup_project, mit den optionalen Argumenten instrument, focus und project in dieser Reihenfolge. instrument ist code (data-track im Code, als Änderung zur Prüfung), rules (nur Feature-Regeln: Der Code wird nie bearbeitet, und es wird keine Änderung daran vorgeschlagen) oder leer, dann wählt der Assistent. focus nennt, worauf es am meisten ankommt. Das Vorgehen ist unter Projekt einrichten lassen beschrieben. Nur mit Schreibrechten.
• privatrak://guide/instrumentation (Markdown): wie der Tracker Dinge benennt, worin sich Feature-Regeln von data-track unterscheiden und welche Grenzen für Funnels und Dashboards gelten. Jeder Schlüssel.

Beim Verbinden schickt der Server außerdem Anweisungen, die dem Assistenten sagen, dass er zuerst get_project aufrufen soll und wie er die Zahlen ehrlich liest. Bei einer OAuth-Verbindung nennen sie auch die Projekte, die sie umfasst.

Setup-Läufe

Ein Setup-Lauf bündelt die Änderungen eines Assistenten, damit sie sich in einem Schritt rückgängig machen lassen. Jede Änderung über ein schreibendes Tool gehört zu einem Lauf.

• Starten Sie einen mit start_setup_run und geben Sie seine run_id bei jedem Schreibaufruf mit. Ein Schreibaufruf ohne run_id startet einen Lauf der Art chat und gibt seine ID mit run_started: true zurück. Schlägt der Schreibaufruf fehl, wird der gestartete Lauf wieder entfernt.
• Über die REST-API entspricht das dem Header X-Setup-Run-ID bei jedem Schreibzugriff auf Feature-Regeln, Funnels, Dashboards, Widgets oder Klickprobleme. Schreibzugriffe ohne ihn werden nicht festgehalten und lassen sich so nicht rückgängig machen.
• undo_setup_run läuft standardmäßig mit dry_run: true, meldet also, was passieren würde, und ändert nichts. Das echte Rückgängigmachen läuft vom Neuesten zum Ältesten in einer Transaktion: Es entfernt, was der Lauf angelegt hat, setzt zurück, was er geändert hat, und stellt wieder her, was er gelöscht hat, mit der ursprünglichen ID. Was jemand anderes seitdem geändert hat, wird übersprungen und gemeldet. Ein Lauf lässt sich einmal rückgängig machen und nimmt danach keine Änderungen mehr an. Im Dashboard finden Sie dasselbe Rückgängigmachen auf der Seite Änderungen durch KI.
• Die gezählten Tage eines Funnels lassen sich nicht wiederherstellen. Das Rückgängigmachen meldet sie vorher und nachher als funnel_history und funnel_days_lost.
• Ein Klickproblem, das der Lauf als erledigt markiert oder ignoriert hat, ist nach dem Rückgängigmachen wieder offen. Eines, das der Lauf wieder geöffnet oder zwischen erledigt und ignoriert umgestellt hat, wird so zurückgesetzt, wie es war. Hat es seitdem jemand anderes erledigt, ignoriert oder wieder geöffnet, lässt das Rückgängigmachen es in Ruhe und meldet es.
• Die Limits des Tarifs gelten für Schreibzugriffe und für das Rückgängigmachen gleichermaßen. get_project liefert slots_left für Feature-Regeln, Funnels, Dashboards und Widgets.

Schlüssel in den Einstellungen Ihres Assistenten

Diese Einstellungen betreffen Assistenten, die mit einem API-Schlüssel verbunden sind. Eine Verbindung per Anmeldung umfasst alle Projekte, die die Person erlaubt hat, und braucht nichts davon. Jeder Schlüssel gehört zu einem Projekt. Ein Assistent sollte also den Schlüssel des Projekts verwenden, an dessen Code er arbeitet.

• Claude Code speichert die Verbindung für den Ordner, in dem Sie claude mcp add ausführen. Führen Sie den Befehl in jedem Projektordner mit dem Schlüssel dieses Projekts aus.
• Cursor liest .cursor/mcp.json aus dem Ordner des jeweiligen Projekts. Jedes Projekt hat damit seine eigene Datei und seinen eigenen Schlüssel.
• Codex verwendet eine Verbindung in allen Ordnern, solange ein Projekt keine eigene nennt. Wählen Sie für jedes Projekt einen eigenen Variablennamen, etwa PRIVATRAK_API_KEY_SHOP, und speichern Sie den Schlüssel dieses Projekts darunter, wie bei PRIVATRAK_API_KEY. Legen Sie dann im Projektordner die Datei .codex/config.toml an:

[mcp_servers.privatrak]
url = "https://api.privatrak.com/mcp"
bearer_token_env_var = "PRIVATRAK_API_KEY_SHOP"

Die Datei nennt nur die Variable, nicht den Schlüssel, und darf deshalb in Ihr Code-Repository. Codex liest sie nur in einem Ordner, dem Sie vertrauen, und fragt Sie danach, wenn Sie Codex dort zum ersten Mal starten.

Schlüssel wechseln

Ein Assistent trägt Privatrak unter dem Namen privatrak ein und hält damit immer nur einen Schlüssel. Um zwischen einem KI-Assistenten-Schlüssel und einem Schlüssel mit vollem Zugriff zu wechseln, ersetzen Sie den alten Schlüssel, statt einen zweiten hinzuzufügen. In Claude Code führen Sie im Projektordner claude mcp remove privatrak und danach den neuen Befehl aus. In Codex ändern Sie den Schlüssel in der Zeile, die ihn speichert. In Cursor ersetzen Sie den Schlüssel in der mcp.json.

Möchten Sie sich anmelden, statt einen Schlüssel zu verwenden, entfernen Sie zuerst die Verbindung mit dem Schlüssel: claude mcp remove privatrak in Claude Code, codex mcp remove privatrak in Codex. In Cursor ersetzen Sie den Eintrag privatrak in der mcp.json durch den aus KI-Assistenten verbinden. Melden Sie sich dann wie dort beschrieben an und widerrufen Sie den alten Schlüssel auf der Seite API-Schlüssel.