The MCP Server
hd_mcp puts an HD instance in front of an AI assistant. It speaks the Model
Context Protocol over Server-Sent Events, so any agent framework that can call
MCP tools can query the instance without being taught what an HD query is — and
without being handed a raw database connection. The service runs outside the
storage cluster, reaches it through the HD Proxy like every other door, and
evaluates the SQL part locally with the SDK's engine. The rules it shares with
the other doors are on the querying page.
The tools
Two tools, and the split between them is the point:
execute_hd_query fetches live records and answers a question about them.
| Argument | |
|---|---|
proxy_name |
which Proxy, by the name given in the proxy list |
sql_query |
the SQL to evaluate over the records that arrive, in DuckDB's dialect |
start_time, end_time |
the window, in Unix seconds. The end is clamped to now |
query_qos |
priority weight 1–255 |
The time window is what keeps an assistant's question affordable. With one, the tool names exactly the batches of that window; without one it reads the whole dataset, and the tool acknowledges that full scan on the agent's behalf, because an agent has no way to be asked. Prompt the assistant to always give the window. The interactive alternative is the stream endpoint on the second port, where an application such as Data Explore relays the person's answer to the full-scan question instead.
execute_raw_sql_query runs SQL over the records the previous call already
fetched, with no round trip to the storage cluster. It exists so an assistant
can ask several questions of one fetch — group it another way, filter it
further — without paying for the transfer again. It takes proxy_name and
sql_query.
An address literal in either tool's SQL — '10.0.0.1' against a column the
schema types as an address, or against an integer column wide enough to hold
one — becomes the integer before the engine sees it, and an address column in
the result is rendered as an address.
Running it
# proxies.yaml
proxies:
prod:
url: https://proxy.hd.internal:6986
| Setting | Default | |
|---|---|---|
PROXY_CONFIG_PATH |
proxies.yaml |
the Proxy list, watched for changes; each Proxy's schema is fetched from its /v1/hd/schema |
MCP_LISTEN_PORT |
8082 | the MCP endpoint, over Server-Sent Events |
MCP_STREAM_PORT |
8083 | the interactive query stream Data Explore uses |
FERMIHDI_DATA_RETURN_PORT |
6987 | where the Storage Nodes stream results |
FERMIHDI_DATA_PLANE_SUBNET / FERMIHDI_DATA_RETURN_HOST |
10.150.0.0/24 / discovery |
the address advertised to the Storage Nodes — wrong, and every query waits for results that went elsewhere |
An assistant's client configuration points at the MCP endpoint, for example
http://hd-mcp:8082. The service has no authentication of its own: place it
behind the authenticating front door, and give the assistant the identity the
Proxy's policy should evaluate — the front doors page says how
identity reaches the Proxy from here. It is an engine role for placement — it carries
the SDK — and the Administrator's Guide sizes
it.
Data Explore
Data Explore is the browser front end over this service: a visual query
builder, charts, and the interactive full-scan prompt. It reaches the MCP
server on both ports (FERMIHDI_MCP_ENDPOINT, FERMIHDI_MCP_STREAM_ENDPOINT),
serves on port 4321, and relies entirely on the identity headers the front door
sets, so it too belongs behind it.