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

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

실행 중인 ClickHouse Cloud 서비스
원하는 IDE 또는 에이전트 기반 개발 도구
헤드리스 인증을 사용하려면 필요한 조직 및 서비스에 대한 액세스 권한이 있는 ClickHouse Cloud API Key

Cloud에서 원격 MCP 서버 활성화

원격 MCP 서버를 활성화할 ClickHouse Cloud 서비스에 연결합니다. 왼쪽 메뉴에서 Connect를 클릭합니다. 연결 정보(connection details)가 표시된 상자가 열립니다. Connect with MCP를 선택합니다: 서비스에서 MCP를 활성화하려면 버튼을 켭니다. MCP를 활성화하거나 비활성화하려면 control-plane:service:manage-mcp 권한이 필요합니다(Console 역할 및 권한 참조): 표시된 URL을 복사합니다. 이 URL은 아래와 동일합니다:

https://mcp.clickhouse.cloud/mcp

개발용 원격 MCP 설정

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

헤드리스 환경에서 인증하기

MCP 클라이언트가 원격 호스트나 헤드리스 호스트에서 실행되어 브라우저 기반 OAuth 흐름을 사용하기 어렵다면 ClickHouse Cloud API Key로 인증하십시오.

ClickHouse Cloud 콘솔에서 조직을 열고 API Keys를 선택합니다.
MCP 클라이언트가 액세스해야 하는 조직과 서비스에 필요한 최소한의 역할과 권한만 부여하여 키를 생성한 다음, 키 ID와 시크릿을 다운로드합니다.
원격 호스트에서 시크릿 관리 시스템을 통해 자격 증명을 제공하고 HTTP Basic 인증(authorization) 값을 생성합니다.

export CLICKHOUSE_CLOUD_API_KEY="<key_id>"
export CLICKHOUSE_CLOUD_API_SECRET="<key_secret>"

export CH_AUTH="Basic $(
  printf '%s:%s' \
    "$CLICKHOUSE_CLOUD_API_KEY" \
    "$CLICKHOUSE_CLOUD_API_SECRET" |
  base64 | tr -d '\n'
)"

MCP 클라이언트를 선택하고 원격 MCP 서버를 추가하십시오.

Claude Code
Codex
OpenCode

claude mcp add \
  --scope user \
  --transport http \
  clickhouse-cloud \
  https://mcp.clickhouse.cloud/mcp \
  --header 'Authorization: ${CH_AUTH}'

Claude Code는 연결할 때 환경 변수에서 CH_AUTH 값을 읽어 확장합니다. Claude Code를 시작한 후 /mcp를 실행하여 clickhouse-cloud가 연결되었는지 확인하십시오.원격 HTTP 서버와 헤더 구성에 대한 자세한 내용은 Claude Code MCP 문서를 참조하십시오.

~/.codex/config.toml에 다음 엔트리를 추가하십시오.

[mcp_servers.clickhouse-cloud]
url = "https://mcp.clickhouse.cloud/mcp"
env_http_headers = { Authorization = "CH_AUTH" }

codex mcp list를 실행하여 clickhouse-cloud가 구성되었는지 확인하십시오.mcp_servers.<id>.env_http_headers에 대한 자세한 내용은 Codex 구성 참고 문서를 참조하십시오.

opencode.jsonc 구성 파일에 다음 엔트리를 추가하십시오.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "clickhouse-cloud": {
        "type": "remote",
        "url": "https://mcp.clickhouse.cloud/mcp",
        "oauth": false,
        "headers": {
          "Authorization": "{env:CH_AUTH}"
        }
      }
    }
  }
}

opencode mcp list를 실행하여 clickhouse-cloud가 연결되었는지 확인하십시오.원격 서버, 헤더, 환경 변수 치환에 대한 자세한 내용은 OpenCode MCP 문서를 참조하십시오.

각 클라이언트 세션에서 CH_AUTH를 계속 사용할 수 있도록 유지하십시오. 또한 API Key, 시크릿, CH_AUTH 값을 소스 관리 시스템에 커밋하지 마십시오. Base64 인코딩은 자격 증명을 암호화하지 않습니다. 이 API Key 방식에서는 브라우저나 별도의 clickhousectl 로그인이 필요하지 않습니다.

Claude Code

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

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

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

claude

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

/mcp

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

Claude 웹 UI

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

Cursor

Cursor Marketplace에서 MCP 서버를 둘러보고 설치합니다.
ClickHouse를 검색한 다음, 원하는 서버에서 “Add to Cursor”를 클릭해 설치합니다.
OAuth로 인증합니다.

Visual Studio Code

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

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

자세한 내용은 Visual Studio Code 문서를 참고하십시오.

Windsurf

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

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

자세한 내용은 Windsurf docs를 참고하십시오.

Zed

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

{
  "context_servers": {
    "clickhouse-cloud": {
      "url": "https://mcp.clickhouse.cloud/mcp"
    }
  }
}

그러면 Zed가 서버에 처음 연결할 때 OAuth를 통해 인증하라는 메시지를 표시합니다. 자세한 내용은 Zed docs를 참조하십시오.

Codex

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

codex mcp add clickhouse-cloud --url https://mcp.clickhouse.cloud/mcp

예시 사용

연결되면 자연어 프롬프트를 통해 ClickHouse Cloud와 상호작용할 수 있습니다. 아래에는 일반적인 워크플로와 MCP 클라이언트가 백그라운드에서 호출하는 도구가 나와 있습니다. 사용 가능한 도구의 전체 목록은 도구 참고를 참조하십시오.

데이터 살펴보기

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

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

분석 쿼리 실행

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

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

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

서비스 및 인프라 관리

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

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

비용 모니터링

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

ClickHouse 에이전트 스킬

시작하기

서비스 및 인프라

Bring Your Own Cloud

데이터 및 통합

연결 및 쿼리 실행

접근 관리

보안 및 컴플라이언스

모니터링 및 백업

AI 도구 및 에이전트

Cloud API

청구

지원

ClickHouse Private

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

Cloud에서 원격 MCP 서버 활성화

개발용 원격 MCP 설정

헤드리스 환경에서 인증하기

Claude Code

Claude 웹 UI

Cursor

Visual Studio Code

Windsurf

Zed

Codex

예시 사용

데이터 살펴보기

분석 쿼리 실행

서비스 및 인프라 관리

비용 모니터링

​Cloud에서 원격 MCP 서버 활성화

​개발용 원격 MCP 설정

​헤드리스 환경에서 인증하기

​Claude Code

​Claude 웹 UI

​Cursor

​Visual Studio Code

​Windsurf

​Zed

​Codex

​예시 사용

​데이터 살펴보기

​분석 쿼리 실행

​서비스 및 인프라 관리

​비용 모니터링

​관련 콘텐츠

Cloud에서 원격 MCP 서버 활성화

개발용 원격 MCP 설정

헤드리스 환경에서 인증하기

Claude Code

Claude 웹 UI

Cursor

Visual Studio Code

Windsurf

Zed

Codex

예시 사용

데이터 살펴보기

분석 쿼리 실행

서비스 및 인프라 관리

비용 모니터링

관련 콘텐츠