MCP 서버

1. 에이전트가 할 수 있는 일

Model Context Protocol 클라이언트를 엔드포인트에 연결하면 “이번 달에 분노 클릭이 가장 많이 발생한 페이지는?” 또는 “독일에서 2분을 넘게 진행된 세션 3개를 보여 줘” 같은 질문을 하고, 세션을 재생하는 링크를 받을 수 있습니다.

도구	제공하는 정보
mp_projects	이 키로 읽을 수 있는 프로젝트
mp_overview	세션, 사람, 페이지 조회, 지속 시간, 좌절 신호
mp_sessions	국가, 기기 또는 길이로 필터링한 최근 세션 및 재생 링크
mp_session	세션 하나: 순서대로 나열된 페이지, 이벤트, 유입 소스, 기기
mp_pages	조회 수 기준 페이지 및 순 방문자
mp_frustration	페이지별로 묶은 분노 클릭, 무반응 클릭 및 JavaScript 오류
mp_goals	목표 및 각 목표의 달성 횟수

2. 연결

엔드포인트는 /mcp 에서 POST를 받고 Streamable HTTP를 사용합니다. 프로토콜 버전은 2026-07-28입니다.

일반 MousePlayer 읽기 API 키로 인증합니다. 설정의 API 키에서 만드는 키이며, REST API에 사용하는 것과 같은 종류입니다. 두 번째 자격 증명은 없습니다. 키를 폐기하면 같은 순간 에이전트의 접근 권한도 사라집니다.

그다음 프로젝트를 켜세요

API 키는 워크스페이스 전체를 열어 줍니다. 이 기능은 의도적으로 그렇게 하지 않습니다. 각 프로젝트에는 연동 페이지의 자체 스위치가 있으며 기본값은 꺼짐입니다. 켜지 않은 프로젝트는 mp_projects 에 표시되지 않으며, 에이전트가 ID를 추측해도 읽을 수 없습니다.

이는 번거로운 절차를 추가하려는 것이 아닙니다. 배포 스크립트의 API 키는 사용자가 통제하는 한곳에 있지만, 에이전트 설정 파일의 API 키는 모델 컨텍스트에 들어가므로 훨씬 느슨하게 관리됩니다. 프로젝트를 하나씩 허용하는 것이 이에 맞는 통제 방식입니다.

3. 읽기 전용이며, 앞으로도 유지하는 이유

7개 도구 중 어떤 것도 쓰기 작업을 하지 않습니다. 이 엔드포인트에는 삭제, 내보내기 또는 설정 변경 기능이 없습니다. 시간이 부족해서가 아닙니다. 에이전트가 호출할 수 있는 도구는 실수로도 호출할 수 있기 때문입니다.

반환하지 않는 항목

녹화 자체, DOM 스냅샷 및 IP 주소는 반환하지 않습니다. 에이전트는 사용자가 인터페이스에서 보는 내용과 나머지를 시청할 링크를 받습니다.

요청 및 범위 한도

REST API와 동일하게 키당 분당 60개 요청입니다. 시간 범위는 365일, 결과 목록은 200행으로 제한됩니다. 조용히 잘린 목록은 완전한 목록과 똑같아 보이므로, 답변이 잘리면 이를 명시합니다.

4. 클라이언트 개발자를 위한 정보

세 가지 메서드: server/discover, tools/list, tools/call. 세션과 GET 스트림은 없으며 Last-Event-ID 도 사용하지 않습니다. 이는 2025-11-25까지의 프로토콜 버전에 해당하며 이 버전에는 포함되지 않습니다. GET 또는 DELETE는 405를 반환합니다.

모든 POST에는 MCP-Protocol-Version, Mcp-Method 및 tools/call인 경우 Mcp-Name이 포함되며, 각각 본문과 일치해야 합니다. 일치하지 않으면 400 과 JSON-RPC 오류 -32020을 반환하고, 지원하지 않는 버전이면 400 과 -32022 및 지원하는 버전 목록을 반환합니다. 클라이언트는 그중 하나를 선택해 재시도할 수 있습니다.

의도적으로 나눈 두 종류의 오류

잘못된 요청이나 알 수 없는 도구는 JSON-RPC 오류입니다. “이 프로젝트는 허용되지 않음”이나 “해당 세션 없음”은 isError: true 가 포함된 일반 결과로 반환됩니다. 모델은 mp_projects 에 질의한 뒤 재시도하여 두 번째 종류의 오류에서는 복구할 수 있지만, 첫 번째 종류에서는 그럴 수 없기 때문입니다.

결과에는 structuredContent 와 같은 데이터를 텍스트 블록으로 직렬화한 내용이 모두 포함되므로, 구형 클라이언트도 유용한 내용을 볼 수 있습니다.