> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickStack MCP 서버

> Model Context Protocol(MCP) 서버를 통해 AI 어시스턴트를 ClickStack에 연결합니다

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

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

이를 통해 [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://www.cursor.com/), 또는 MCP 호환 클라이언트를 사용해 개발 환경을 벗어나지 않고도 인시던트를 조사하고, 대시보드를 구축하며, 관측성 환경을 관리할 수 있습니다.

<div id="availability">
  ## 지원 현황
</div>

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

| 배포                                                | 상태     |
| ------------------------------------------------- | ------ |
| **Open Source ClickStack**                        | 사용 가능  |
| **BYOC (Bring Your Own Cloud)**                   | 사용 가능  |
| **Managed ClickStack**                            | 출시 예정  |
| **HyperDX v1** ([hyperdx.io](https://hyperdx.io)) | 지원 안 함 |

<Info>
  **Managed ClickStack**

  Managed ClickStack의 MCP 서버 지원은 현재 개발 중이며 곧 제공될 예정입니다. 이 페이지의 지침은 Open Source 및 BYOC 배포에 적용됩니다.
</Info>

<div id="prerequisites">
  ## 사전 요구 사항
</div>

MCP 클라이언트를 연결하기 전에 다음이 필요합니다:

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

<Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/Y9kcWM6RbYppspJn/images/clickstack/api-key-personal.png?fit=max&auto=format&n=Y9kcWM6RbYppspJn&q=85&s=dbd0e27eab9687a639d51efe86b2d749" alt="Team Settings의 Personal API Access Key" size="md" border width="3798" height="1938" data-path="images/clickstack/api-key-personal.png" />

<Note>
  Personal API Access Key는 Team Settings에서 찾을 수 있는 **수집 API key**와 다릅니다. 수집 API key는 OpenTelemetry collector로 전송되는 텔레메트리 데이터를 인증하는 데 사용됩니다.
</Note>

<div id="endpoint">
  ## 엔드포인트
</div>

MCP 서버는 ClickStack 프론트엔드 URL의 `/api/mcp` 경로에서 이용할 수 있습니다:

예를 들어, 기본 로컬 배포에서는 다음과 같습니다:

기본 설정을 변경한 경우 `localhost:8080`을 인스턴스에 맞는 호스트와 포트로 바꾸십시오.

<Note>
  이 페이지의 예시는 프론트엔드 앱 URL(기본 포트 `8080`)을 사용합니다. 백엔드를 통해 `<BACKEND_URL>/mcp`로 MCP 서버에 직접 접근할 수도 있지만, 모든 배포에서 백엔드가 노출되는 것은 아니므로 이 문서에서는 프론트엔드 경로를 사용합니다.
</Note>

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

<div id="connecting-a-client">
  ## MCP 클라이언트 연결하기
</div>

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

<div id="claude-code">
  ### Claude Code
</div>

```shell theme={null}
claude mcp add --transport http hyperdx <YOUR_CLICKSTACK_URL>/api/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"
```

<div id="cursor">
  ### Cursor
</div>

프로젝트의 `.cursor/mcp.json` 파일이나 Cursor 전역 설정에 다음 내용을 추가하십시오:

```json theme={null}
{
  "mcpServers": {
    "hyperdx": {
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}
```

<div id="opencode">
  ### OpenCode
</div>

다음을 `opencode.json` 설정에 추가하십시오:

```json theme={null}
{
  "mcp": {
    "hyperdx": {
      "type": "http",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}
```

<div id="other-clients">
  ### 기타 클라이언트
</div>

**Streamable HTTP** 전송을 지원하는 모든 MCP 클라이언트가 연결할 수 있습니다. 다음과 같이 구성하십시오.

* **URL:** `<YOUR_CLICKSTACK_URL>/api/mcp`
* **헤더:** `Authorization: Bearer <YOUR_API_KEY>`

<div id="capabilities">
  ## MCP로 무엇을 할 수 있나요?
</div>

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

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

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

<div id="multi-team">
  ## 여러 팀 사용
</div>

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

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

<div id="troubleshooting">
  ## 문제 해결
</div>

<Accordion title="403 인증 오류가 발생합니다">
  * **Personal API Access Key**를 사용하고 있는지 확인하십시오(**수집 API key**가 아닙니다).
  * `Authorization` 헤더에 key가 `Bearer` 토큰으로 포함되어 있는지 확인하십시오.
  * ClickStack 인스턴스가 실행 중이며 구성한 URL에서 접근 가능한지 확인하십시오.
</Accordion>

<Accordion title="속도 제한이 적용됩니다">
  MCP 서버는 사용자당 **분당 600개의 요청**으로 속도 제한을 적용합니다. 이 제한을 초과하면 요청이 일시적으로 거부됩니다. 요청 빈도를 줄이거나 다시 시도하기 전에 잠시 기다리십시오.
</Accordion>

<Accordion title="x-hdx-team 헤더와 함께 401 오류가 발생합니다">
  team ID가 올바른지, 그리고 사용자 계정이 해당 team의 구성원인지 확인하십시오.
</Accordion>

<Accordion title="MCP 서버에 연결할 수 없습니다">
  * MCP 클라이언트가 **Streamable HTTP** 전송을 지원하는지 확인하십시오. stdio 전송만 지원하는 구형 클라이언트는 작동하지 않습니다.
  * ClickStack을 로컬에서 실행 중이라면, 구성된 URL(기본값은 `http://localhost:8080`)에서 앱에 접근할 수 있는지 확인하십시오.
  * 로드 밸런서 또는 리버스 프록시 뒤에서 실행되는 BYOC 배포에서는 `/api/mcp` 경로가 차단되거나 재작성되지 않는지 확인하십시오.
</Accordion>