ClickStack MCP 서버

ClickStack에는 AI 어시스턴트가 관측성 데이터와 상호작용할 수 있도록 하는 기본 제공 Model Context Protocol (MCP) 서버가 포함되어 있습니다. 연결되면 AI 어시스턴트는 자연어만으로 로그, 트레이스, 메트릭을 쿼리하고, 대시보드와 알림을 관리하며, 데이터 소스를 탐색하고, 저장된 검색을 활용할 수 있습니다.

이를 통해 Claude Code, Cursor, 또는 MCP 호환 클라이언트를 사용해 개발 환경을 벗어나지 않고도 인시던트를 조사하고, 대시보드를 구축하며, 관측성 환경을 관리할 수 있습니다.

MCP 서버는 다음 ClickStack 배포 유형에서 사용할 수 있습니다:

ClickHouse Cloud의 ClickStack은 Cloud MCP endpoint https://mcp.clickhouse.cloud/clickstack를 통해 연결되며, OAuth 2.0으로 인증됩니다. 이 endpoint에서는 API Key 인증이 지원되지 않습니다.

• ClickStack이 활성화된 실행 중인 ClickHouse Cloud 서비스
• 서비스에서 MCP가 활성화되어 있어야 합니다 — Cloud Console을 열고 Connect를 클릭한 다음 Connect with MCP를 선택한 후 토글을 켜십시오

https://mcp.clickhouse.cloud/clickstack

인증에는 OAuth 2.0을 사용합니다. MCP client가 처음 연결되면 브라우저 창이 열리며 ClickHouse Cloud 자격 증명으로 로그인할 수 있습니다. API Key는 필요하지 않습니다.

각 클라이언트는 처음 연결할 때 OAuth 흐름을 자동으로 처리합니다.

claude mcp add --transport http clickstack https://mcp.clickhouse.cloud/clickstack

{
  "mcpServers": {
    "clickstack": {
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

{
  "servers": {
    "clickstack": {
      "type": "http",
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

{
  "mcp": {
    "clickstack": {
      "type": "remote",
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

mcpServers:
  clickstack:
    type: streamable-http
    url: https://mcp.clickhouse.cloud/clickstack

x-service-id 헤더가 없으면 요청은 기본적으로 계정에서 프로비저닝해 사용 중인 첫 번째 ClickStack 서비스로 전송됩니다. 다른 서비스를 지정하려면 MCP 클라이언트 구성의 헤더에 x-service-id: <YOUR_SERVICE_ID>를 추가하십시오.

Open Source 및 BYOC 배포는 ClickStack 인스턴스에 내장된 MCP 엔드포인트를 Bearer token 인증으로 사용합니다.

• 실행 중인 ClickStack 인스턴스(배포에서 설정 옵션 참조)
• Personal API Access Key — HyperDX의 Team Settings → API Keys → Personal API Access Key에서 확인할 수 있습니다

MCP 서버는 ClickStack 프론트엔드 URL의 /api/mcp 경로에서 이용할 수 있습니다. 예를 들어, 기본 로컬 배포에서는 URL이 http://localhost:8080/api/mcp입니다. 기본 설정을 변경한 경우 localhost:8080을 인스턴스에 맞는 호스트와 포트로 바꾸십시오.

MCP 서버는 Bearer token 인증을 사용하는 Streamable HTTP 전송 방식을 사용합니다.

<YOUR_CLICKSTACK_URL>은 인스턴스 URL(예: http://localhost:8080)로, <YOUR_API_KEY>는 Personal API Access Key로 바꾸십시오.

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

{
  "mcpServers": {
    "hyperdx": {
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

{
  "servers": {
    "hyperdx": {
      "type": "http",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

{
  "mcp": {
    "hyperdx": {
      "type": "remote",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

mcpServers:
  clickstack:
    type: streamable-http
    url: <YOUR_CLICKSTACK_URL>/api/mcp
    headers:
      Authorization: "Bearer <YOUR_API_KEY>"

연결이 완료되면 AI 어시스턴트는 ClickStack의 핵심 영역 전반에 걸친 다양한 도구에 접근할 수 있습니다. 여기에는 다음이 포함됩니다.

• 데이터 쿼리 — ClickStack의 쿼리 빌더, 검색 구문 또는 raw SQL을 사용해 로그, 트레이스, 메트릭을 검색하고 집계합니다.
• 데이터 소스 — 사용 가능한 데이터 소스, 데이터베이스 연결, 컬럼 스키마, 속성 키를 나열합니다.
• 대시보드 — 타일과 함께 대시보드를 생성, 업데이트, 삭제하고 내용을 확인합니다.
• 알림 — 평가 이력과 함께 알림을 생성, 업데이트하고 내용을 확인합니다.
• 저장된 검색 — 재사용 가능한 저장된 검색 정의를 생성, 업데이트하고 내용을 확인합니다.
• 웹훅 — 알림 알림을 위한 사용 가능한 웹훅 대상을 나열합니다.
• 팀 — 현재 사용자가 속한 팀을 나열하고 활성 팀을 식별합니다.

제공되는 도구의 구체적인 구성은 시간이 지나면서 확장될 수 있습니다. MCP 클라이언트는 연결 시 사용 가능한 도구를 자동으로 탐색합니다.

이는 Open Source 및 BYOC 배포에만 적용됩니다. ClickStack on ClickHouse Cloud는 특정 service 지정을 참조하십시오.

기본적으로 MCP 요청은 사용자의 기본 팀 컨텍스트에서 실행됩니다. 여러 팀에 속해 있다면 Authorization 헤더와 함께 팀 ID로 설정한 x-hdx-team 헤더를 전달하십시오. 이 헤더를 생략하면 기본 팀이 사용됩니다. 속해 있지 않은 팀을 지정하면 요청이 401 오류와 함께 거부됩니다.

MCP 클라이언트의 팀 목록 도구를 사용하면 액세스할 수 있는 팀과 현재 활성 상태인 팀을 확인할 수 있습니다.