> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/Upsonic/Upsonic/tree/master) que pode interagir com o
[playground SQL do ClickHouse](https://sql.clickhouse.com/) usando o [ClickHouse MCP server](https://github.com/ClickHouse/mcp-clickhouse).

<Info>
  **Notebook de exemplo**

  Este exemplo está disponível como um notebook no [repositório de exemplos](https://github.com/ClickHouse/examples/blob/main/ai/mcp/upsonic/upsonic.ipynb).
</Info>

<div id="prerequisites">
  ## Pré-requisitos
</div>

* 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.

<Steps>
  <Step>
    ## Instale as bibliotecas

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

    ```python theme={null}
    pip install -q --upgrade pip
    pip install -q "upsonic[loaders,tools]" openai
    pip install -q ipywidgets
    ```
  </Step>

  <Step>
    ## Configurar credenciais

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

    ```python theme={null}
    import os, getpass
    os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter OpenAI API Key:")
    ```

    ```response title="Response" theme={null}
    Enter OpenAI API Key: ········
    ```

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

    ```python theme={null}
    env = {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true"
    }
    ```
  </Step>

  <Step>
    ## 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:

    ```python theme={null}
    from upsonic import Agent, Task
    from upsonic.models.openai import OpenAIResponsesModel
    ```

    ```python theme={null}
    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 title="Response" theme={null}
    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"
      }
    }
    ```
  </Step>
</Steps>