MCP tools to manage and query data sources in Docyrus.
Tool Overview
Discovery Tools
get_apps
— List tenant apps. Use before
create_data_source
to find the target
tenantAppId
.
get_data_source_list
— Search data sources by name/description or app ID.
get_data_source_list_with_fields
— Same as above but includes field names and types.
get_data_source_metadata
— Get full metadata (fields with IDs, types, slugs, enums, relations) for a data source.
Always call this before querying
to discover field slugs and relation targets.
get_enums_by_field_id
— Get enum options for select/status/tagSelect fields.
read_current_user
/
read_tenant_user
— Get user info.
Data Source CRUD
create_data_source
— Create a new data source (table). Default fields auto-created:
id
,
autonumber_id
,
name
,
record_owner
,
created_on
,
created_by
,
last_modified_by
,
last_modified_on
.
create_data_sources_batch
— Create multiple data sources with fields and enum options in a single atomic transaction. Supports cross-referencing data sources within the batch by slug for
field-relation
types. Max 20 data sources per batch.
update_data_source
— Update data source properties.
delete_data_source
— Delete a data source and all its data.
Field Management
create_fields
— Batch create fields. Set
relationDataSourceId
for
field-relation
types.
update_fields
— Batch update fields. Non-CUSTOM fields get customization records.
delete_fields
— Batch delete fields by ID.
Enum Management
create_enums
— Create enum options for select/tagSelect/status fields. Pass
fieldId
for field-specific enums or
enumSetId
for shared enum sets.
update_enums
— Update enum option name/slug/color/icon.
delete_enums
— Delete enum options.
OpenAPI Spec
regenerate_openapi_spec
— Regenerate and upload the tenant's OpenAPI spec after data source or field changes. Accepts optional
dataSourceSlugs
(string array) to limit scope; omit to include all data sources. Returns the
publicUrl
of the uploaded spec.
Call this after any
create_data_source
,
update_data_source
,
delete_data_source
,
create_fields
,
update_fields
, or
delete_fields
operation
to keep the spec in sync.
Query & Compute
query_data_source
— Read data with filtering, sorting, aggregation, formulas, pivots, child queries.
See
references/data-source-query-guide.md
for complete query syntax.
evaluate_jsonata
— Test JSONata expressions. Use for validating computed field formulas.
Custom Queries
get_custom_queries
— List non-archived custom queries for the tenant.
get_custom_query_by_id
— Read full custom query definition (
name
,
description
,
query
,
filters
).
create_custom_query
— Create a saved SQL template using Handlebars variables and optional filter definitions.
update_custom_query
— Update selected fields of an existing custom query (partial update).
delete_custom_query
— Soft-delete (archive) a custom query.
run_custom_query
— Execute a saved custom query with runtime filters, pagination offset, and optional simulate mode.
Common Workflows
Create a Data Source with Fields and Enums
Single data source approach:
Call
get_apps
to find the target app ID
Call
create_data_source
with title (plural), name (singular), slug (singular snake_case)
Call
create_fields
with all custom fields (default fields already exist)
For select/tagSelect/status fields, call
create_enums
with the field ID from step 3
Call
regenerate_openapi_spec
to update the OpenAPI spec
Batch approach (recommended for multiple data sources):
Call
get_apps
to find the target app ID (optional, defaults to "Default Customizations App")
Call
create_data_sources_batch
with an array of data source definitions (max 20)
Each data source includes
title
,
name
,
slug
, and
fields
array
Fields can include inline
enumOptions
for select/status/tagSelect fields
Use slug references for
relationDataSourceId
to reference other data sources in the same batch
All data sources, fields, and enums are created in a single atomic transaction
Call
regenerate_openapi_spec
to update the OpenAPI spec
Query Data
Call
get_data_source_metadata
to discover field slugs, types, and relations
Call
query_data_source
with appropriate columns, filters, and sorting
For advanced queries (aggregations, formulas, pivots, child queries), read
references/data-source-query-guide.md
Modify Existing Data Source
Call
get_data_source_metadata
to see current fields
Use
create_fields
/
update_fields
/
delete_fields
as needed
For enum changes, use
get_enums_by_field_id
first, then
create_enums
/
update_enums
/
delete_enums
Call
regenerate_openapi_spec
to update the OpenAPI spec
Manage a Custom Query Lifecycle
Call
get_custom_queries
to find an existing query or confirm naming
Call
create_custom_query
with
name
,
query
, and optional
description
/
filters
Call
get_custom_query_by_id
to verify the saved template and filter definitions
Use
update_custom_query
for targeted edits (rename, revise SQL template, update filter definitions)
Use
delete_custom_query
only when archival is explicitly requested
Run and Debug a Custom Query
Call
get_custom_query_by_id
first to inspect SQL template and available filter slugs
Build runtime
filters
with
rules[].field
values that match the query's filter slugs
Call
run_custom_query
with
simulate: true
for complex or untrusted queries to inspect plan output
Call
run_custom_query
with
simulate: false
(or omitted) to fetch real data
Use
offset
for pagination and expect a max of 50,000 rows per execution
Key Rules
Data Source Creation
title
is plural (e.g., "Sales Orders"),
name
is singular (e.g., "Sales Order"),
slug
is singular snake_case (e.g., "sales_order")
Use
defaultEditFormTarget: "tab"
for complex forms,
"side"
for simple ones
Enable
pluginActivityView
for CRM-type data sources (leads, contacts, deals)
Enable
pluginComments
for collaborative data sources
Enable
pluginFile
when users need to attach files to records
Enable
pluginDocyment
when users need rich text documents per record
Field Types
field-relation
requires
relationDataSourceId
— the ID (UUID) of the related data source, or in batch operations, the slug of another data source in the same batch
field-list
is a virtual field showing child records (one-to-many) — not stored in DB
field-select
/
field-tagSelect
/
field-status
need enum options:
In
create_fields
call
create_enums
after field creation
In
create_data_sources_batch
include inline
enumOptions
array in the field definition
field-formula
uses JSONata expressions — test with
evaluate_jsonata
first
field-inlineData
stores array of objects,
field-inlineForm
stores single nested object
Field
slug
must be snake_case matching
^[a-z][a-z0-9_]*$
Enum option
slug
must be snake_case matching
^[a-z][a-z0-9_]*$
(auto-generated from name if not provided)
Batch Operations
create_data_sources_batch
creates up to 20 data sources in a single transaction
Within a batch, reference other data sources using their
slug
for
relationDataSourceId
For external data sources (created outside the batch), use the UUID for
relationDataSourceId
Data source slugs must be unique within the batch (validation error otherwise)
Inline enum options are defined per-field using the
enumOptions
array
Each enum option in
enumOptions
can specify:
name
,
slug
,
color
,
icon
,
sortOrder
If a batch operation fails, all changes are rolled back (atomic transaction)
Use batch operations when creating related data sources to avoid multiple API calls and ensure consistency
Querying
Use
dataSourceId
(UUID) to identify which data source to query
columns
is a comma-separated string of field slugs, not an array
For aggregations, always use
id
field for
count
calculations
Relation expansion:
relation_field(sub_field1, sub_field2)
selects nested columns
Spread operator:
...relation_field(alias:sub_field)
flattens into root object
Filter on related fields:
rel_{{relation_slug}}/{{field_slug}}
Date filters have shortcut operators like
today
,
this_month
,
last_30_days
query_data_source Required Parameters
All parameters are required in the MCP tool schema (most accept
null
):
dataSourceId
string (required, non-null)
columns
string | null
filters
object | null
filterKeyword
string | null
orderBy
array | null
limit
number | null (default: 1000)
offset
number | null
fullCount
boolean | null
recordId
string | null (fetch single record by ID)
calculations
array | null
distinctColumns
array | null
formulas
array | null
childQueries
array | null
pivot
object | null
Custom Query Rules
Treat custom query
query
content as a Handlebars SQL template, not static SQL.
Use built-in context variables in templates when relevant:
TENANT_ID
,
TENANT_SCHEMA
,
USER_ID
,
USER_EMAIL
,
USER_FIRSTNAME
,
USER_LASTNAME
,
USER_FULLNAME
.
Use
{{filter FILTERS.}}
for optional runtime filtering. If no runtime value is provided, the helper resolves to
1=1
.
Keep
filters
definitions in
create_custom_query
/
update_custom_query
aligned with template usage:
template usage:
FILTERS.
runtime rule field:
filter definition slug:
Prefer
simulate: true
before running expensive queries to inspect
EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)
output.
Respect runtime limits on
run_custom_query
50,000 row cap, 15s timeout for normal execution, 30s timeout for simulate mode.
Use
delete_custom_query
as an archival action (soft delete), not permanent deletion.
For JSONB-backed simple data sources, access custom fields with
(table_alias."data"->>'field-uuid')::type
.
References
Data Source Query Guide
— Up-to-date reference for
query_data_source
including columns, filters, orderBy, pagination, calculations, formulas, pivots, child queries, and operator details.
Formula Design Guide (LLM)
— Up-to-date guide for designing formula payloads used in query requests.
Custom Query Guide
— Full lifecycle and execution reference for
get_custom_queries
,
get_custom_query_by_id
,
create_custom_query
,
update_custom_query
,
delete_custom_query
, and
run_custom_query
.