Python MCP
Give AI agents your Python ClickHouse datasets, not a SQL console
Define datasets in Python and serve them with FastAPI. The hypequery MCP bridge exposes exactly the endpoints an API key may call, so Claude and Cursor query governed measures while SQL, credentials, and the tenant stay in your backend.
Agent surface
Authorized endpoints only
SQL and credentials
Stay in Python
Works with
Claude, Cursor, MCP clients
A SQL tool hands the model your database
Generic ClickHouse MCP servers let the agent pick tables, joins, and result sizes. A prompt is not a permission system.
Agents invent their own revenue
When the agent writes its own query, its number disagrees with your dashboard. The definition has to be shared, not re-derived.
Python teams were left out
Most semantic-layer MCP servers expect a Node or YAML project. Your analytics already live in a Python service.
Client contract
Publish what agents may call
Install dataset endpoints with a client profile and add the client-contract route. The contract lists each endpoint’s fields, operators, and limits for the calling principal, and nothing else.
- Agents see only endpoints the API key’s principal is allowed to call
- The tenant comes from that principal on the Python side; the agent cannot choose it
- Fields, filters, and limits are validated by Python before any SQL runs
- If definitions change while the bridge runs, tools fail with
MCP_STALE_CONTRACTuntil restart
api.py
Dataset endpoints plus live discovery
The same endpoints your React app calls. No separate agent backend.
MCP bridge
Point the bridge at your Python API
The hypequery CLI runs the MCP server over stdio and turns each tool call into the same HTTP request a generated React client sends. Python needs no Node process; only the bridge does.
The contract URL must be HTTPS (or plain HTTP on localhost), and the API key is sent only to that origin. Redirects are refused.
Agents get list_datasets, get_dataset_schema, and query_dataset tools. They never write or receive SQL.
terminal
Start the bridge
Add the same command to Claude Desktop or Cursor’s MCP config.
Where teams usually get stuck
Questions teams ask
ClickHouse MCP server for Python
Use your existing Python service as the MCP backend instead of exposing ClickHouse directly.
Semantic layer for AI agents in Python
Agents query named measures and dimensions from your datasets, so their numbers match your product.
Multi-tenant MCP
Run one bridge per principal. Each one is scoped to that principal’s tenant by your Python auth.
Native Python MCP server?
Not today. The Node bridge reads your live contract; Python keeps ownership of SQL, auth, and tenancy.
Further reading
Go deeper where it actually helps
Next step
Connect one dataset to your first agent
Add a client contract route to your FastAPI app, then run the bridge with --self-test.
Open source, and it runs in your own backend. Want it hosted?