MCP-server

1. Wat een agent hiermee kan doen

Verbind een Model Context Protocol-client met het endpoint en die kan vragen stellen zoals “welke pagina veroorzaakt deze maand de meeste woedeklikken” of “toon drie sessies uit Duitsland die langer dan twee minuten duurden”, en u vervolgens een link geven om de sessie af te spelen.

Tool	Geeft antwoord op
mp_projects	welke projecten deze sleutel mag lezen
mp_overview	sessies, personen, paginaweergaven, duur en frustratiesignalen
mp_sessions	recente sessies met afspeellinks, gefilterd op land, apparaat of duur
mp_session	één sessie: pagina’s op volgorde, gebeurtenissen, bron en apparaat
mp_pages	pagina’s op aantal weergaven, met unieke bezoekers
mp_frustration	woedeklikken, dode klikken en JavaScript-fouten gegroepeerd per pagina
mp_goals	uw doelen en hoe vaak elk is bereikt

2. Verbinden

Het endpoint accepteert POST op /mcp en gebruikt Streamable HTTP, protocolversie 2026-07-28.

Authenticatie verloopt via een gewone MousePlayer-API-sleutel met leesrechten, hetzelfde type dat u maakt onder Instellingen, API-sleutels en dat de REST-API accepteert. Er is geen tweede toegangsgegeven. Als u de sleutel intrekt, verliest de agent op hetzelfde moment toegang.

Schakel daarna het project in

Een API-sleutel opent uw hele werkruimte. Deze toegang doet dat bewust niet: elk project heeft een eigen schakelaar op de integratiepagina, standaard uitgeschakeld. Een project dat niet is ingeschakeld, verschijnt niet in mp_projects en kan niet worden gelezen, ook niet als de agent de ID raadt.

Dat is geen bureaucratie. Een API-sleutel in een deployscript staat op één plek die u beheert; een sleutel in het configuratiebestand van een agent voedt de context van een model, en dat biedt veel minder directe controle. Eén project tegelijk vrijgeven is de bijpassende beheersmaatregel.

3. Alleen-lezen, en waarom dat zo blijft

Geen van de zeven tools schrijft iets. Achter dit endpoint zitten geen verwijdering, export of configuratiewijzigingen. Niet omdat we geen tijd meer hadden, maar omdat een tool die een agent kan aanroepen ook per ongeluk kan worden aangeroepen.

Wat niet wordt teruggegeven

Geen opnamen zelf, geen DOM-momentopnamen en geen IP-adressen. De agent krijgt wat een persoon in de interface ziet, plus de link om de rest te bekijken.

Limieten voor verzoeken en bereik

Zestig verzoeken per minuut per sleutel, hetzelfde als de REST-API. Een tijdsbereik is beperkt tot 365 dagen en een resultatenlijst tot 200 rijen. Een afgekapt antwoord vermeldt dit, want een ongemerkt ingekorte lijst ziet er precies zo uit als een volledige.

4. Voor wie de client bouwt

Drie methoden: server/discover, tools/list, tools/call. Geen sessies, geen GET-stream en geen Last-Event-ID ; die horen bij protocolversies tot en met 2025-11-25 en maken geen deel uit van deze versie. GET of DELETE krijgt 405.

Elke POST bevat MCP-Protocol-Version, Mcp-Method en, voor tools/call, Mcp-Name, en elke waarde moet overeenkomen met de inhoud. Een afwijking levert 400 met JSON-RPC-fout -32020op; een niet-ondersteunde versie levert 400 met -32022 en de lijst met ondersteunde versies op, zodat uw client er een kan kiezen en het opnieuw kan proberen.

Bewust twee soorten fouten

Een onjuist gevormd verzoek of een onbekende tool is een JSON-RPC-fout. “Dit project is niet vrijgegeven” of “sessie bestaat niet” komt terug als normaal resultaat met isError: true , omdat een model van het tweede type kan herstellen door mp_projects op te vragen en het opnieuw te proberen, maar niet van het eerste.

Resultaten bevatten zowel structuredContent als dezelfde gegevens geserialiseerd in een tekstblok, zodat ook oudere clients nog iets bruikbaars zien.