메인 콘텐츠로 건너뛰기
ClickStack에는 AI 어시스턴트가 관측성 데이터와 상호작용할 수 있도록 하는 기본 제공 Model Context Protocol (MCP) 서버가 포함되어 있습니다. 연결되면 AI 어시스턴트는 자연어만으로 로그, 트레이스, 메트릭을 쿼리하고, 대시보드와 알림을 관리하며, 데이터 소스를 탐색하고, 저장된 검색을 활용할 수 있습니다. 이를 통해 Claude Code, Cursor, 또는 MCP 호환 클라이언트를 사용해 개발 환경을 벗어나지 않고도 인시던트를 조사하고, 대시보드를 구축하며, 관측성 환경을 관리할 수 있습니다.

​
지원 현황

MCP 서버는 다음 ClickStack 배포 유형에서 사용할 수 있습니다:
배포상태
Open Source ClickStack사용 가능
BYOC (Bring Your Own Cloud)사용 가능
Managed ClickStack출시 예정
HyperDX v1 (hyperdx.io)지원 안 함
Managed ClickStackManaged ClickStack의 MCP 서버 지원은 현재 개발 중이며 곧 제공될 예정입니다. 이 페이지의 지침은 Open Source 및 BYOC 배포에 적용됩니다.

​
사전 요구 사항

MCP 클라이언트를 연결하기 전에 다음이 필요합니다:
  • 실행 중인 ClickStack 인스턴스(배포에서 설정 옵션 참조)
  • Personal API Access Key — HyperDX의 Team Settings → API Keys → Personal API Access Key에서 확인할 수 있습니다
Personal API Access Key는 Team Settings에서 찾을 수 있는 수집 API key와 다릅니다. 수집 API key는 OpenTelemetry collector로 전송되는 텔레메트리 데이터를 인증하는 데 사용됩니다.

​
엔드포인트

MCP 서버는 ClickStack 프론트엔드 URL의 /api/mcp 경로에서 이용할 수 있습니다: 예를 들어, 기본 로컬 배포에서는 다음과 같습니다: 기본 설정을 변경한 경우 localhost:8080을 인스턴스에 맞는 호스트와 포트로 바꾸십시오.
이 페이지의 예시는 프론트엔드 앱 URL(기본 포트 8080)을 사용합니다. 백엔드를 통해 <BACKEND_URL>/mcp로 MCP 서버에 직접 접근할 수도 있지만, 모든 배포에서 백엔드가 노출되는 것은 아니므로 이 문서에서는 프론트엔드 경로를 사용합니다.
MCP 서버는 Bearer token 인증을 사용하는 Streamable HTTP 전송 방식을 사용합니다.

​
MCP 클라이언트 연결하기

아래 예시에서는 널리 사용되는 MCP 클라이언트를 구성하는 방법을 보여줍니다. <YOUR_CLICKSTACK_URL>은 인스턴스 URL(예: http://localhost:8080)로, <YOUR_API_KEY>는 Personal API Access Key로 바꾸십시오.

​
Claude Code

claude mcp add --transport http hyperdx <YOUR_CLICKSTACK_URL>/api/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"

​
Cursor

프로젝트의 .cursor/mcp.json 파일이나 Cursor 전역 설정에 다음 내용을 추가하십시오: 
{
  "mcpServers": {
    "hyperdx": {
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

​
OpenCode

다음을 opencode.json 설정에 추가하십시오: 
{
  "mcp": {
    "hyperdx": {
      "type": "http",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

​
기타 클라이언트

Streamable HTTP 전송을 지원하는 모든 MCP 클라이언트가 연결할 수 있습니다. 다음과 같이 구성하십시오.
  • URL: <YOUR_CLICKSTACK_URL>/api/mcp
  • 헤더: Authorization: Bearer <YOUR_API_KEY>

​
MCP로 무엇을 할 수 있나요?

연결이 완료되면 AI 어시스턴트는 ClickStack의 핵심 영역 전반에 걸친 다양한 도구에 접근할 수 있습니다. 여기에는 다음이 포함됩니다.
  • 데이터 쿼리 — ClickStack의 쿼리 빌더, 검색 구문 또는 raw SQL을 사용해 로그, 트레이스, 메트릭을 검색하고 집계합니다.
  • 데이터 소스 — 사용 가능한 데이터 소스, 데이터베이스 연결, 컬럼 스키마, 속성 키를 나열합니다.
  • 대시보드 — 타일과 함께 대시보드를 생성, 업데이트, 삭제하고 내용을 확인합니다.
  • 알림 — 평가 이력과 함께 알림을 생성, 업데이트하고 내용을 확인합니다.
  • 저장된 검색 — 재사용 가능한 저장된 검색 정의를 생성, 업데이트하고 내용을 확인합니다.
  • 웹훅 — 알림 알림을 위한 사용 가능한 웹훅 대상을 나열합니다.
  • 팀 — 현재 사용자가 속한 팀을 나열하고 활성 팀을 식별합니다.
제공되는 도구의 구체적인 구성은 시간이 지나면서 확장될 수 있습니다. MCP 클라이언트는 연결 시 사용 가능한 도구를 자동으로 탐색합니다.

​
여러 팀 사용

기본적으로 MCP 요청은 사용자의 기본 팀 컨텍스트에서 실행됩니다. 여러 팀에 속해 있다면 Authorization 헤더와 함께 팀 ID로 설정한 x-hdx-team 헤더를 전달해 특정 팀을 대상으로 지정할 수 있습니다. 이 헤더를 생략하면 기본 팀이 사용됩니다. 속해 있지 않은 팀을 지정하면 요청이 401 오류와 함께 거부됩니다. MCP 클라이언트의 팀 목록 도구를 사용하면 액세스할 수 있는 팀과 현재 활성 상태인 팀을 확인할 수 있습니다.

​
문제 해결

  • Personal API Access Key를 사용하고 있는지 확인하십시오(수집 API key가 아닙니다).
  • Authorization 헤더에 key가 Bearer 토큰으로 포함되어 있는지 확인하십시오.
  • ClickStack 인스턴스가 실행 중이며 구성한 URL에서 접근 가능한지 확인하십시오.
MCP 서버는 사용자당 분당 600개의 요청으로 속도 제한을 적용합니다. 이 제한을 초과하면 요청이 일시적으로 거부됩니다. 요청 빈도를 줄이거나 다시 시도하기 전에 잠시 기다리십시오.
team ID가 올바른지, 그리고 사용자 계정이 해당 team의 구성원인지 확인하십시오.
  • MCP 클라이언트가 Streamable HTTP 전송을 지원하는지 확인하십시오. stdio 전송만 지원하는 구형 클라이언트는 작동하지 않습니다.
  • ClickStack을 로컬에서 실행 중이라면, 구성된 URL(기본값은 http://localhost:8080)에서 앱에 접근할 수 있는지 확인하십시오.
  • 로드 밸런서 또는 리버스 프록시 뒤에서 실행되는 BYOC 배포에서는 /api/mcp 경로가 차단되거나 재작성되지 않는지 확인하십시오.
마지막 수정일 2026년 6월 10일