Servidor MCP do ClickStack

O ClickStack inclui um servidor Model Context Protocol (MCP) integrado que permite que assistentes de IA interajam com seus dados de observabilidade. Depois de conectado, um assistente de IA pode consultar logs, traces e métricas; gerenciar dashboards e alertas; explorar fontes de dados; e trabalhar com pesquisas salvas — tudo em linguagem natural.

Isso permite que você use ferramentas como Claude Code, Cursor ou qualquer cliente compatível com MCP para investigar incidentes, criar dashboards e gerenciar sua configuração de observabilidade sem sair do ambiente de desenvolvimento.

O servidor MCP está disponível nos seguintes tipos de implantação do ClickStack:

O ClickStack no ClickHouse Cloud se conecta por meio do endpoint MCP do ClickHouse Cloud em https://mcp.clickhouse.cloud/clickstack e usa autenticação OAuth 2.0. A autenticação com API key não tem suporte nesse endpoint.

• Um serviço do ClickHouse Cloud em execução com o ClickStack ativado
• MCP ativado no serviço — abra o console do Cloud, clique em Connect, selecione Connect with MCP e ative-o

https://mcp.clickhouse.cloud/clickstack

A autenticação usa OAuth 2.0. Quando seu cliente MCP se conecta pela primeira vez, ele abre uma janela do navegador para que você faça login com suas credenciais do ClickHouse Cloud. Não é necessária nenhuma chave de API.

Cada cliente gerencia automaticamente o fluxo do OAuth ao se conectar pela primeira vez.

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

{
  "mcpServers": {
    "clickstack": {
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

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

{
  "mcp": {
    "clickstack": {
      "type": "remote",
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

mcpServers:
  clickstack:
    type: streamable-http
    url: https://mcp.clickhouse.cloud/clickstack

Sem o cabeçalho x-service-id, as solicitações são direcionadas por padrão ao primeiro serviço ClickStack provisionado e usado pela sua conta. Para direcionar as solicitações a outro serviço, passe x-service-id: <YOUR_SERVICE_ID> como cabeçalho na configuração do seu cliente MCP.

As implantações Open Source e BYOC usam o endpoint MCP integrado da sua instância do ClickStack com autenticação via token Bearer.

• Uma instância do ClickStack em execução (consulte Implantação para ver as opções de configuração)
• Uma Personal API Access Key — encontre a sua no HyperDX em Team Settings → API Keys → Personal API Access Key

O servidor MCP está disponível no caminho /api/mcp na URL de frontend do seu ClickStack. Por exemplo, com uma implantação local padrão, a URL é http://localhost:8080/api/mcp. Substitua localhost:8080 pelo host e pela porta da sua instância se você tiver alterado os valores padrão.

O servidor MCP usa o transporte Streamable HTTP com autenticação por token Bearer.

Substitua <YOUR_CLICKSTACK_URL> pela URL da sua instância (por exemplo, http://localhost:8080) e <YOUR_API_KEY> pela sua Personal API Access Key.

claude mcp add --transport http hyperdx <YOUR_CLICKSTACK_URL>/api/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"

{
  "mcpServers": {
    "hyperdx": {
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

{
  "servers": {
    "hyperdx": {
      "type": "http",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

{
  "mcp": {
    "hyperdx": {
      "type": "remote",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

mcpServers:
  clickstack:
    type: streamable-http
    url: <YOUR_CLICKSTACK_URL>/api/mcp
    headers:
      Authorization: "Bearer <YOUR_API_KEY>"

Depois de se conectar, seu assistente de IA tem acesso a várias ferramentas que abrangem as principais áreas do ClickStack. Elas incluem:

• Consulta de dados — Pesquise e agregue logs, traces e métricas usando o query builder do ClickStack, a sintaxe de busca ou SQL puro.
• Fontes de dados — Liste as fontes de dados disponíveis, conexões de banco de dados, esquemas de colunas e chaves de atributos.
• Dashboards — Crie, atualize, exclua e inspecione dashboards, junto com seus tiles.
• Alertas — Crie, atualize e inspecione alertas, junto com seu histórico de avaliação.
• Pesquisas salvas — Crie, atualize e inspecione definições reutilizáveis de pesquisas salvas.
• Webhooks — Liste os destinos de webhook disponíveis para notificações de alerta.
• Equipes — Liste as equipes às quais o usuário atual pertence e identifique a equipe ativa.

O conjunto específico de ferramentas pode se expandir com o tempo. Seu cliente MCP descobrirá automaticamente as ferramentas disponíveis ao se conectar.

Isso se aplica apenas a implantações Open Source e BYOC. Para o ClickStack no ClickHouse Cloud, consulte Direcionar para um serviço específico.

Por padrão, as solicitações MCP operam no contexto da sua equipe primária. Se você pertence a várias equipes, pode direcionar a solicitação para uma equipe específica incluindo o cabeçalho x-hdx-team com o ID da equipe junto com o cabeçalho Authorization. Se o cabeçalho for omitido, sua equipe primária será usada. Se você especificar uma equipe da qual não faz parte, a solicitação será rejeitada com um erro 401.

Use a ferramenta de listagem de equipes do seu cliente MCP para descobrir a quais equipes você tem acesso e qual delas está ativa.