Skip to content

Commit 453b5c0

Browse files
BlargianBlargian
authored
Merge pull request #4552 from mneedham/moar-mcp-agent-examples
Claude + MSFT libraries
2 parents 1a46bf8 + 6733fda commit 453b5c0

File tree

2 files changed

+276
-0
lines changed

2 files changed

+276
-0
lines changed

‎docs/use-cases/AI_ML/MCP/ai_agent_libraries/claude-agent-sdk.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
slug: /use-cases/AI/MCP/ai-agent-libraries/claude-agent-sdk
3+
sidebar_label: 'Integrate Claude Agent SDK'
4+
title: 'How to build an AI Agent with Claude Agent SDK and the ClickHouse MCP Server'
5+
pagination_prev: null
6+
pagination_next: null
7+
description: 'Learn how build an AI Agent with Claude Agent SDK and the ClickHouse MCP Server'
8+
keywords: ['ClickHouse', 'MCP', 'Claude']
9+
show_related_blogs: true
10+
doc_type: 'guide'
11+
---
12+
13+
# How to build an AI Agent with Claude Agent SDK and the ClickHouse MCP Server
14+
15+
In this guide you'll learn how to build a [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview) AI agent that can interact with
16+
[ClickHouse's SQL playground](https://sql.clickhouse.com/) using [ClickHouse's MCP Server](https://github.com/ClickHouse/mcp-clickhouse).
17+
18+
:::note Example notebook
19+
This example can be found as a notebook in the [examples repository](https://github.com/ClickHouse/examples/blob/main/ai/mcp/claude-agent/claude-agent.ipynb).
20+
:::
21+
22+
## Prerequisites {#prerequisites}
23+
- You'll need to have Python installed on your system.
24+
- You'll need to have `pip` installed on your system.
25+
- You'll need an Anthropic API key
26+
27+
You can run the following steps either from your Python REPL or via script.
28+
29+
<VerticalStepper headerLevel="h2">
30+
31+
## Install libraries {#install-libraries}
32+
33+
Install the Claude Agent SDK library by running the following commands:
34+
35+
```python
36+
!pip install -q --upgrade pip
37+
!pip install -q claude-agent-sdk
38+
!pip install -q ipywidgets
39+
```
40+
41+
## Setup credentials {#setup-credentials}
42+
43+
Next, you'll need to provide your Anthropic API key:
44+
45+
```python
46+
import os, getpass
47+
os.environ["ANTHROPIC_API_KEY"] = getpass.getpass("Enter Anthropic API Key:")
48+
```
49+
50+
```response title="Response"
51+
Enter Anthropic API Key: ········
52+
```
53+
54+
Next, define the credentials needed to connect to the ClickHouse SQL playground:
55+
56+
```python
57+
env = {
58+
"CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
59+
"CLICKHOUSE_PORT": "8443",
60+
"CLICKHOUSE_USER": "demo",
61+
"CLICKHOUSE_PASSWORD": "",
62+
"CLICKHOUSE_SECURE": "true"
63+
}
64+
```
65+
66+
## Initialize MCP Server and Claude Agent SDK agent {#initialize-mcp-and-agent}
67+
68+
Now configure the ClickHouse MCP Server to point at the ClickHouse SQL playground
69+
and also initialize our agent and ask it a question:
70+
71+
```python
72+
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, UserMessage, TextBlock, ToolUseBlock
73+
```
74+
75+
```python
76+
options = ClaudeAgentOptions(
77+
allowed_tools=[
78+
"mcp__mcp-clickhouse__list_databases",
79+
"mcp__mcp-clickhouse__list_tables",
80+
"mcp__mcp-clickhouse__run_select_query",
81+
"mcp__mcp-clickhouse__run_chdb_select_query"
82+
],
83+
mcp_servers={
84+
"mcp-clickhouse": {
85+
"command": "uv",
86+
"args": [
87+
"run",
88+
"--with", "mcp-clickhouse",
89+
"--python", "3.10",
90+
"mcp-clickhouse"
91+
],
92+
"env": env
93+
}
94+
}
95+
)
96+
97+
98+
async for message in query(prompt="Tell me something interesting about UK property sales", options=options):
99+
if isinstance(message, AssistantMessage):
100+
for block in message.content:
101+
if isinstance(block, TextBlock):
102+
print(f"🤖 {block.text}")
103+
if isinstance(block, ToolUseBlock):
104+
print(f"🛠️ {block.name} {block.input}")
105+
elif isinstance(message, UserMessage):
106+
for block in message.content:
107+
if isinstance(block, TextBlock):
108+
print(block.text)
109+
```
110+
111+
Note the code inside the `for` block is filtering the output for brevity.
112+
113+
```response title="Response"
114+
🤖 I'll query the ClickHouse database to find something interesting about UK property sales.
115+
116+
Let me first see what databases are available:
117+
🛠️ mcp__mcp-clickhouse__list_databases {}
118+
🤖 Great! There's a "uk" database. Let me see what tables are available:
119+
🛠️ mcp__mcp-clickhouse__list_tables {'database': 'uk'}
120+
🤖 Perfect! The `uk_price_paid` table has over 30 million property sales records. Let me find something interesting:
121+
🛠️ mcp__mcp-clickhouse__run_select_query {'query': "\nSELECT \n street,\n town,\n max(price) as max_price,\n min(price) as min_price,\n max(price) - min(price) as price_difference,\n count() as sales_count\nFROM uk.uk_price_paid\nWHERE street != ''\nGROUP BY street, town\nHAVING sales_count > 100\nORDER BY price_difference DESC\nLIMIT 1\n"}
122+
🤖 Here's something fascinating: **Baker Street in London** (yes, the famous Sherlock Holmes street!) has the largest price range of any street with over 100 sales - properties sold for as low as **£2,500** and as high as **£594.3 million**, a staggering difference of over £594 million!
123+
124+
This makes sense given Baker Street is one of London's most prestigious addresses, running through wealthy areas like Marylebone, and has had 541 recorded sales in this dataset.
125+
```
126+
127+
</VerticalStepper>

‎docs/use-cases/AI_ML/MCP/ai_agent_libraries/microsoft-agent-framework.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
slug: /use-cases/AI/MCP/ai-agent-libraries/microsoft-agent-framework
3+
sidebar_label: 'Integrate Microsoft Agent Framework'
4+
title: 'How to build an AI Agent with Microsoft Agent Framework and the ClickHouse MCP Server'
5+
pagination_prev: null
6+
pagination_next: null
7+
description: 'Learn how build an AI Agent with Microsoft Agent Framework and the ClickHouse MCP Server'
8+
keywords: ['ClickHouse', 'MCP', 'Microsoft']
9+
show_related_blogs: true
10+
doc_type: 'guide'
11+
---
12+
13+
# How to build an AI Agent with Microsoft Agent Framework and the ClickHouse MCP Server
14+
15+
In this guide you'll learn how to build a [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) AI agent that can interact with
16+
[ClickHouse's SQL playground](https://sql.clickhouse.com/) using [ClickHouse's MCP Server](https://github.com/ClickHouse/mcp-clickhouse).
17+
18+
:::note Example notebook
19+
This example can be found as a notebook in the [examples repository](https://github.com/ClickHouse/examples/blob/main/ai/mcp/microsoft-agent-framework/microsoft-agent-framework.ipynb).
20+
:::
21+
22+
## Prerequisites {#prerequisites}
23+
- You'll need to have Python installed on your system.
24+
- You'll need to have `pip` installed on your system.
25+
- You'll need an OpenAI API key
26+
27+
You can run the following steps either from your Python REPL or via script.
28+
29+
<VerticalStepper headerLevel="h2">
30+
31+
## Install libraries {#install-libraries}
32+
33+
Install the Microsoft Agent Framework library by running the following commands:
34+
35+
```python
36+
!pip install -q --upgrade pip
37+
!pip install -q agent-framework --pre
38+
!pip install -q ipywidgets
39+
```
40+
41+
## Setup credentials {#setup-credentials}
42+
43+
Next, you'll need to provide your OpenAI API key:
44+
45+
```python
46+
import os, getpass
47+
os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter OpenAI API Key:")
48+
```
49+
50+
```response title="Response"
51+
Enter OpenAI API Key: ········
52+
```
53+
54+
Next, define the credentials needed to connect to the ClickHouse SQL playground:
55+
56+
```python
57+
env = {
58+
"CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
59+
"CLICKHOUSE_PORT": "8443",
60+
"CLICKHOUSE_USER": "demo",
61+
"CLICKHOUSE_PASSWORD": "",
62+
"CLICKHOUSE_SECURE": "true"
63+
}
64+
```
65+
66+
## Initialize MCP Server and Microsoft Agent Framework agent {#initialize-mcp-and-agent}
67+
68+
Now configure the ClickHouse MCP Server to point at the ClickHouse SQL playground
69+
and also initialize our agent and ask it a question:
70+
71+
```python
72+
from agent_framework import ChatAgent, MCPStdioTool
73+
from agent_framework.openai import OpenAIResponsesClient
74+
```
75+
76+
```python
77+
clickhouse_mcp_server = MCPStdioTool(
78+
name="clickhouse",
79+
command="uv",
80+
args=[
81+
"run",
82+
"--with",
83+
"mcp-clickhouse",
84+
"--python",
85+
"3.10",
86+
"mcp-clickhouse"
87+
],
88+
env=env
89+
)
90+
91+
92+
async with ChatAgent(
93+
chat_client=OpenAIResponsesClient(model_id="gpt-5-mini-2025-08-07"),
94+
name="HousePricesAgent",
95+
instructions="You are a helpful assistant that can help query a ClickHouse database",
96+
tools=clickhouse_mcp_server,
97+
) as agent:
98+
query = "Tell me about UK property prices over the last five years"
99+
print(f"User: {query}")
100+
async for chunk in agent.run_stream(query):
101+
print(chunk.text, end="", flush=True)
102+
print("\n\n")
103+
```
104+
105+
The output of running this script is shown below:
106+
107+
```response title="Response"
108+
User: Tell me about UK property prices over the last five years
109+
I looked at monthly UK sold-price records in the uk.uk_price_paid_simple_partitioned table for the last five years (toStartOfMonth(date), from Oct 2020 → Aug 2025). Summary and key points:
110+
111+
What I measured
112+
- Metrics: monthly median price, mean price, and transaction count (price paid records).
113+
- Period covered: months starting 2020-10-01 through 2025-08-01 (last five years from today).
114+
115+
High-level findings
116+
- Median price rose from £255,000 (2020-10) to £294,500 (2025-08) — an increase of about +15.4% over five years.
117+
- Equivalent compound annual growth rate (CAGR) for the median ≈ +2.9% per year.
118+
- Mean price fell slightly from about £376,538 (2020-10) to £364,653 (2025-08) — a decline of ≈ −3.2% over five years.
119+
- Mean-price CAGR ≈ −0.6% per year.
120+
- The divergence (median up, mean slightly down) suggests changes in the mix of transactions (fewer very-high-value sales or other compositional effects), since the mean is sensitive to outliers while the median is not.
121+
122+
Notable patterns and events in the data
123+
- Strong rises in 2020–2021 (visible in both median and mean), consistent with the post‑pandemic / stamp‑duty / demand-driven market surge seen in that period.
124+
- Peaks in mean prices around mid‑2022 (mean values ~£440k), then a general softening through 2022–2023 and stabilisation around 2023–2024.
125+
- Some months show large volatility or unusual counts (e.g., June 2021 and June 2021 had very high transaction counts; March 2025 shows a high median but April–May 2025 show lower counts). Recent months (mid‑2025) have much lower transaction counts in the table — this often indicates incomplete reporting for the most recent months and means recent monthly figures should be treated cautiously.
126+
127+
Example datapoints (from the query)
128+
- 2020-10: median £255,000, mean £376,538, transactions 89,125
129+
- 2022-08: mean peak ~£441,209 (median ~£295,000)
130+
- 2025-03: median ~£314,750 (one of the highest medians)
131+
- 2025-08: median £294,500, mean £364,653, transactions 18,815 (low count — likely incomplete)
132+
133+
Caveats
134+
- These are transaction prices (Price Paid dataset) — actual house “values” may differ.
135+
- Mean is sensitive to composition and outliers. Changes in the types of properties sold (e.g., mix of flats vs detached houses, regional mix) will affect mean and median differently.
136+
- Recent months can be incomplete; months with unusually low transaction counts should be treated with caution.
137+
- This is a national aggregate — regional differences can be substantial.
138+
139+
If you want I can:
140+
- Produce a chart of median and mean over time.
141+
- Compare year-on-year or compute CAGR for a different start/end month.
142+
- Break the analysis down by region/county/town, property type (flat, terraced, semi, detached), or by price bands.
143+
- Show a table of top/bottom regions for price growth over the last 5 years.
144+
145+
Which follow-up would you like?
146+
147+
```
148+
149+
</VerticalStepper>

0 commit comments

Comments
 (0)