Servidor MCP do ClickStack

Conecte assistentes de IA ao ClickStack usando o servidor do Model Context Protocol (MCP)

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.

​

Disponibilidade

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

Implantação	Status
Open Source ClickStack	Disponível
BYOC (Bring Your Own Cloud)	Disponível
ClickStack no ClickHouse Cloud	Disponível
HyperDX v1 (hyperdx.io)	Sem suporte

Configuração diferente para ClickHouse Cloud vs OSS/BYOC

O ClickStack no ClickHouse Cloud usa um endpoint e um método de autenticação diferentes das implantações Open Source e BYOC. Consulte a seção ClickStack no ClickHouse Cloud abaixo para a configuração específica do Cloud.

​

ClickStack no ClickHouse Cloud

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.

​

Pré-requisitos

• 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

​

Endpoint

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.

​

Conectar um cliente MCP

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

Claude Code

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

Abra o Claude Code e execute /mcp; depois, selecione clickstack para concluir o fluxo do OAuth.

Cursor

Adicione o seguinte a .cursor/mcp.json:

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

VS Code

Adicione o seguinte a .vscode/mcp.json:

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

OpenCode

Adicione o seguinte a opencode.json:

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

LibreChat

Adicione o seguinte a librechat.yaml:

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

Other

Qualquer cliente MCP com suporte a Streamable HTTP com OAuth pode se conectar. Configure-o com:

• URL: https://mcp.clickhouse.cloud/clickstack

​

Direcionando para um serviço específico

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.

​

Open Source e BYOC

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

​

Pré-requisitos

• 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

A Personal API Access Key é diferente da API key de ingestão encontrada em Team Settings, que é usada para autenticar dados de telemetria enviados ao coletor OpenTelemetry.

​

Endpoint

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.

Os exemplos nesta página usam a URL do app de frontend (porta 8080 por padrão). Você também pode acessar o servidor MCP diretamente pelo backend em <BACKEND_URL>/mcp, mas nem todas as implantações expõem o backend, por isso esta documentação usa o caminho do frontend.

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

​

Conectar um cliente MCP

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 Code

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

Cursor

Adicione o seguinte a .cursor/mcp.json:

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

VS Code

Adicione o seguinte a .vscode/mcp.json:

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

OpenCode

Adicione o seguinte a opencode.json:

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

LibreChat

Adicione o seguinte a librechat.yaml:

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

Outros

Qualquer cliente MCP com suporte a Streamable HTTP pode se conectar. Configure-o com:

• URL: <YOUR_CLICKSTACK_URL>/api/mcp
• Cabeçalho: Authorization: Bearer <YOUR_API_KEY>

​

O que você pode fazer com o MCP?

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.

​

Uso por múltiplas equipes (OSS/BYOC)

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.

​

Solução de problemas

​

ClickStack no ClickHouse Cloud

O fluxo do OAuth não é concluído

• Confirme que seu cliente MCP oferece suporte a OAuth 2.0. Clients que oferecem suporte apenas a token Bearer ou ao transporte stdio não conseguem se autenticar com o endpoint do Cloud.
• Verifique se o navegador não está bloqueando o pop-up ou o redirecionamento do OAuth.
• Verifique se sua conta do ClickHouse Cloud tem acesso à organização e ao serviço.

O MCP está habilitado, mas o cliente MCP não consegue se conectar

• Confirme que você está usando o endpoint do ClickStack (https://mcp.clickhouse.cloud/clickstack), e não o endpoint MCP geral do Cloud (https://mcp.clickhouse.cloud/mcp).
• Verifique se o MCP está habilitado no serviço no console do Cloud.

As solicitações vão para o serviço errado

Sem o cabeçalho x-service-id, as solicitações são direcionadas por padrão para o primeiro serviço do ClickStack provisionado e usado pela sua conta. Envie o cabeçalho para direcioná-las a um serviço específico. Consulte Direcionar para um serviço específico.

​

Open Source e BYOC

Estou recebendo um erro 403 de autenticação

• Verifique se você está usando a Personal API Access Key (não a API key de ingestão).
• Confirme se a chave está incluída como um token Bearer no cabeçalho Authorization.
• Verifique se sua instância do ClickStack está em execução e acessível na URL que você configurou.

Estou sendo afetado por rate limit

O servidor MCP aplica um limite de 600 solicitações por minuto por usuário. Se você exceder esse limite, as solicitações serão rejeitadas temporariamente. Reduza a frequência das solicitações ou aguarde antes de tentar novamente.

Estou recebendo um erro 401 com o cabeçalho x-hdx-team

Verifique se o ID da equipe está correto e se sua conta de usuário é membro dessa equipe.

Não consigo me conectar ao servidor MCP

• Certifique-se de que seu cliente MCP oferece suporte ao transporte Streamable HTTP. Clientes mais antigos que oferecem suporte apenas ao transporte stdio não funcionarão.
• Se você estiver executando o ClickStack localmente, confirme se o aplicativo está acessível na URL configurada (o padrão é http://localhost:8080).
• Em implantações BYOC atrás de um balanceador de carga ou proxy reverso, certifique-se de que o caminho /api/mcp não esteja sendo bloqueado nem reescrito.