Ative e conecte o servidor MCP remoto do ClickHouse Cloud

Este guia mostra como habilitar o servidor MCP remoto do ClickHouse Cloud e configurá-lo para uso com ferramentas de desenvolvedor comuns. Pré-requisitos

Um serviço do ClickHouse Cloud em execução
Sua IDE ou ferramenta de desenvolvimento com agentes de preferência
Para autenticação sem interação (headless), uma chave de API do ClickHouse Cloud com acesso à organização e aos serviços necessários

Habilitar o servidor MCP remoto para Cloud

Conecte-se ao serviço ClickHouse Cloud para o qual você deseja habilitar o servidor MCP remoto. No menu à esquerda, clique em Connect. Uma caixa com os detalhes da conexão será aberta. Selecione Connect with MCP: Ative o botão para habilitar o MCP no serviço. Para habilitar ou desabilitar o MCP, é necessária a permissão control-plane:service:manage-mcp (consulte Funções e permissões do Console): Copie a URL exibida, que é a mesma mostrada abaixo:

https://mcp.clickhouse.cloud/mcp

Configure o MCP remoto para desenvolvimento

Escolha sua IDE ou ferramenta abaixo e siga as instruções de configuração correspondentes.

Autenticar a partir de um ambiente headless

Se o seu cliente MCP for executado em um host remoto ou headless, onde um fluxo do OAuth baseado em navegador não é viável, faça a autenticação com uma chave de API do ClickHouse Cloud.

No console do ClickHouse Cloud, abra sua organização e selecione Chaves de API.
Crie uma chave com as funções e permissões mínimas necessárias para as organizações e os serviços que o cliente MCP precisa acessar e, em seguida, baixe o ID e o secret da chave.
No host remoto, forneça as credenciais por meio do seu sistema de gerenciamento de secrets e crie um valor de autorização HTTP Basic:

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'
)"

Selecione seu cliente MCP e adicione o servidor MCP remoto:

Claude Code
Codex
OpenCode

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

O Claude Code expande CH_AUTH a partir do ambiente ao se conectar. Inicie o Claude Code e execute /mcp para confirmar que clickhouse-cloud está conectado.Consulte a documentação de MCP do Claude Code para obter detalhes sobre servidores HTTP remotos e a configuração de cabeçalhos.

Adicione a seguinte entrada ao arquivo ~/.codex/config.toml:

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

Execute codex mcp list para confirmar que clickhouse-cloud está configurado.Consulte a referência de configuração do Codex para obter detalhes sobre mcp_servers.<id>.env_http_headers.

Adicione a seguinte entrada ao seu arquivo de configuração 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}"
        }
      }
    }
  }
}

Execute opencode mcp list para confirmar que clickhouse-cloud está conectado.Consulte a documentação de MCP do OpenCode para obter detalhes sobre servidores remotos, cabeçalhos e substituição de variáveis de ambiente.

Mantenha CH_AUTH disponível em cada sessão do cliente e não faça commit da chave de API, do secret nem do valor de CH_AUTH no controle de versão. A codificação Base64 não criptografa as credenciais. Esse fluxo com chave de API não exige um navegador nem um login separado no clickhousectl.

Claude Code

No diretório de trabalho, execute o comando a seguir para adicionar a configuração do servidor MCP do ClickHouse Cloud ao Claude Code:

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

Em seguida, abra o Claude Code:

claude

Execute o comando a seguir para listar servidores MCP:

/mcp

Selecione clickhouse-cloud e autentique-se via OAuth usando suas credenciais do ClickHouse Cloud.

Claude interface web

Navegue até Customize > Connectors
Clique no ícone ”+” e em Add custom connector
Dê um nome ao conector personalizado, como clickhouse-cloud, e adicione-o
Clique no conector clickhouse-cloud recém-adicionado e depois em Connect
Autentique-se usando suas credenciais do ClickHouse Cloud via OAuth

Cursor

Navegue pelo Cursor Marketplace e instale servidores MCP.
Procure por ClickHouse e clique em “Add to Cursor” em qualquer servidor para instalá-lo
Autentique-se com OAuth.

Visual Studio Code

Adicione a seguinte configuração ao arquivo .vscode/mcp.json:

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

Para mais detalhes, consulte a documentação do Visual Studio Code.

