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

# Как создать AI-агента с mcp-agent и MCP-сервером ClickHouse

> Узнайте, как создать AI-агента с mcp-agent и MCP-сервером ClickHouse

В этом руководстве вы узнаете, как создать AI-агента на базе [mcp-agent](https://github.com/lastmile-ai/mcp-agent), который может взаимодействовать с
[Песочницей ClickHouse](https://sql.clickhouse.com/) с помощью [MCP-сервера ClickHouse](https://github.com/ClickHouse/mcp-clickhouse).

<Info>
  **Ноутбук с примером**

  Этот пример доступен в виде ноутбука в [репозитории examples](https://github.com/ClickHouse/examples/blob/main/ai/mcp/mcp-agent/mcp-agent.ipynb).
</Info>

<div id="prerequisites">
  ## Предварительные требования
</div>

* На вашей системе должен быть установлен Python.
* На вашей системе должен быть установлен `pip`.
* Вам понадобится ключ API OpenAI.

Вы можете выполнить следующие шаги либо в Python REPL, либо с помощью скрипта.

<Steps>
  <Step>
    ## Установка библиотек

    Установите библиотеку mcp-agent, выполнив следующие команды:

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

  <Step>
    ## Настройка учетных данных

    Далее вам потребуется указать свой API-ключ 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: ········
    ```

    Далее укажите учетные данные, необходимые для подключения к песочнице 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>
    ## Инициализация MCP Server и агента mcp-agent

    Теперь настройте MCP-сервер ClickHouse для работы с Песочницей ClickHouse,
    инициализируйте агента и задайте ему вопрос:

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

    Что я вычислил (и как)
    Я выполнил агрегации по таблицам uk.price-paid в ClickHouse:
    - общая сводка за 2025 год (количество, среднее, медиана, минимум, максимум) из uk.uk_price_paid_simple_partitioned
    - помесячная разбивка за 2025 год (транзакции, среднее, медиана)
    - топ городов в 2025 году по средней цене (города с >= 50 транзакциями)
    - сравнение по годам: 2024 vs 2025 (количество, среднее, медиана)
    - разбивка по типу недвижимости за 2025 год (количество, среднее, медиана) с использованием uk.uk_price_paid

    Ключевые показатели (из набора данных)
    - Итого за 2025 год (зарегистрированные транзакции): транзакций = 376 633; средняя цена = £362 282,66; медианная цена = £281 000; мин = £100; макс =
    £127 700 000.
    - По месяцам (2025): (месяц, транзакции, средняя цена, медианная цена)
      - Янв: 53 927, среднее £386 053, медиана £285 000
      - Фев: 58 740, среднее £371 803, медиана £285 000
      - Мар: 95 274, среднее £377 200, медиана £315 000
      - Апр: 24 987, среднее £331 692, медиана £235 000
      - Май: 39 013, среднее £342 380, медиана £255 000
      - Июн: 41 446, среднее £334 667, медиана £268 500
      - Июл: 44 431, среднее £348 293, медиана £277 500
      - Авг: 18 815, среднее £364 653, медиана £292 999
      (В наборе данных присутствуют только месяцы 1–8.)
    - Топ городов по средней цене (2025, города с ≥50 транзакциями)
      - TRING: 126 транзакций, среднее £1 973 274
      - BUCKHURST HILL: 98 транзакций, среднее £1 441 331
      - ASCOT: 175 транзакций, среднее £1 300 748
      - RADLETT: 69 транзакций, среднее £1 160 217
      - COBHAM: 115 транзакций, среднее £1 035 192
      - EAST MOLESEY, BEACONSFIELD, ESHER, CHALFONT ST GILES, THAMES DITTON также входят в топ-10 (все — пригородные/состоятельные города с высокими средними ценами).
    - Сравнение по годам (2024 vs 2025 по зарегистрированным данным)
      - 2024: 859 960 транзакций, среднее £390 879, медиана £280 000
      - 2025: 376 633 транзакции, среднее £362 283, медиана £281 000
      (Количество за 2025 год значительно ниже, поскольку набор данных охватывает лишь часть года.)
    - По типу недвижимости (2025)
      - отдельный дом: 85 362 транзакции, среднее £495 714, медиана £415 000
      - полуотдельный дом: 107 580 транзакций, среднее £319 922, медиана £270 000
      - квартира: 62 975 транзакций, среднее £298 529, медиана £227 000
      - таунхаус: 112 832 транзакции, среднее £286 616, медиана £227 000
      - прочее: 7 884 транзакции, среднее £1 087 765 (медиана £315 000) — следует учитывать эффект малой выборки и выбросов

    Важные оговорки и замечания по качеству данных
    - Набор данных за 2025 год является неполным (присутствуют только месяцы с января по август). Любые итоговые показатели за «2025 год» не являются годовыми.
    - Существуют значительные выбросы (например, макс. £127,7 млн и мин. £100). Вероятно, они включают ошибки ввода данных или нестандартные записи и завышают среднее значение. Медиана здесь является более надёжным показателем.
    - Средние значения для категории «прочее» нестабильны из-за малого/неоднородного количества записей и выбросов.
    - Я не применял фильтры по is_new, duration или другим метаданным; эти фильтры могут изменить результаты (например, при исключении новостроек или объектов с правом аренды).
    - Таблицы представляют собой записи о транзакциях в стиле Price Paid (зарегистрированные продажи) — они не отражают напрямую запрашиваемые цены или оценочную стоимость.

    Предлагаемые следующие шаги (я могу их выполнить)
    - Удалить очевидные выбросы (например, цены < £10 тыс. или > £10 млн) и пересчитать средние значения/медианы.
    - Подготовить сводки и карты по регионам / графствам / почтовым зонам.
    - Вычислить медиану «месяц к месяцу» или скользящую медиану за 3 месяца для отображения тенденции в 2025 году.
    - Подготовить темпы роста год к году (YoY) по месяцам (например, март 2025 vs март 2024).
    - Составить прогноз на полный 2025 год с использованием простой экстраполяции или моделирования временных рядов (но лучше после принятия решения о том, как обрабатывать отсутствующие месяцы/выбросы).

    Если хотите, я могу:
    - Повторно выполнить те же агрегации после удаления экстремальных выбросов и показать очищенные результаты.
    - Подготовить помесячный рост YoY и графики (могу вернуть агрегаты в формате CSV или JSON для построения диаграмм).
    Что бы вы хотели сделать дальше?
    [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>