Habilitar y conectar el servidor MCP remoto de ClickHouse Cloud

Esta guía muestra cómo habilitar el servidor MCP remoto de ClickHouse Cloud y configurarlo para usarlo con herramientas de desarrollo habituales. Requisitos previos

Un servicio de ClickHouse Cloud en ejecución
El IDE o la herramienta de desarrollo con agentes que prefiera
Para la autenticación sin interfaz gráfica, una clave de API de ClickHouse Cloud con acceso a la organización y los servicios necesarios

Habilitar el servidor MCP remoto en Cloud

Conéctese al servicio de ClickHouse Cloud en el que desea habilitar el servidor MCP remoto. En el menú de la izquierda, haga clic en Conectar. Se abrirá una ventana con los detalles de conexión. Seleccione Conectar with MCP: Active el botón para habilitar MCP en el servicio. Para habilitar o deshabilitar MCP se necesita el permiso control-plane:service:manage-mcp (consulte Roles y permisos de la consola): Copie la URL que se muestra, que es la misma que aparece a continuación:

https://mcp.clickhouse.cloud/mcp

Configura un MCP remoto para desarrollo

Elige tu IDE o herramienta a continuación y sigue las instrucciones de configuración correspondientes.

Autenticarse desde un entorno sin interfaz gráfica

Si su cliente MCP se ejecuta en un host remoto o sin interfaz gráfica en el que no resulta práctico un flujo OAuth basado en navegador, autentíquese con una clave de API de ClickHouse Cloud.

En la consola de ClickHouse Cloud, abra su organización y seleccione API Keys.
Cree una clave con los roles y permisos mínimos necesarios para las organizaciones y los servicios a los que el cliente MCP necesita acceder y, a continuación, descargue el ID y el secreto de la clave.
En el host remoto, proporcione las credenciales mediante su sistema de gestión de secretos y genere un valor de autorización 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'
)"

Seleccione su cliente MCP y agregue el 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}'

Claude Code expande CH_AUTH a partir del entorno al conectarse. Inicie Claude Code y ejecute /mcp para confirmar que clickhouse-cloud está conectado.Consulte la documentación de MCP de Claude Code para obtener más información sobre los servidores HTTP remotos y la configuración de encabezados.

Agregue la siguiente entrada a ~/.codex/config.toml:

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

Ejecute codex mcp list para confirmar que clickhouse-cloud está configurado.Consulte la referencia de configuración de Codex para obtener más información sobre mcp_servers.<id>.env_http_headers.

Agregue la siguiente entrada a su archivo de configuración 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}"
        }
      }
    }
  }
}

Ejecute opencode mcp list para confirmar que clickhouse-cloud está conectado.Consulte la documentación de MCP de OpenCode para obtener más información sobre los servidores remotos, los encabezados y la sustitución de variables de entorno.

Mantenga CH_AUTH disponible en cada sesión del cliente y no haga commit de la clave de API, el secreto ni el valor de CH_AUTH en el sistema de control de versiones. La codificación Base64 no cifra las credenciales. Este flujo basado en clave de API no requiere navegador ni un inicio de sesión aparte con clickhousectl.

Claude Code

Desde tu directorio de trabajo, ejecuta el siguiente comando para agregar la configuración del MCP Server de ClickHouse Cloud a Claude Code:

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

Después, inicia Claude Code:

claude

Ejecute el siguiente comando para ver la lista de servidores MCP:

/mcp

Selecciona clickhouse-cloud y autentícate con OAuth usando tus credenciales de ClickHouse Cloud.

Interfaz web de Claude

Ve a Personalizar > Conectores
Haz clic en el icono ”+” y en Agregar conector personalizado
Asigna al conector personalizado un nombre como clickhouse-cloud y agrégalo
Haz clic en el conector clickhouse-cloud que acabas de agregar y luego en Conectar
Autentícate con tus credenciales de ClickHouse Cloud mediante OAuth

Cursor

Explora e instala servidores MCP desde el Marketplace de Cursor.
Busca ClickHouse y haz clic en “Add to Cursor” en cualquiera de los servidores para instalarlo
Autentícate con OAuth.

Visual Studio Code

Añade la siguiente configuración a tu .vscode/mcp.json:

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

Para obtener más información, consulta la documentación de Visual Studio Code.

Windsurf

Edita el archivo mcp_config.json con la siguiente configuración:

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

