- 실행 중인 ClickHouse Cloud 서비스
- 원하는 IDE 또는 에이전트 기반 개발 도구
- 헤드리스 인증을 사용하려면 필요한 조직 및 서비스에 대한 액세스 권한이 있는 ClickHouse Cloud API Key
Cloud에서 원격 MCP 서버 활성화
원격 MCP 서버를 활성화할 ClickHouse Cloud 서비스에 연결합니다. 왼쪽 메뉴에서 Connect를 클릭합니다. 연결 정보(connection details)가 표시된 상자가 열립니다. Connect with MCP를 선택합니다:
control-plane:service:manage-mcp 권한이 필요합니다(Console 역할 및 권한 참조):

헤드리스 환경에서 인증하기
MCP 클라이언트가 원격 호스트나 헤드리스 호스트에서 실행되어 브라우저 기반 OAuth 흐름을 사용하기 어렵다면 ClickHouse Cloud API Key로 인증하십시오.- ClickHouse Cloud 콘솔에서 조직을 열고 API Keys를 선택합니다.
-
MCP 클라이언트가 액세스해야 하는 조직과 서비스에 필요한 최소한의 역할과 권한만 부여하여 키를 생성한 다음, 키 ID와 시크릿을 다운로드합니다.
clickhousectl로 키를 생성하려면 먼저 역할 ID를 확인한 다음, MCP 호스트의 IP를 허용 목록에 지정하여 키를 생성하십시오.clickhousectl을 사용하려면 키 생성 권한이 있는 기존 API Key가 필요합니다.이 명령은 새 키 ID와 시크릿을 한 번만 출력하므로 시크릿 관리 시스템에 저장하십시오.--ip-allow를 지정하지 않으면 키의 IP 허용 목록이 비어 있어 모든 액세스가 거부됩니다. - 원격 호스트에서 시크릿 관리 시스템을 통해 자격 증명을 제공하고 HTTP Basic 인증(authorization) 값을 생성합니다.
- MCP 클라이언트를 선택하고 원격 MCP 서버를 추가하십시오.
- Claude Code
- Codex
- OpenCode
CH_AUTH 값을 읽어 확장합니다. Claude Code를 시작한 후 /mcp를 실행하여 clickhouse-cloud가 연결되었는지 확인하십시오.원격 HTTP 서버와 헤더 구성에 대한 자세한 내용은 Claude Code MCP 문서를 참조하십시오.CH_AUTH를 계속 사용할 수 있도록 유지하십시오. 또한 API Key, 시크릿, CH_AUTH 값을 소스 관리 시스템에 커밋하지 마십시오. Base64 인코딩은 자격 증명을 암호화하지 않습니다.
이 API Key 방식에서는 브라우저나 별도의 clickhousectl 로그인이 필요하지 않습니다. 같은 호스트에서 clickhousectl도 사용한다면 clickhousectl 역시 동일한 CLICKHOUSE_CLOUD_API_KEY 및 CLICKHOUSE_CLOUD_API_SECRET 변수를 읽으며, 이 변수들이 브라우저 로그인보다 우선 적용됩니다.
현재 작업 디렉터리에서 다음 명령을 실행하여 Claude Code에 ClickHouse Cloud MCP 서버 구성을 추가하십시오:
clickhouse-cloud를 선택하고 ClickHouse Cloud 자격 증명으로 OAuth 인증을 진행하세요.
- Customize > Connectors로 이동하세요
- ”+” 아이콘을 클릭한 다음 Add custom connector를 선택하세요
- 사용자 지정 커넥터에
clickhouse-cloud와 같은 이름을 지정한 뒤 추가하세요 - 새로 추가한
clickhouse-cloud커넥터를 클릭한 다음 Connect를 클릭하세요 - OAuth를 통해 ClickHouse Cloud 자격 증명으로 인증하세요
- Cursor Marketplace에서 MCP 서버를 둘러보고 설치합니다.
- ClickHouse를 검색한 다음, 원하는 서버에서 “Add to Cursor”를 클릭해 설치합니다.
- OAuth로 인증합니다.
.vscode/mcp.json 파일에 추가하십시오:
mcp_config.json 파일을 수정하세요:
자연어로 질문하면 에이전트가 이를 SQL로 변환합니다:
run_select_query 도구는 SELECT SQL 문만 허용합니다. 모든 쿼리는 읽기 전용입니다.
ClickHouse Cloud 리소스를 한눈에 파악할 수 있습니다: