Server MCP
Consenta a un agente IA di leggere i dati analitici: sette strumenti tramite Model Context Protocol, tutti di sola lettura, autenticati con una chiave API già disponibile.
1. Cosa può fare un agente
Colleghi un client Model Context Protocol all’endpoint: potrà chiedere «quale pagina genera più clic di rabbia questo mese» o «mostri tre sessioni dalla Germania oltre due minuti», ricevendo un link per riprodurle.
| Strumento | Risposte |
|---|---|
mp_projects | quali progetti può leggere la chiave |
mp_overview | sessioni, persone, visualizzazioni, durata e segnali di frustrazione |
mp_sessions | sessioni recenti con link, filtrate per paese, dispositivo o durata |
mp_session | una sessione: pagine in ordine, eventi, origine e dispositivo |
mp_pages | pagine per visualizzazioni, con visitatori unici |
mp_frustration | clic di rabbia, clic a vuoto ed errori JavaScript per pagina |
mp_goals | obiettivi e numero di volte in cui sono stati raggiunti |
Ogni sessione presentata dall’agente include un link apribile da una persona. Un agente che riassume ciò che vede è utile; uno che mostra anche i venti secondi alla base del riassunto è verificabile.
2. Connessione
L’endpoint accetta POST su /mcp e usa Streamable HTTP, versione del protocollo 2026-07-28.
L’autenticazione usa una normale chiave API di lettura MousePlayer, dello stesso tipo creato sotto Impostazioni, Chiavi API e accettato dall’API REST. Non serve una seconda credenziale. Revocare la chiave revoca immediatamente l’accesso dell’agente.
Poi attivi il progetto
Una chiave API apre l’intera area. Questo accesso volutamente no: ogni progetto ha un interruttore nelle integrazioni, spento per impostazione predefinita. Un progetto non attivo non compare in mp_projects e non è leggibile neppure indovinandone l’ID.
Non è burocrazia. Una chiave in uno script di deploy sta in un luogo controllato; nella configurazione di un agente alimenta il contesto di un modello, una custodia molto meno rigorosa. Abilitare un progetto alla volta è il controllo adeguato.
3. Sola lettura e perché non cambierà
Nessuno dei sette strumenti scrive. Nessuna eliminazione, esportazione o modifica di configurazione dietro questo endpoint: non per mancanza di tempo, ma perché un agente può chiamare uno strumento anche per errore.
Cosa non restituisce
Nessuna registrazione, istantanea DOM o indirizzo IP. L’agente riceve ciò che una persona vede nell’interfaccia e il link per guardare il resto.
Limiti di frequenza e intervallo
Sessanta richieste al minuto per chiave, come l’API REST. Intervalli limitati a 365 giorni ed elenchi a 200 righe; le risposte troncate lo dichiarano, perché un elenco accorciato silenziosamente sembra completo.
4. Per chi sviluppa il client
Tre metodi: server/discover, tools/list, tools/call. Nessuna sessione, flusso GET o Last-Event-ID - appartengono alle versioni fino a 2025-11-25 e non fanno parte di questa. GET o DELETE riceve 405.
Ogni POST include MCP-Protocol-Version, Mcp-Method e, per tools/call, Mcp-Name, e ciascuno deve corrispondere al corpo. Una discordanza restituisce 400 con errore JSON-RPC -32020; una versione non supportata restituisce 400 con -32022 e l’elenco delle versioni supportate, per sceglierne una e riprovare.
Due tipi di errore, volutamente
Una richiesta malformata o uno strumento sconosciuto è un errore JSON-RPC. «Progetto non abilitato» o «sessione inesistente» ritorna come risultato normale con isError: true - un modello può recuperare dal secondo tipo chiedendo mp_projects e riprovando, ma non dal primo.
I risultati contengono sia structuredContent sia gli stessi dati serializzati in un blocco di testo, utili anche ai client meno recenti.
Tutti i marchi citati appartengono ai rispettivi titolari. MousePlayer non ha rapporti commerciali con questi fornitori.