Windsurf

Edite o arquivo mcp_config.json com a seguinte configuração:

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

Para mais informações, consulte a documentação do Windsurf.

Zed

Adicione o ClickHouse como um servidor customizado. Adicione o seguinte às configurações do Zed, em context_servers:

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

O Zed deverá solicitar que você se autentique via OAuth na primeira vez em que se conectar ao servidor. Para mais detalhes, consulte a documentação do Zed.

Codex

Execute o comando abaixo para adicionar o servidor MCP do ClickHouse Cloud pela CLI:

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

Exemplo de uso

Depois de se conectar, você pode interagir com o ClickHouse Cloud por meio de prompts em linguagem natural. Abaixo estão alguns fluxos de trabalho comuns e as ferramentas que seu MCP client acionará em segundo plano. Para ver a lista completa de ferramentas disponíveis, consulte a referência de ferramentas.

Explorando seus dados

Comece descobrindo o que está disponível:

Prompt	Ferramenta invocada
”A quais organizações tenho acesso?”	`get_organizations`
”Quais bancos de dados estão disponíveis no meu serviço?”	`list_databases`
”Mostre as tabelas no banco de dados `default`”	`list_tables`
”Liste todas as tabelas cujos nomes começam com `events_`”	`list_tables` (com o filtro `like`)

Executando consultas analíticas

Faça perguntas em linguagem natural, e o agente as traduzirá para SQL:

Prompt	Ferramenta invocada
”Mostre as 10 primeiras linhas da tabela `hits`”	`run_select_query`
”Qual é a duração média da sessão por país nos últimos 7 dias?”	`run_select_query`
”Quantas linhas existem em cada tabela do banco de dados `analytics`?”	`run_select_query`

A ferramenta run_select_query permite apenas instruções SELECT. Todas as consultas são somente leitura.

Gerenciando serviços e infraestrutura

Tenha visibilidade sobre seus recursos no ClickHouse Cloud:

Prompt	Ferramenta invocada
”Liste todos os meus serviços”	`get_services_list`
”Qual é o status do meu serviço de produção?”	`get_service_details`
”Mostre a programação de backups deste serviço”	`get_service_backup_configuration`
”Liste os backups recentes”	`list_service_backups`
”Quais ClickPipes estão configurados neste serviço?”	`list_clickpipes`

Custos de monitoramento

Prompt	Ferramenta invocada
”Qual foi o custo da minha organização na semana passada?”	`get_organization_cost`
”Mostre os custos diários de 1º de março a 15 de março”	`get_organization_cost` (com `from_date` e `to_date`)

ClickHouse Agent Skills

Primeiros passos

Serviços e infraestrutura

Bring Your Own Cloud

Dados e integrações

Conectar e consultar

Gerenciamento de acesso

Segurança e conformidade

Monitoramento e backups

Ferramentas e agentes de IA

API do Cloud

Faturamento

Suporte

ClickHouse Private

Ative e conecte o servidor MCP remoto do ClickHouse Cloud

Habilitar o servidor MCP remoto para Cloud

Configure o MCP remoto para desenvolvimento

Autenticar a partir de um ambiente headless

Claude Code

Claude interface web

Cursor

Visual Studio Code

Windsurf

Zed

Codex

Exemplo de uso

Explorando seus dados

Executando consultas analíticas

Gerenciando serviços e infraestrutura

Custos de monitoramento

​Habilitar o servidor MCP remoto para Cloud

​Configure o MCP remoto para desenvolvimento

​Autenticar a partir de um ambiente headless

​Claude Code

​Claude interface web

​Cursor

​Visual Studio Code

​Windsurf

​Zed

​Codex

​Exemplo de uso

​Explorando seus dados

​Executando consultas analíticas

​Gerenciando serviços e infraestrutura

​Custos de monitoramento

​Conteúdo relacionado

Habilitar o servidor MCP remoto para Cloud

Configure o MCP remoto para desenvolvimento

Autenticar a partir de um ambiente headless

Claude Code

Claude interface web

Cursor

Visual Studio Code

Windsurf

Zed

Codex

Exemplo de uso

Explorando seus dados

Executando consultas analíticas

Gerenciando serviços e infraestrutura

Custos de monitoramento

Conteúdo relacionado