Servidor MCP

1. Què hi pot fer un agent

Apunti un client de Model Context Protocol a l’endpoint i podrà fer preguntes com «quina pàgina genera més clics de ràbia aquest mes» o «mostra’m tres sessions d’Alemanya de més de dos minuts», i després donar-li un enllaç per reproduir la sessió.

Eina	Respon
mp_projects	quins projectes pot llegir aquesta clau
mp_overview	sessions, persones, visualitzacions de pàgina, durada i senyals de frustració
mp_sessions	sessions recents amb enllaços de reproducció, filtrades per país, dispositiu o durada
mp_session	una sessió: pàgines en ordre, esdeveniments, origen i dispositiu
mp_pages	pàgines per visualitzacions, amb visitants únics
mp_frustration	clics de ràbia, clics sense efecte i errors JavaScript agrupats per pàgina
mp_goals	els seus objectius i quantes vegades s’ha assolit cadascun

2. Connexió

L’endpoint accepta POST a /mcp i utilitza Streamable HTTP, versió de protocol 2026-07-28.

L’autenticació és una clau d’API de lectura normal de MousePlayer: del mateix tipus que crea a Configuració, Claus d’API, i del mateix tipus que accepta l’API REST. No hi ha cap segona credencial. Revocar la clau revoca l’accés de l’agent en el mateix moment.

Després, activi el projecte

Una clau d’API obre tot el seu espai de treball. Aquesta integració, expressament, no: cada projecte té un interruptor propi a la pàgina d’integracions, desactivat per defecte. Un projecte no activat no apareix a mp_projects i no es pot llegir encara que l’agent n’endevini l’identificador.

No és burocràcia. Una clau d’API en un script de desplegament es troba en un lloc que vostè controla; una clau d’API al fitxer de configuració d’un agent alimenta el context d’un model, i això implica una custòdia molt més laxa. Autoritzar un projecte cada vegada és el control adequat.

3. Només lectura i per què això no canviarà

Cap de les set eines no escriu res. No hi ha supressió, exportació ni canvis de configuració darrere d’aquest endpoint; no perquè ens hagi faltat temps, sinó perquè una eina que un agent pot cridar també és una eina que pot cridar per error.

Què no retorna

Cap gravació en si, cap captura del DOM ni cap adreça IP. L’agent rep allò que una persona veu a la interfície, més l’enllaç per mirar la resta.

Límits de peticions i d’interval

Seixanta peticions per minut per clau, igual que l’API REST. L’interval de temps està limitat a 365 dies i la llista de resultats a 200 files; una resposta truncada ho indica, perquè una llista truncada sense avís sembla exactament una de completa.

4. Per a qui desenvolupa el client

Tres mètodes: server/discover, tools/list, tools/call. Sense sessions, sense flux GET, sense Last-Event-ID perquè pertanyen a versions del protocol fins a 2025-11-25 i no formen part d’aquesta. Un GET o DELETE rep 405.

Cada POST conté MCP-Protocol-Version, Mcp-Method i, per a tools/call, Mcp-Name, i cadascun ha de coincidir amb el cos. Una discrepància és 400 amb l’error JSON-RPC -32020; una versió no compatible és 400 amb -32022 i la llista de versions que sí que admetem, perquè el client en pugui triar una i reintentar-ho.

Dos tipus d’error, expressament

Una petició mal formada o una eina desconeguda és un error JSON-RPC. «Aquest projecte no està autoritzat» o «la sessió no existeix» es retorna com a resultat normal amb isError: true perquè un model es pot recuperar del segon tipus consultant mp_projects i tornant-ho a provar, però no es pot recuperar del primer.

Els resultats contenen tant structuredContent com les mateixes dades serialitzades en un bloc de text, perquè els clients antics continuïn veient informació útil.