> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse Cloud 원격 MCP 서버 활성화 및 연결

> 이 가이드에서는 ClickHouse Cloud 원격 MCP 서버를 활성화하고 사용하는 방법을 설명합니다

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

이 가이드에서는 ClickHouse Cloud 원격 MCP 서버를 활성화하고 일반적인 개발자 도구에서 사용할 수 있도록 설정하는 방법을 설명합니다.

**사전 요구사항**

* 실행 중인 [ClickHouse Cloud 서비스](/docs/ko/get-started/setup/cloud)
* 원하는 IDE 또는 에이전트 기반 개발 도구

<div id="enable-remote-mcp-server">
  ## Cloud에서 원격 MCP 서버 활성화
</div>

원격 MCP 서버를 활성화할 ClickHouse Cloud 서비스에 연결합니다.
왼쪽 메뉴에서 **Connect**를 클릭합니다. 연결 정보(connection details)가 표시된 상자가 열립니다.

**Connect with MCP**를 선택합니다:

<Image img="https://mintcdn.com/private-7c7dfe99/F7iOqwDUBB9E2S65/images/use-cases/AI_ML/MCP/1connectmcpmodal.webp?fit=max&auto=format&n=F7iOqwDUBB9E2S65&q=85&s=744e5d063d27c1d69b4b09204c3627f8" alt="Connect 모달에서 MCP 선택" size="md" width="2190" height="2082" data-path="images/use-cases/AI_ML/MCP/1connectmcpmodal.webp" />

서비스에서 MCP를 활성화하려면 버튼을 켭니다:

<Image img="https://mintcdn.com/private-7c7dfe99/F7iOqwDUBB9E2S65/images/use-cases/AI_ML/MCP/2enable_mcp.webp?fit=max&auto=format&n=F7iOqwDUBB9E2S65&q=85&s=b3dcbb434349ffabcc8402552d82eb1a" alt="MCP 서버 활성화" size="md" width="1340" height="884" data-path="images/use-cases/AI_ML/MCP/2enable_mcp.webp" />

표시된 URL을 복사합니다. 이 URL은 아래와 동일합니다:

```bash theme={null}
https://mcp.clickhouse.cloud/mcp
```

<div id="setup-clickhouse-cloud-remote-mcp-server">
  ## 개발용 원격 MCP 설정
</div>

아래에서 IDE 또는 도구를 선택하고 해당 설정 안내를 따르십시오.

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

현재 작업 디렉터리에서 다음 명령을 실행하여 Claude Code에 ClickHouse Cloud MCP 서버 구성을 추가하십시오:

```bash theme={null}
claude mcp add --transport http clickhouse-cloud https://mcp.clickhouse.cloud/mcp
```

그런 다음 Claude Code를 시작합니다:

```bash theme={null}
claude
```

다음 명령을 실행하여 MCP 서버 목록을 확인하세요:

```bash theme={null}
/mcp
```

`clickhouse-cloud`를 선택하고 ClickHouse Cloud 자격 증명으로 OAuth 인증을 진행하세요.

<div id="claude-web">
  ### Claude 웹 UI
</div>

1. **Customize** > **Connectors**로 이동하세요
2. "+" 아이콘을 클릭한 다음 **Add custom connector**를 선택하세요
3. 사용자 지정 커넥터에 `clickhouse-cloud`와 같은 이름을 지정한 뒤 추가하세요
4. 새로 추가한 `clickhouse-cloud` 커넥터를 클릭한 다음 **Connect**를 클릭하세요
5. OAuth를 통해 ClickHouse Cloud 자격 증명으로 인증하세요

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

