Como criar um agente de IA com Upsonic e o ClickHouse MCP server

Aprenda a criar um agente de IA com Upsonic e o ClickHouse MCP server

Neste guia, você aprenderá a criar um agente de IA com Upsonic que pode interagir com o playground SQL do ClickHouse usando o ClickHouse MCP server.

Notebook de exemplo

Este exemplo está disponível como um notebook no repositório de exemplos.

​

Pré-requisitos

• Você precisará ter o Python instalado no seu sistema.
• Você precisará ter o pip instalado no seu sistema.
• Você precisará de uma chave de API da OpenAI

Você pode executar as etapas a seguir tanto no REPL do Python quanto em um script.

1. ​

   Instale as bibliotecas

   Instale a biblioteca mcp-agent executando os comandos a seguir:

   pip install -q --upgrade pip
   pip install -q "upsonic[loaders,tools]" openai
   pip install -q ipywidgets
   
2. ​

   Configurar credenciais

   Em seguida, você precisará informar sua API key da OpenAI:

   import os, getpass
   os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter OpenAI API Key:")
   

   Response

   Enter OpenAI API Key: ········
   

   Em seguida, defina as credenciais necessárias para acessar o playground do ClickHouse SQL:

   env = {
       "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
       "CLICKHOUSE_PORT": "8443",
       "CLICKHOUSE_USER": "demo",
       "CLICKHOUSE_PASSWORD": "",
       "CLICKHOUSE_SECURE": "true"
   }
   
