How to build an AI Agent with CrewAI 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/mcp-agent.md)

In this guide you'll learn how to build a [mcp-agent](https://github.com/lastmile-ai/mcp-agent) 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/mcp-agent/mcp-agent.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 mcp-agent 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 mcp-agent agent

## Initialize MCP server and mcp-agent agent[​](#initialize-mcp-and-agent "Direct link to Initialize MCP server and mcp-agent 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 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
```

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