1. [Cursor Marketplace](https://cursor.com/marketplace)에서 MCP 서버를 둘러보고 설치합니다.
2. ClickHouse를 검색한 다음, 원하는 서버에서 "Add to Cursor"를 클릭해 설치합니다.
3. OAuth로 인증합니다.

<div id="visual-studio-code">
  ### Visual Studio Code
</div>

다음 구성을 `.vscode/mcp.json` 파일에 추가하십시오:

```json theme={null}
{
  "servers": {
    "clickhouse-cloud": {
      "type": "http",
      "url": "https://mcp.clickhouse.cloud/mcp"
    }
  }
}
```

자세한 내용은 [Visual Studio Code 문서](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)를 참고하십시오.

<div id="windsurf">
  ### Windsurf
</div>

다음 구성에 맞게 `mcp_config.json` 파일을 수정하세요:

```json theme={null}
{
  "mcpServers": {
    "clickhouse-cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"]
    }
  }
}
```

자세한 내용은 [Windsurf docs](https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp)를 참고하십시오.

<div id="zed">
  ### Zed
</div>

ClickHouse를 사용자 지정 서버로 추가합니다.
다음을 Zed 설정의 **context\_servers**에 추가하세요:

```json theme={null}
{
  "context_servers": {
    "clickhouse-cloud": {
      "url": "https://mcp.clickhouse.cloud/mcp"
    }
  }
}
```

그러면 Zed가 서버에 처음 연결할 때 OAuth를 통해 인증하라는 메시지를 표시합니다.
자세한 내용은 [Zed docs](https://zed.dev/docs/ai/mcp#as-custom-servers)를 참조하십시오.

<div id="codex">
  ### Codex
</div>

CLI를 사용해 ClickHouse Cloud MCP 서버를 추가하려면 다음 명령을 실행하세요:

```bash theme={null}
codex mcp add clickhouse-cloud --url https://mcp.clickhouse.cloud/mcp
```

<div id="example-usage">
  ## 예시 사용
</div>

연결되면 자연어 프롬프트를 통해 ClickHouse Cloud와 상호작용할 수 있습니다.
아래에는 일반적인 워크플로와 MCP 클라이언트가 백그라운드에서 호출하는 도구가 나와 있습니다.
사용 가능한 도구의 전체 목록은 [도구 참고](/docs/ko/products/cloud/features/ai-ml/remote-mcp#available-tools)를 참조하십시오.

<div id="exploring-data">
  ### 데이터 살펴보기
</div>

먼저 어떤 항목을 사용할 수 있는지 확인합니다:

| 프롬프트                                | 호출되는 도구                          |
| ----------------------------------- | -------------------------------- |
| "액세스할 수 있는 조직이 무엇인가요?"              | `get_organizations`              |
| "내 서비스에서 사용할 수 있는 데이터베이스는 무엇인가요?"   | `list_databases`                 |
| "`default` 데이터베이스의 테이블을 보여주세요"      | `list_tables`                    |
| "이름이 `events_`로 시작하는 모든 테이블을 나열하세요" | `list_tables` (`like` filter 사용) |

<div id="running-queries">
  ### 분석 쿼리 실행
</div>

자연어로 질문하면 에이전트가 이를 SQL로 변환합니다:

| 프롬프트                                       | 호출되는 도구            |
| ------------------------------------------ | ------------------ |
| "`hits` 테이블의 상위 10개 행을 보여주세요"              | `run_select_query` |
| "지난 7일간 국가별 평균 세션 지속 시간은 얼마입니까?"           | `run_select_query` |
| "`analytics` 데이터베이스의 각 테이블에는 행이 몇 개 있습니까?" | `run_select_query` |

`run_select_query` 도구는 `SELECT` SQL 문만 허용합니다. 모든 쿼리는 읽기 전용입니다.

<div id="managing-services">
  ### 서비스 및 인프라 관리
</div>

ClickHouse Cloud 리소스를 한눈에 파악할 수 있습니다:

| 프롬프트                               | 호출되는 도구                            |
| ---------------------------------- | ---------------------------------- |
| "내 서비스 목록을 보여줘"                    | `get_services_list`                |
| "운영 서비스의 상태가 어떻게 되나요?"             | `get_service_details`              |
| "이 서비스의 백업 일정을 보여줘"                | `get_service_backup_configuration` |
| "최근 백업 목록을 보여줘"                    | `list_service_backups`             |
| "이 서비스에는 어떤 ClickPipes가 구성되어 있나요?" | `list_clickpipes`                  |

<div id="monitoring-costs">
  ### 비용 모니터링
</div>

| 프롬프트                            | 호출되는 도구                                              |
| ------------------------------- | ---------------------------------------------------- |
| "지난주 우리 조직의 비용은 얼마였나요?"         | `get_organization_cost`                              |
| "3월 1일부터 3월 15일까지 일별 비용을 보여주세요" | `get_organization_cost` (`from_date` 및 `to_date` 사용) |

<div id="related-content">
  ## 관련 콘텐츠
</div>

* [ClickHouse 에이전트 스킬](https://github.com/ClickHouse/agent-skills)