How to build an AI Agent with Upsonic and the ClickHouse MCP server

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/use-cases/AI_ML/MCP/ai_agent_libraries/upsonic.md)

In this guide you'll learn how to build a [Upsonic](https://github.com/Upsonic/Upsonic/tree/master) AI agent that can interact with
[ClickHouse's SQL playground](https://sql.clickhouse.com/) using [ClickHouse's MCP server](https://github.com/ClickHouse/mcp-clickhouse).

Example notebook

This example can be found as a notebook in the [examples repository](https://github.com/ClickHouse/examples/blob/main/ai/mcp/upsonic/upsonic.ipynb).

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

- You'll need to have Python installed on your system.
- You'll need to have `pip` installed on your system.
- You'll need an OpenAI API key

You can run the following steps either from your Python REPL or via script.

Install libraries

## Install libraries[​](#install-libraries "Direct link to Install libraries")

Install the mcp-agent library by running the following commands:

```
pip install -q --upgrade pip
pip install -q "upsonic[loaders,tools]" openai
pip install -q ipywidgets
```

Setup credentials

## Setup credentials[​](#setup-credentials "Direct link to Setup credentials")

Next, you'll need to provide your OpenAI API key:

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

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

Next, define the credentials needed to connect to the ClickHouse SQL playground:

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

Initialize MCP server and Upsonic agent

## Initialize MCP server and Upsonic agent[​](#initialize-mcp-and-agent "Direct link to Initialize MCP server and Upsonic agent")

Now configure the ClickHouse MCP server to point at the ClickHouse SQL playground
and also initialize our agent and ask it a question:

```
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]
)

# Execute the workflow
workflow_result = database_agent.do(task)
print("\nMulti-MCP Workflow Result:")
print(workflow_result)
```

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

...