3. ​

   Inicializar o MCP Server e o agente Upsonic

   Agora configure o ClickHouse MCP server para apontar para o playground do ClickHouse SQL, inicialize o agente e faça uma pergunta:

   from upsonic import Agent, Task
   from upsonic.models.openai import OpenAIResponsesModel
   

   class DatabaseMCP:
       """
       MCP server for ClickHouse database operations.
       Provides tools for querying tables and databases
       """
       command="uv"
       args=[
           "run",
           "--with",
           "mcp-clickhouse",
           "--python",
           "3.10",
           "mcp-clickhouse"
       ]
       env=env
   
   database_agent = Agent(
       name="Data Analyst",
       role="ClickHouse specialist.",
       goal="Query ClickHouse database and tables and answer questions",
       model=OpenAIResponsesModel(model_name="gpt-5-mini-2025-08-07")
   )
   
   task = Task(
       description="Tell me what happened in the UK property market in the 2020s. Use ClickHouse.",
       tools=[DatabaseMCP]
   )
   
   # Executar o fluxo de trabalho
   workflow_result = database_agent.do(task)
   print("\nMulti-MCP Workflow Result:")
   print(workflow_result)
   

   Response

   2025-10-10 11:26:12,758 - mcp.server.lowlevel.server - INFO - Processing request of type ListToolsRequest
   Found 3 tools from DatabaseMCP
     - list_databases: List available ClickHouse databases
     - list_tables: List available ClickHouse tables in a database, including schema, comment,
   row count, and column count.
     - run_select_query: Run a SELECT query in a ClickHouse database
   ✅ MCP tools discovered via thread
   
   ...
   
   [10/10/25 11:26:20] INFO     Starting MCP server 'mcp-clickhouse' with transport 'stdio'                                      server.py:1502
   2025-10-10 11:26:20,183 - mcp.server.lowlevel.server - INFO - Processing request of type ListToolsRequest
   2025-10-10 11:26:20,184 - mcp.server.lowlevel.server - INFO - Processing request of type ListPromptsRequest
   2025-10-10 11:26:20,185 - mcp.server.lowlevel.server - INFO - Processing request of type ListResourcesRequest
   [INFO] 2025-10-10T11:26:20 mcp_agent.workflows.llm.augmented_llm_openai.database-anayst - Using reasoning model 'gpt-5-mini-2025-08-07' with
   'medium' reasoning effort
   [INFO] 2025-10-10T11:26:23 mcp_agent.mcp.mcp_aggregator.database-anayst - Requesting tool call
   {
     "data": {
       "progress_action": "Calling Tool",
       "tool_name": "list_databases",
       "server_name": "clickhouse",
       "agent_name": "database-anayst"
     }
   }
   2025-10-10 11:26:23,477 - mcp.server.lowlevel.server - INFO - Processing request of type CallToolRequest
   2025-10-10 11:26:23,479 - mcp-clickhouse - INFO - Listing all databases
   2025-10-10 11:26:23,479 - mcp-clickhouse - INFO - Creating ClickHouse client connection to sql-clickhouse.clickhouse.com:8443 as demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
   2025-10-10 11:26:24,375 - mcp-clickhouse - INFO - Successfully connected to ClickHouse server version 25.8.1.8344
   2025-10-10 11:26:24,551 - mcp-clickhouse - INFO - Found 38 databases
   [INFO] 2025-10-10T11:26:26 mcp_agent.mcp.mcp_aggregator.database-anayst - Requesting tool call
   {
     "data": {
       "progress_action": "Calling Tool",
       "tool_name": "list_tables",
       "server_name": "clickhouse",
       "agent_name": "database-anayst"
     }
   }
   2025-10-10 11:26:26,825 - mcp.server.lowlevel.server - INFO - Processing request of type CallToolRequest
   2025-10-10 11:26:26,832 - mcp-clickhouse - INFO - Listing tables in database 'uk'
   2025-10-10 11:26:26,832 - mcp-clickhouse - INFO - Creating ClickHouse client connection to sql-clickhouse.clickhouse.com:8443 as demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
   2025-10-10 11:26:27,311 - mcp-clickhouse - INFO - Successfully connected to ClickHouse server version 25.8.1.8344
   2025-10-10 11:26:28,738 - mcp-clickhouse - INFO - Found 9 tables
   [INFO] 2025-10-10T11:26:48 mcp_agent.mcp.mcp_aggregator.database-anayst - Requesting tool call
   {
     "data": {
       "progress_action": "Calling Tool",
       "tool_name": "run_select_query",
       "server_name": "clickhouse",
       "agent_name": "database-anayst"
     }
   }
   [INFO] 2025-10-10T11:26:48 mcp_agent.mcp.mcp_aggregator.database-anayst - Requesting tool call
   {
     "data": {
       "progress_action": "Calling Tool",
       "tool_name": "run_select_query",
       "server_name": "clickhouse",
       "agent_name": "database-anayst"
     }
   }
   [INFO] 2025-10-10T11:26:48 mcp_agent.mcp.mcp_aggregator.database-anayst - Requesting tool call
   {
     "data": {
       "progress_action": "Calling Tool",
       "tool_name": "run_select_query",
       "server_name": "clickhouse",
       "agent_name": "database-anayst"
     }
   }
   [INFO] 2025-10-10T11:26:48 mcp_agent.mcp.mcp_aggregator.database-anayst - Requesting tool call
   {
     "data": {
       "progress_action": "Calling Tool",
       "tool_name": "run_select_query",
       "server_name": "clickhouse",
       "agent_name": "database-anayst"
     }
   }
   [INFO] 2025-10-10T11:26:48 mcp_agent.mcp.mcp_aggregator.database-anayst - Requesting tool call
   {
     "data": {
       "progress_action": "Calling Tool",
       "tool_name": "run_select_query",
       "server_name": "clickhouse",
       "agent_name": "database-anayst"
     }
   }
   2025-10-10 11:26:48,366 - mcp.server.lowlevel.server - INFO - Processing request of type CallToolRequest
   2025-10-10 11:26:48,367 - mcp-clickhouse - INFO - Executing SELECT query: SELECT
   count(*) AS transactions,
   avg(price) AS avg_price,
   quantileExact(0.5)(price) AS median_price,
   min(price) AS min_price,
   max(price) AS max_price
   FROM uk.uk_price_paid_simple_partitioned
   WHERE toYear(date)=2025
   2025-10-10 11:26:48,367 - mcp-clickhouse - INFO - Creating ClickHouse client connection to sql-clickhouse.clickhouse.com:8443 as demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
   2025-10-10 11:26:49,262 - mcp-clickhouse - INFO - Successfully connected to ClickHouse server version 25.8.1.8344
   2025-10-10 11:26:49,407 - mcp-clickhouse - INFO - Query returned 1 rows
   2025-10-10 11:26:49,408 - mcp.server.lowlevel.server - INFO - Processing request of type CallToolRequest
   2025-10-10 11:26:49,408 - mcp-clickhouse - INFO - Executing SELECT query: SELECT toMonth(date) AS month, count(*) AS transactions, avg(price) AS avg_price, quantileExact(0.5)(price) AS median_price
   FROM uk.uk_price_paid_simple_partitioned
   WHERE toYear(date)=2025
   GROUP BY month
   ORDER BY month
   2025-10-10 11:26:49,408 - mcp-clickhouse - INFO - Creating ClickHouse client connection to sql-clickhouse.clickhouse.com:8443 as demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
   2025-10-10 11:26:49,857 - mcp-clickhouse - INFO - Successfully connected to ClickHouse server version 25.8.1.8344
   2025-10-10 11:26:50,067 - mcp-clickhouse - INFO - Query returned 8 rows
   2025-10-10 11:26:50,068 - mcp.server.lowlevel.server - INFO - Processing request of type CallToolRequest
   2025-10-10 11:26:50,069 - mcp-clickhouse - INFO - Executing SELECT query: SELECT town, count(*) AS transactions, avg(price) AS avg_price
   FROM uk.uk_price_paid_simple_partitioned
   WHERE toYear(date)=2025
   GROUP BY town
   HAVING transactions >= 50
   ORDER BY avg_price DESC
   LIMIT 10
   2025-10-10 11:26:50,069 - mcp-clickhouse - INFO - Creating ClickHouse client connection to sql-clickhouse.clickhouse.com:8443 as demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
   2025-10-10 11:26:50,594 - mcp-clickhouse - INFO - Successfully connected to ClickHouse server version 25.8.1.8344
   2025-10-10 11:26:50,741 - mcp-clickhouse - INFO - Query returned 10 rows
   2025-10-10 11:26:50,744 - mcp.server.lowlevel.server - INFO - Processing request of type CallToolRequest
   2025-10-10 11:26:50,746 - mcp-clickhouse - INFO - Executing SELECT query: SELECT toYear(date) AS year, count(*) AS transactions, avg(price) AS avg_price, quantileExact(0.5)(price) AS median_price
   FROM uk.uk_price_paid_simple_partitioned
   WHERE toYear(date) IN (2024,2025)
   GROUP BY year
   ORDER BY year
   2025-10-10 11:26:50,747 - mcp-clickhouse - INFO - Creating ClickHouse client connection to sql-clickhouse.clickhouse.com:8443 as demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
   2025-10-10 11:26:51,256 - mcp-clickhouse - INFO - Successfully connected to ClickHouse server version 25.8.1.8344
   2025-10-10 11:26:51,447 - mcp-clickhouse - INFO - Query returned 2 rows
   2025-10-10 11:26:51,449 - mcp.server.lowlevel.server - INFO - Processing request of type CallToolRequest
   2025-10-10 11:26:51,452 - mcp-clickhouse - INFO - Executing SELECT query: SELECT type, count(*) AS transactions, avg(price) AS avg_price, quantileExact(0.5)(price) AS median_price
   FROM uk.uk_price_paid
   WHERE toYear(date)=2025
   GROUP BY type
   ORDER BY avg_price DESC
   2025-10-10 11:26:51,452 - mcp-clickhouse - INFO - Creating ClickHouse client connection to sql-clickhouse.clickhouse.com:8443 as demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
   2025-10-10 11:26:51,952 - mcp-clickhouse - INFO - Successfully connected to ClickHouse server version 25.8.1.8344
   2025-10-10 11:26:52,166 - mcp-clickhouse - INFO - Query returned 5 rows
   [INFO] 2025-10-10T11:27:51 mcp_agent.mcp_basic_agent - Summary (TL;DR)
   - Based on the UK Price Paid tables in ClickHouse, for transactions recorded in 2025 so far there are 376,633 sales with an average price of
   £362,283 and a median price of £281,000. The data appears to include only months Jan–Aug 2025 (so 2025 is incomplete). There are extreme
   outliers (min £100, max £127,700,000) that skew the mean.
   
   O que calculei (como)
   Executei agregações nas tabelas uk.price-paid no ClickHouse:
   - resumo geral de 2025 (contagem, média, mediana, mínimo, máximo) de uk.uk_price_paid_simple_partitioned
   - detalhamento mensal de 2025 (transações, média, mediana)
   - principais cidades em 2025 por preço médio (cidades com >= 50 transações)
   - comparação anual: 2024 vs 2025 (contagem, média, mediana)
   - detalhamento por tipo de imóvel em 2025 (contagens, média, mediana) usando uk.uk_price_paid
   
   Números-chave (do conjunto de dados)
   - Geral 2025 (transações registradas): transações = 376.633; preço médio = £362.282,66; mediana de preço = £281.000; mín = £100; máx =
   £127.700.000.
   - Por mês (2025): (mês, transações, preço médio, mediana de preço)
     - Jan: 53.927, média £386.053, mediana £285.000
     - Fev: 58.740, média £371.803, mediana £285.000
     - Mar: 95.274, média £377.200, mediana £315.000
     - Abr: 24.987, média £331.692, mediana £235.000
     - Mai: 39.013, média £342.380, mediana £255.000
     - Jun: 41.446, média £334.667, mediana £268.500
     - Jul: 44.431, média £348.293, mediana £277.500
     - Ago: 18.815, média £364.653, mediana £292.999
     (Apenas os meses 1–8 estão presentes no conjunto de dados.)
   - Principais cidades por preço médio (2025, cidades com ≥50 transações)
     - TRING: 126 transações, média £1.973.274
     - BUCKHURST HILL: 98 transações, média £1.441.331
     - ASCOT: 175 transações, média £1.300.748
     - RADLETT: 69 transações, média £1.160.217
     - COBHAM: 115 transações, média £1.035.192
     - EAST MOLESEY, BEACONSFIELD, ESHER, CHALFONT ST GILES, THAMES DITTON também estão no top 10 (todas cidades de alto padrão para pendulares/abastadas).
   - Comparação anual (2024 vs 2025 conforme registrado)
     - 2024: 859.960 transações, média £390.879, mediana £280.000
     - 2025: 376.633 transações, média £362.283, mediana £281.000
     (Os números de 2025 são muito menores porque o conjunto de dados inclui apenas parte do ano.)
   - Por tipo de imóvel (2025)
     - isolado: 85.362 transações, média £495.714, mediana £415.000
     - geminado: 107.580 transações, média £319.922, mediana £270.000
     - apartamento: 62.975 transações, média £298.529, mediana £227.000
     - em fila: 112.832 transações, média £286.616, mediana £227.000
     - outro: 7.884 transações, média £1.087.765 (mediana £315.000) — observação: efeito de grupo pequeno e valores discrepantes
   
   Ressalvas importantes e notas sobre qualidade dos dados
   - O conjunto de dados parece incompleto para 2025 (apenas os meses de jan–ago estão presentes). Quaisquer totais de "2025" não são valores anuais completos.
   - Existem grandes valores discrepantes (ex.: máx £127,7M e mín £100). Estes provavelmente incluem erros de entrada de dados ou registros não padronizados e inflacionam a
   média. A mediana geralmente é uma medida mais robusta aqui.
   - As médias do tipo de imóvel "outro" são instáveis devido a contagens baixas/heterogêneas e valores discrepantes.
   - Não filtrei por is_new, duration ou outros metadados; esses filtros podem alterar os resultados (por exemplo, excluindo imóveis novos ou
   arrendamentos).
   - As tabelas são registros de transações no estilo Price Paid (vendas registradas) — elas não representam diretamente preços pedidos ou avaliações.
   
   Próximos passos sugeridos (posso executá-los)
   - Remover valores discrepantes óbvios (ex.: preços < £10k ou > £10M) e recalcular médias/medianas.
   - Produzir resumos e mapas regionais / por condado / por área de código postal.
   - Calcular mediana mês a mês ou média móvel de 3 meses para mostrar a tendência ao longo de 2025.
   - Produzir taxas de crescimento ano a ano (YoY) por mês (ex.: mar 2025 vs mar 2024).
   - Previsão para o ano completo de 2025 usando extrapolação simples ou modelagem de séries temporais (mas melhor após decidir como lidar com
   meses ausentes/valores discrepantes).
   
   Se desejar, posso:
   - Reexecutar as mesmas agregações após remover valores discrepantes extremos e mostrar os resultados limpos.
   - Produzir crescimento mensal YoY e gráficos (posso retornar agregados em CSV ou JSON que você pode usar para criar gráficos).
   O que você gostaria que eu fizesse a seguir?
   [INFO] 2025-10-10T11:27:51 mcp_agent.mcp.mcp_aggregator.database-anayst - Last aggregator closing, shutting down all persistent
   connections...
   [INFO] 2025-10-10T11:27:51 mcp_agent.mcp.mcp_connection_manager - Disconnecting all persistent server connections...
   [INFO] 2025-10-10T11:27:51 mcp_agent.mcp.mcp_connection_manager - clickhouse: Requesting shutdown...
   [INFO] 2025-10-10T11:27:51 mcp_agent.mcp.mcp_connection_manager - All persistent server connections signaled to disconnect.
   [INFO] 2025-10-10T11:27:52 mcp_agent.mcp.mcp_aggregator.database-anayst - Connection manager successfully closed and removed from context
   [INFO] 2025-10-10T11:27:52 mcp_agent.mcp_basic_agent - MCPApp cleanup
   {
     "data": {
       "progress_action": "Finished",
       "target": "mcp_basic_agent",
       "agent_name": "mcp_application_loop"
     }
   }