Para más detalles, consulta la documentación de Windsurf.

Zed

Añade ClickHouse como un servidor personalizado. Añade lo siguiente a la configuración de Zed, en context_servers:

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

Zed debería solicitarte que te autentiques mediante OAuth cuando se conecte por primera vez al servidor. Para obtener más información, consulta la documentación de Zed.

Codex

Ejecute el siguiente comando para agregar el servidor MCP de ClickHouse Cloud desde la CLI:

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

Ejemplo de uso

Una vez conectado, puedes interactuar con ClickHouse Cloud mediante prompts en lenguaje natural. A continuación, se muestran algunos flujos de trabajo habituales y las herramientas que tu cliente MCP invocará en segundo plano. Para consultar la lista completa de herramientas disponibles, consulta la referencia de herramientas.

Explorar tus datos

Comienza por descubrir qué hay disponible:

Prompt	Herramienta invocada
”¿A qué organizaciones tengo acceso?”	`get_organizations`
”¿Qué bases de datos están disponibles en mi servicio?”	`list_databases`
”Muéstrame las tablas de la base de datos `default`”	`list_tables`
”Enumera todas las tablas cuyos nombres empiezan por `events_`”	`list_tables` (con el filtro `like`)

Ejecutar consultas analíticas

Haz preguntas en lenguaje natural y el agente las traducirá a SQL:

Prompt	Herramienta invocada
”Muéstrame las primeras 10 filas de la tabla `hits`”	`run_select_query`
”¿Cuál es la duración media de la sesión por país en los últimos 7 días?”	`run_select_query`
”¿Cuántas filas hay en cada tabla de la base de datos `analytics`?”	`run_select_query`

La herramienta run_select_query solo permite sentencias SELECT. Todas las consultas son de solo lectura.

Gestión de servicios e infraestructura

Consulta tus recursos de ClickHouse Cloud:

Prompt	Herramienta invocada
”Lista todos mis servicios”	`get_services_list`
”¿Cuál es el estado de mi servicio de producción?”	`get_service_details`
”Muéstrame la programación de copias de seguridad de este servicio”	`get_service_backup_configuration`
”Lista las copias de seguridad recientes”	`list_service_backups`
”¿Qué ClickPipes están configurados en este servicio?”	`list_clickpipes`

Costos de monitoreo

Prompt	Herramienta invocada
”¿Cuál fue el costo de mi organización la semana pasada?”	`get_organization_cost`
”Muéstrame los costos diarios del 1 al 15 de marzo”	`get_organization_cost` (con `from_date` y `to_date`)

ClickHouse agent skills

Primeros pasos

Servicios e infraestructura

Bring Your Own Cloud

Datos e integraciones

Conectar y consultar

Gestión de accesos

Seguridad y cumplimiento normativo

Monitorización y copias de seguridad

Herramientas y agentes de IA

API de Cloud

Facturación

Soporte

ClickHouse Private

Habilitar y conectar el servidor MCP remoto de ClickHouse Cloud

Habilitar el servidor MCP remoto en Cloud

Configura un MCP remoto para desarrollo

Autenticarse desde un entorno sin interfaz gráfica

Claude Code

Interfaz web de Claude

Cursor

Visual Studio Code

Windsurf

Zed

Codex

Ejemplo de uso

Explorar tus datos

Ejecutar consultas analíticas

Gestión de servicios e infraestructura

Costos de monitoreo

​Habilitar el servidor MCP remoto en Cloud

​Configura un MCP remoto para desarrollo

​Autenticarse desde un entorno sin interfaz gráfica

​Claude Code

​Interfaz web de Claude

​Cursor

​Visual Studio Code

​Windsurf

​Zed

​Codex

​Ejemplo de uso

​Explorar tus datos

​Ejecutar consultas analíticas

​Gestión de servicios e infraestructura

​Costos de monitoreo

​Contenido relacionado

Habilitar el servidor MCP remoto en Cloud

Configura un MCP remoto para desarrollo

Autenticarse desde un entorno sin interfaz gráfica

Claude Code

Interfaz web de Claude

Cursor

Visual Studio Code

Windsurf

Zed

Codex

Ejemplo de uso

Explorar tus datos

Ejecutar consultas analíticas

Gestión de servicios e infraestructura

Costos de monitoreo

Contenido relacionado