Como criar um agente SlackBot usando o servidor MCP do ClickHouse.

Neste guia, você aprenderá a criar um agente SlackBot. Esse bot permite que você faça perguntas sobre seus dados no ClickHouse diretamente do Slack, usando linguagem natural. Ele usa o ClickHouse MCP server e o PydanticAI.

Projeto de exemploO código deste exemplo pode ser encontrado no repositório de exemplos.

Pré-requisitos

Você precisará ter o uv instalado
Você precisará ter acesso a um workspace do Slack
Você precisará de uma API key da Anthropic ou de outro provedor de LLM

Criar um Slack App

Acesse slack.com/apps e clique em Create New App.
Escolha a opção From scratch e dê um nome ao seu app.
Selecione seu workspace do Slack.

Instalar o app no seu workspace

Em seguida, você precisará adicionar ao seu workspace o app criado na etapa anterior. Você pode seguir as instruções de “Add apps to your Slack workspace” na documentação do Slack.

Configurar as definições do app do Slack

Acesse App Home
- Em Show Tabs → Messages Tab: habilite Allow users to send Slash commands and messages from the messages tab
- Acesse Socket Mode
  - Habilite Socket Mode
  - Anote o Socket Mode Handler para a variável de ambiente SLACK_APP_TOKEN
- Acesse OAuth & Permissions
  - Adicione os seguintes Bot Token Scopes:
    - app_mentions:read
    - assistant:write
    - chat:write
    - im:history
    - im:read
    - im:write
    - channels:history
  - Instale o app no seu workspace e anote o Bot User OAuth Token para a variável de ambiente SLACK_BOT_TOKEN.
- Acesse Event Subscriptions
  - Habilite Events
  - Em Subscribe to bot events, adicione:
    - app_mention
    - assistant_thread_started
    - message:im
  - Save Changes

Adicionar variáveis de ambiente (.env)

Crie um arquivo .env na raiz do projeto com as seguintes variáveis de ambiente, que permitirão que seu app se conecte ao SQL playground do ClickHouse.

SLACK_BOT_TOKEN=your-slack-bot-token
SLACK_APP_TOKEN=your-slack-app-level-token
ANTHROPIC_API_KEY=your-anthropic-api-key
CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_PORT=8443
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
CLICKHOUSE_SECURE=true

Você pode adaptar as variáveis do ClickHouse para usar seu próprio servidor ClickHouse ou uma instância no Cloud, se preferir.

Usando o bot

Inicie o bot:
uv run main.py
No Slack:
- Mencione o bot em um canal: @yourbot Who are the top contributors to the ClickHouse git repo?
- Responda na thread com uma menção: @yourbot how many contributions did these users make last week?
- Envie uma mensagem direta para o bot: Show me all tables in the demo database.

O bot responderá na thread, usando todas as mensagens anteriores como contexto quando aplicável.Contexto da thread: Ao responder em uma thread, o bot carrega todas as mensagens anteriores (exceto a atual) e as inclui como contexto para a IA.Uso de ferramentas: O bot usa apenas as ferramentas disponíveis via MCP (por exemplo, schema discovery e execução de SQL) e sempre mostrará o SQL usado e um resumo de como a resposta foi encontrada.

​Pré-requisitos

Pré-requisitos