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

# Cómo crear un agente de IA con mcp-agent y el servidor MCP de ClickHouse

> Aprende a crear un agente de IA con mcp-agent y el servidor MCP de ClickHouse

En esta guía aprenderás a crear un agente de IA con [mcp-agent](https://github.com/lastmile-ai/mcp-agent) que puede interactuar con
el [Playground de SQL de ClickHouse](https://sql.clickhouse.com/) mediante el [servidor MCP de ClickHouse](https://github.com/ClickHouse/mcp-clickhouse).

<Info>
  **Notebook de ejemplo**

  Este ejemplo está disponible como notebook en el [repositorio de ejemplos](https://github.com/ClickHouse/examples/blob/main/ai/mcp/mcp-agent/mcp-agent.ipynb).
</Info>

<div id="prerequisites">
  ## Requisitos previos
</div>

* Debes tener Python instalado en tu sistema.
* Debes tener `pip` instalado en tu sistema.
* Necesitarás una clave de API de OpenAI

Puedes seguir estos pasos desde tu REPL de Python o mediante un script.

<Steps>
  <Step>
    ## Instalar bibliotecas

    Instala la biblioteca mcp-agent ejecutando los siguientes comandos:

    ```python theme={null}
    pip install -q --upgrade pip
    pip install -q mcp-agent openai
    pip install -q ipywidgets
    ```
  </Step>

  <Step>
    ## Configura las credenciales

    A continuación, deberás proporcionar tu clave de API de 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: ········
    ```

    A continuación, define las credenciales necesarias para conectarse al Playground de SQL de ClickHouse:

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

  <Step>
    ## Inicializar el MCP Server y el agente mcp-agent

    Ahora configure el ClickHouse MCP server para que apunte al Playground de SQL de ClickHouse,
    inicialice el agente y hágale una pregunta:

    ```python theme={null}
    from mcp_agent.app import MCPApp
    from mcp_agent.agents.agent import Agent
    from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM
    from mcp_agent.config import Settings, MCPSettings, MCPServerSettings, OpenAISettings
    ```

    ```python theme={null}
    settings = Settings(
        execution_engine="asyncio",
        openai=OpenAISettings(
            default_model="gpt-5-mini-2025-08-07",
        ),
        mcp=MCPSettings(
            servers={
                "clickhouse": MCPServerSettings(
                    command='uv',
                    args=[
                        "run",
                        "--with", "mcp-clickhouse",
                        "--python", "3.10",
                        "mcp-clickhouse"
                    ],
                    env=env
                ),
            }
        ),
    )

    app = MCPApp(name="mcp_basic_agent", settings=settings)

    async with app.run() as mcp_agent_app:
        logger = mcp_agent_app.logger
        data_agent = Agent(
            name="database-anayst",
            instruction="""You can answer questions with help from a ClickHouse database.""",
            server_names=["clickhouse"],
        )

        async with data_agent:
            llm = await data_agent.attach_llm(OpenAIAugmentedLLM)
            result = await llm.generate_str(
                message="Tell me about UK property prices in 2025. Use ClickHouse to work it out."
            )
            
            logger.info(result)
    ```

    ```response title="Response" theme={null}
    [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.

    Lo que calculé (cómo)
    Ejecuté agregaciones en las tablas uk.price-paid en ClickHouse:
    - resumen general de 2025 (recuento, media, mediana, mínimo, máximo) de uk.uk_price_paid_simple_partitioned
    - desglose mensual para 2025 (transacciones, media, mediana)
    - principales ciudades en 2025 por precio promedio (ciudades con >= 50 transacciones)
    - comparación anual: 2024 vs 2025 (recuento, media, mediana)
    - desglose por tipo de propiedad para 2025 (recuentos, promedio, mediana) usando uk.uk_price_paid

    Cifras clave (del conjunto de datos)
    - Total 2025 (transacciones registradas): transacciones = 376.633; precio medio = £362.282,66; precio mediano = £281.000; mín = £100; máx =
    £127.700.000.
    - Por mes (2025): (mes, transacciones, precio medio, precio mediano)
      - Ene: 53.927, media £386.053, mediana £285.000
      - Feb: 58.740, media £371.803, mediana £285.000
      - Mar: 95.274, media £377.200, mediana £315.000
      - Abr: 24.987, media £331.692, mediana £235.000
      - May: 39.013, media £342.380, mediana £255.000
      - Jun: 41.446, media £334.667, mediana £268.500
      - Jul: 44.431, media £348.293, mediana £277.500
      - Ago: 18.815, media £364.653, mediana £292.999
      (Solo los meses 1–8 están presentes en el conjunto de datos.)
    - Principales ciudades por precio promedio (2025, ciudades con ≥50 transacciones)
      - TRING: 126 txns, promedio £1.973.274
      - BUCKHURST HILL: 98 txns, promedio £1.441.331
      - ASCOT: 175 txns, promedio £1.300.748
      - RADLETT: 69 txns, promedio £1.160.217
      - COBHAM: 115 txns, promedio £1.035.192
      - EAST MOLESEY, BEACONSFIELD, ESHER, CHALFONT ST GILES, THAMES DITTON también están en el top 10 (todas ciudades de alto promedio para commuters/adineradas).
    - Comparación anual (2024 vs 2025 según registros)
      - 2024: 859.960 transacciones, media £390.879, mediana £280.000
      - 2025: 376.633 transacciones, media £362.283, mediana £281.000
      (Los recuentos de 2025 son mucho menores porque el conjunto de datos solo incluye parte del año.)
    - Por tipo de propiedad (2025)
      - unifamiliar: 85.362 txns, promedio £495.714, mediana £415.000
      - adosado semi-independiente: 107.580 txns, promedio £319.922, mediana £270.000
      - piso: 62.975 txns, promedio £298.529, mediana £227.000
      - adosado: 112.832 txns, promedio £286.616, mediana £227.000
      - otro: 7.884 txns, promedio £1.087.765 (mediana £315.000) — nota: efecto de grupo pequeño y valores atípicos

    Advertencias importantes y notas sobre calidad de datos
    - El conjunto de datos parece parcial para 2025 (solo están presentes los meses de enero a agosto). Cualquier total de "2025" no corresponde a cifras de año completo.
    - Existen grandes valores atípicos (p. ej., máx £127,7 M y mín £100). Es probable que incluyan errores de entrada de datos o registros no estándar que inflan la
    media. La mediana suele ser una medida más robusta en este caso.
    - Los promedios del tipo de propiedad "otro" son inestables debido a recuentos bajos/heterogéneos y valores atípicos.
    - No filtré por is_new, duration u otros metadatos; esos filtros pueden cambiar los resultados (por ejemplo, excluyendo obra nueva o
    arrendamientos).
    - Las tablas son registros de transacciones de tipo Price Paid (ventas registradas): no representan directamente precios de oferta ni valoraciones.

    Próximos pasos sugeridos (puedo ejecutarlos)
    - Eliminar valores atípicos obvios (p. ej., precios < £10k o > £10M) y recalcular promedios/medianas.
    - Producir resúmenes y mapas por región / condado / área de código postal.
    - Calcular la mediana mensual o móvil de 3 meses para mostrar la tendencia a lo largo de 2025.
    - Producir tasas de crecimiento interanual (YoY) por mes (p. ej., mar 2025 vs mar 2024).
    - Pronóstico para todo 2025 usando extrapolación simple o modelado de series temporales (pero mejor después de decidir cómo manejar los meses faltantes/valores atípicos).

    Si lo desea, puedo:
    - Volver a ejecutar las mismas agregaciones después de eliminar los valores atípicos extremos y mostrar los resultados limpios.
    - Producir el crecimiento mensual interanual y gráficos (puedo devolver agregados en CSV o JSON que pueda graficar).
    ¿Qué le gustaría que hiciera a continuación?
    [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>