ObjectStackNatural Language Queries
How agents query live data through the open MCP data tools (query_records, get_record, aggregate_records) under RLS
Natural Language Queries
Part of the AI module — how natural-language questions become ObjectQL queries at runtime.
Natural-language querying is open. Point your own AI — Claude, Cursor, any
MCP client, or a local model — at your app through @objectstack/mcp, and it
turns questions into ObjectQL against your objects, governed by the same
row-level security as the REST API. The data tools and the ObjectQL engine that
back this are part of the open framework — no ObjectOS runtime and no
cloud Studio are required.
Your AI queries your data through the open MCP data tools — query_records
(filter, field selection, sort, pagination), get_record, and aggregate_records
(group-by count/sum/avg/min/max/count_distinct, with optional date bucketing),
plus the discovery tools list_objects and describe_object — which the model
calls with structured arguments. These run as ordinary ObjectQL queries over
your objects (ObjectStack uses ObjectQL, not SOQL), and they execute under the
caller's ExecutionContext, so row-level security applies exactly as it does
for the REST API.
Server-side aggregation is open too. aggregate_records runs a single-object
GROUP BY (count/sum/avg/min/max/count_distinct, optional date bucketing and
filter) through the same ObjectQL engine read path — so totals and breakdowns
come back in one call under row-level and field-level security, instead of
the agent paging every visible row and summing client-side. It does not join
across objects or read datasets/cubes: the cross-object, dataset-level
aggregate_data roll-up tool remains part of the cloud in-product chat runtime
(below).
The open MCP server plugin exposes these tools automatically — it bridges the
metadata and data engine to any connected MCP client, served per-request at
/api/v1/mcp (default-on):
import { LiteKernel } from '@objectstack/core';
import { MCPServerPlugin } from '@objectstack/mcp';
const kernel = new LiteKernel();
kernel.use(new MCPServerPlugin({ autoStart: true }));
await kernel.bootstrap();Point any MCP client at the server and ask questions in natural language: the
model discovers list_objects / describe_object / query_records /
get_record / aggregate_records and calls them under RLS as the authenticated caller.
There is no separate natural-language-to-query metadata type to author — the
model is prompted with the available objects and translates the user's question
into query_records calls at runtime.
ObjectOS — bundled in-product chat. ObjectOS ships an in-UI
AI runtime — the ask data-query assistant
and the /api/v1/ai/* chat endpoints — that registers these same data tools,
plus the dataset-level (cross-object) aggregate_data roll-up tool, into its own chat loop. That
runtime is not part of the open framework and is documented separately in the
ObjectOS docs; this page covers the open path
only. On the open-source framework, use
@objectstack/mcp above to get the same natural-language querying with your
own AI.