MCP Server

Framedash MCP Server는 LLM이 Framedash 텔레메트리 데이터에 직접 접근할 수 있도록 하는 Model Context Protocol 서버입니다. 12개의 읽기 전용 도구와 4개의 리소스를 제공하며, 자연어로 게임 분석 데이터를 조회할 수 있습니다.

설정

Claude Desktop

claude_desktop_config.json에 다음을 추가합니다:

{
  "mcpServers": {
    "framedash": {
      "command": "npx",
      "args": ["-y", "@framedash/mcp-server"],
      "env": {
        "FRAMEDASH_API_KEY": "fd_xxx",
        "FRAMEDASH_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

VS Code (Claude Extension)

VS Code 설정에 다음을 추가합니다:

{
  "claude.mcpServers": {
    "framedash": {
      "command": "npx",
      "args": ["-y", "@framedash/mcp-server"],
      "env": {
        "FRAMEDASH_API_KEY": "fd_xxx",
        "FRAMEDASH_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

Claude Code

claude mcp 명령으로 서버를 등록합니다:

claude mcp add framedash \
  -e FRAMEDASH_API_KEY=fd_xxx \
  -e FRAMEDASH_PROJECT_ID=your-project-uuid \
  -- npx -y @framedash/mcp-server

모든 도구(raw SQL query 포함)를 사용하려면 Full 프리셋 키를, raw SQL 이외의 분석 도구에는 Read-only 키를 사용하세요.

호스팅 원격 엔드포인트

Framedash는 원격 MCP 서버도 호스팅하므로, 원격 서버와 OAuth를 지원하는 MCP 클라이언트는 로컬 설치가 필요 없습니다. 요청은 Streamable HTTP 트랜스포트로 POST {origin}/api/mcp(기본값 https://app.framedash.dev/api/mcp)에 보냅니다. 이 엔드포인트는 스테이트리스이며 세션 ID를 사용하지 않습니다.

인증은 OAuth 2.1 Bearer만 지원하며, 여기서는 API 키를 받지 않습니다. 401 응답에는 WWW-Authenticate 헤더가 포함되고 그 resource_metadata는 {origin}/.well-known/oauth-protected-resource를 가리키므로, MCP 인가 사양을 구현한 클라이언트는 인가 서버를 스스로 검색하고 동적 클라이언트 등록을 포함해 OAuth 플로우를 자동으로 완료할 수 있습니다. 도구 호출은 REST API와 동일하게 부여된 scope와 프로젝트 범위에서 실행됩니다. GET과 DELETE는 405를 반환합니다. raw SQL query 도구는 원격 엔드포인트에서 사용할 수 없습니다. 이 도구는 data:admin scope가 필요한데 OAuth 토큰은 이를 가질 수 없으므로, raw SQL은 계속해서 stdio 서버와 Full API 키로 실행하세요.

원격 엔드포인트에는 계정 단위의 플랜별 속도 제한에 더해, 인증 전 입구에 IP 단위의 별도 속도 제한이 있습니다. 자세한 내용은 API 개요의 속도 제한을 참고하세요.

원격 서버와 OAuth를 지원하는 MCP 클라이언트에는 stdio 서버 대신 설치가 필요 없는 이 호스팅 엔드포인트를 사용하세요. API 키 기반이나 로컬 구성에는 계속해서 stdio 서버(npx -y @framedash/mcp-server)가 적합합니다.

환경 변수

변수	필수	설명
`FRAMEDASH_API_KEY`	예	MCP 도구에 필요한 scope를 가진 API 키. Full 프리셋은 raw SQL `query`를 포함한 모든 도구를 허용하고, Read-only 프리셋은 raw SQL 이외의 분석 도구를 허용합니다.
`FRAMEDASH_PROJECT_ID`	아니오	기본 프로젝트 UUID
`FRAMEDASH_BASE_URL`	아니오	API 기본 URL (기본값: `https://app.framedash.dev`)

도구

쿼리

도구	설명	인수
`query`	ClickHouse events 테이블에 읽기 전용 SQL 쿼리 실행	`sql` (string, 필수), `project_id` (uuid, 선택), `limit` (int 1-1000, 기본값 100)

분석

도구	설명	인수
`get_dashboard`	프로젝트 KPI (DAU, MAU, 세션, 이벤트)	`project_id` (uuid, 선택), `days` (7/14/30/90, 기본값 30)
`get_retention`	코호트 리텐션 분석	`project_id` (uuid, 선택), `days` (7/14/30/90, 기본값 30)
`get_funnel`	이벤트 퍼널 분석	`project_id` (uuid, 선택), `steps` (string, 필수: 쉼표 구분 2-8개 이벤트명), `days` (7/14/30/90, 기본값 30)
`get_insights`	차원별 집계 인사이트	`project_id` (uuid, 선택), `metric` (count/unique_players, 필수), `group_by` (string, 필수: event_name, platform 등), `days` (7/14/30/90, 기본값 30), `limit` (10/20/50), `event_name` (string, 선택)
`get_heatmap`	맵의 히트맵 그리드 데이터	`project_id` (uuid, 선택), `map_id` (string, 필수), `cell_size` (5/10/25/50, 기본값 25), `days` (1/7/14/30, 기본값 7), `event_name` (string, 선택)

프로젝트

도구	설명	인수
`list_projects`	API 키에 연결된 프로젝트 표시	없음
`get_project_status`	프로젝트 상태 개요 (이벤트 수, 마지막 이벤트 시간)	`project_id` (uuid, 선택)
`list_maps`	프로젝트의 맵 목록	`project_id` (uuid, 선택)
`list_content`	콘텐츠 레지스트리 항목 목록	`project_id` (uuid, 선택), `type` (string, 선택)

알림

도구	설명	인수
`list_alerts`	알림 규칙 목록	`project_id` (uuid, 선택)
`get_alert_history`	알림 트리거/해제 이력	`project_id` (uuid, 선택), `limit` (int 1-100, 기본값 50)

리소스

framedash:// URI 스킴으로 MCP 리소스를 통해 데이터에 접근할 수 있습니다:

URI	설명
`framedash://projects`	API 키에 연결된 프로젝트
`framedash://projects/{projectId}/maps`	좌표 및 범위 포함 맵 목록
`framedash://projects/{projectId}/content`	콘텐츠 레지스트리 항목
`framedash://projects/{projectId}/status`	프로젝트 상태 및 통계

사용 예시

MCP Server를 구성하면 자연어로 데이터를 조회할 수 있습니다:

프롬프트 예시	사용되는 도구
”지난 7일간 DAU를 보여줘”	`get_dashboard` (days=7)
“spawn에서 death까지의 퍼널을 분석해줘”	`get_funnel` (steps=“player_spawn,player_death”)
“플랫폼별 이벤트 수를 알려줘”	`get_insights` (metric=count, group_by=platform)
“맵의 FPS 히트맵을 보여줘”	`get_heatmap` (map_id=…)
”최근 알림 이력을 확인해줘”	`get_alert_history`

다음 단계

API 레퍼런스: REST API 상세 정보
CLI 레퍼런스: 커맨드라인 도구

AI 에이전트용: llms.txt