CS

Integrated MCP server

Home / Documentation / Agentic development /

Integrated MCP server

CS

The integrated MCP server in NET Genium

Every NET Genium instance includes an integrated MCP server (Model Context Protocol). Through it, an AI assistant or agent – Claude or its developer variant Claude Code, ChatGPT or its developer variant Codex, Microsoft Copilot Studio or any other tool supporting the MCP protocol – connects to the instance and gets everything it needs to work with a particular implementation: the data of its applications, a description of how the applications are built, and the knowledge of the NET Genium framework.

The server is part of the installation, there is nothing to install or start separately. The procedure for connecting the individual AI tools is provided in the separate guide Connecting an AI tool to the MCP server.

What the server can do

  • Working with data – reading and searching records and counting them, including the change history and attachments; with the write permission also creating, updating and deleting records.
  • Describing the implementation – which applications, edit forms, view pages and rights the instance contains and how they relate to one another. The assistant is given the AI model of the implementation directly by the server, always in its current form – nothing is downloaded or pasted by hand.
  • Building and changing applications – with the write permission, an agent can not only describe applications but also create them and keep changing them: application groups, applications, edit forms, view pages, controls, database queries and scripts.
  • User settings – the layout of the portlets on the home page, favourite items and the individual settings of view tables can be read for any user and, with the write permission, set for individual users as well as for whole user groups. Details are provided in the chapter User settings.
  • The knowledge of the framework – the assistant looks up and reads the relevant chapters of the NET Genium documentation, so it designs solutions according to the standards of the platform rather than to general habits. The knowledge base of the server is a selection from the documentation; the complete documentation is available in the AI assistant on the web.
  • Performance analysis – directly from the running instance, the assistant finds out which pages, queries and scripts take the longest, how large the tables they run over are, and where indexes are missing. The usage statistics are collected only when logging to the database is turned on in the NET Genium settings.

An assistant with access to the data can therefore answer questions that the description of the applications alone cannot – for example “how many records exist”, “find a specific document” or “how did a record change over time”.

Access to the server

The MCP server is intended for the administrators of the instance – only a user with administrator rights may use it, and if the Administrators with access to the MCP server list is filled in the NET Genium Settings, only the Administrator account and the administrators in the list. The license key of the instance must allow AI; this is not required in NET Genium Online. Every request signs in as a particular user and may do only what that user's permissions allow. The AI tool authenticates in one of two ways:

  • With a personal MCP token – administrators generate it themselves: they click the avatar on the right side of the header and choose MCP token in the personal menu. This way works with any instance and also suits an agent running unattended.
  • By signing in – in the Claude and ChatGPT applications it is enough to enter the address of the instance and sign in; no token is copied anywhere. This way is available only on instances running at the root of the web site over HTTPS, so always in NET Genium Online.

What the AI tool may do is determined by the permissions of the token, or by the consent given when signing in:

Permission What it gives access to Who can have it
Reading all data and the model via the MCP server reading data and the description of the implementation only a user with administrator rights
Writing all data and the model via the MCP server changing data and applications; the description of the implementation can be read with it as well only a user with administrator rights
Access via a custom API authenticating a user in a custom API of a customer solution; unrelated to the MCP server any user

The knowledge of the framework is given to every administrator regardless of the permissions ticked – it is the general documentation of the platform, not the content of the instance. Access to the server can be narrowed down to selected administrators only. A detailed description of this restriction is provided in the separate guide NET Genium settings.

Writing data through the MCP server

Writing through the MCP server does not run the scripts of the edit form – so neither the validations, recalculations, notifications nor status changes that follow saving a record take place. The record is created, but the process logic around it is not. Data whose saving such logic follows therefore belongs in the edit form, even on a development instance; other data can be written through the MCP server in production as well.

Moreover, a new record has no owner unless the agent states it explicitly among the values it writes. Encrypting values is likewise ensured only by the edit form: the value of a column with encryption turned on (the TextArea and RichTextBox controls) is written unencrypted through the MCP server, and reading returns the values as they are stored in the database.

By default, writing is not recorded in the change history and does not take part in synchronization – which suits bulk batches, typically sample data. For changes that have to stay traceable, writing with the change history therefore has to be requested explicitly. The same applies to deleting records: by default, a deletion is not recorded in the change history and does not take part in synchronization. When deleting with the change history, the records are deleted one by one, and the deletion is recorded in the history and sent for synchronization just like a deletion in the edit form; the scripts of the edit form do not run even then.

In NET Genium Online the server refuses writing while the instance is in read-only mode (credit used up or data allowance exceeded).

Details
  • Writing with the change history behaves like an edit in the edit form, only without scripts: the change is written to the history with an empty “action” column and is added to the synchronization queue, whose sending the server starts right after writing. A new record with a chosen ID goes through ID negotiation and may be renumbered.
  • A form with record history logging disabled does not write the history even when writing with the change history; the change is added to the synchronization queue.
  • The change history itself cannot be changed through the MCP server – the history tables are available for reading only.
  • A web presentation keeps the page tree and the list of attachments in memory and refreshes them according to the change history. A web page and a web attachment therefore have to be created and changed with the change history, otherwise the web does not see them.
  • In NET Genium Online, read-only mode applies to the “write_data”, “delete_data”, “create_attachment”, “write_model”, “rename” and “write_user_settings” tools alike.

User settings

The layout of the portlets on the home page, favourite items and the individual settings of view tables are otherwise changed by users only themselves in the NET Genium user interface. Through the MCP server, an agent reads them for any user and, with the write permission, sets them for individual users as well as for all members of selected user groups; typically, it prepares the home page layout for a new group or adds a portlet to all of its members.

  • Portlets and favourite items can be replaced entirely, or selected ones can just be added or removed. The refresh interval of the home page, the display of the image and the display of favourite items on the home page stay as each user has them, unless the agent changes them explicitly.
  • The settings of a view table correspond to what users can customize on it themselves – the displayed columns and detail columns, sorting, the number of records per page and the displayed parts of the table; for a view table in a portlet, tooltip columns instead of detail columns. Composite filters are not set through the MCP server, and a statistics view table is not supported yet. The settings of a view table cannot be saved for the anonymous user, just as in the user interface.
  • Users get only what they have rights to – a portlet, favourite item or column they have no right to is removed by the server after writing, and the response states it for the user concerned.
  • Details
    • The settings are read by the “get_user_settings” tool and written by “write_user_settings”; the “kind” parameter selects portlets (“portlets”), favourite items (“favorites”) or a view table (“datagrid”). One user is always read, given by ID or login name, and without it the owner of the token; the stored state is returned, not filtered by rights.
    • A view table is identified by the type of the control (“viewpagecontrol” or “formcontrol”) and its ID, a table in a portlet additionally by the portlet flag. The response also carries the columns available for selection and a flag telling whether the user has their own settings – if not, the returned columns are the default columns of the control.
    • Writing addresses users and groups in the form of rights (“U12”, “G3”); a group is expanded to its members and written to each of them separately. The replace, add and remove modes apply only to portlets and favourite items; for a view table, the properties sent are overwritten and the others stay.
    • With invalid input the server writes nothing: only DataGrid, Chart, News, Email and RichText or HTML marked as a portlet may be a portlet, a favourite item must point to an existing page, the columns of a view table must be among those offered, and sorting is possible only by a column the table can be sorted by.
    • The settings being written have the same shape as reading returns. Writing the settings of a statistics view table ends with an error.
    • Writing user settings is not recorded in the change history.

Server tools

This chapter is a reference for those who build an agent or are finding out why a tool behaves differently than expected. The agent receives the description of the tools from the server itself, so ordinary work with an AI assistant does not require knowing it.

Tool What it does Token permission
read_data, count_data, list_tables reading records, their count, the list of tables read
read_attachment the content of an attachment read
get_model, get_permissions, get_data_model the implementation model, user groups and rights groups, the data model read or write
get_model_history the change history of scripts, database queries and the code of HTML and JavaScript controls read or write
get_usage_statistics, get_record_counts, get_index_analysis usage statistics, record counts, index analysis read or write
get_user_settings portlets, favourite items and the view table settings of a user read or write
write_data, delete_data writing and deleting records write
create_attachment creating an attachment write
rename, write_model renaming and changes to the implementation model write
write_user_settings setting portlets, favourite items and view tables write
search_framework_docs, get_framework_doc, list_framework_docs the knowledge of the framework none – administrator rights are enough, together with being in the list “Administrators with access to the MCP server” if it is filled in

A tool the token has no permission for is not offered by the server; calling it ends with the error “Method not found”.

Reading data

The “read_data” tool reads the records of one table, “count_data” returns their count and “list_tables” the list of available tables. The tables of all edit forms are available – including the tables of users (“susers”), user groups (“susergroups”) and rights groups (“srightsgroups”) –, as well as their change history tables and the table of attachment metadata (“sfiles”).

Details
  • A change history table is addressed by the name of the table of the form with the “_history” suffix (for example “ng_invoice_history”). Every edit form has one, even a form with record history logging disabled – it then returns the rows written before logging was disabled and the rows of restoring a record from the history. The “list_tables” tool lists it for every form with the “(history)” suffix, and “count_data” can count its records as well.
  • Only the tables registered in the “stables” system table and the “sfiles” table are available. Other system tables (for example “scolumns”, “smcptokens” or “stables” itself) cannot be read, and reading ends with the error “Table not found”. In NET Genium Online, neither the statistics tables “sstatistics”, “sstatistics2” and “sstatistics3” nor the synchronization table “ssynchro” are available, including their history tables.
  • Columns whose name contains “password” or “md5” (regardless of letter case) are never returned by the server.
  • Encrypting values is ensured only by the edit form, so the server returns the values of columns with encryption turned on (the TextArea and RichTextBox controls) as they are stored in the database.
  • A token with only the write permission gets from “list_tables” just the tables it may write to – without “sfiles”, the history tables and the table of users.
  • The “read_data” response carries the names of the columns only with the returned rows; from an empty table, or with a condition no record satisfies, an empty array is returned. The list of the columns of a table is returned by “get_data_model”.
  • “count_data” returns the count as a 64-bit number. It runs “SELECT COUNT(*)”, so over a large table, especially with a condition on a column without an index, it can take a long time. The record counts of all tables at once are returned by “get_record_counts”.
  • The server returns date and time in the ISO 8601 format without a time zone designator (for example “2026-06-18T14:30:00.0000000”), as a time in the time zone of the instance set in the NET Genium settings. The user's own time zone is not applied through the MCP server, neither when reading nor when writing. The time zone of the instance and the time of the instance at the moment of connecting are given to the agent by the server in the instructions on connecting, if the token has the permission to read or write.

Conditions

The “conditions” parameter of the “read_data”, “count_data” and “delete_data” tools is the part of a query after the WHERE keyword, without the keyword itself – for example “ng_status = 'Active' AND ng_amount > 1000”. Literals are written the same way regardless of whether the instance runs on MS SQL Server or on Firebird:

  • text in single quotes, with an apostrophe inside doubled (“'O''Brien'”); the “N” prefix is not written – on MS SQL Server the server adds it itself and on Firebird it would be invalid,
  • a date as a token between “#” characters outside quotes – “#2026-06-18#” or “#2026-06-18T14:30:00#”; the server converts it to a date literal of the database engine,
  • a number without quotes.
  • Details
    • The condition must be a single expression: outside string literals it must not contain a semicolon, a comment (“--”, “/* */”), an unterminated literal or unbalanced parentheses, and it must not contain a subquery (SELECT) or a column whose name contains “password” or “md5”. The server refuses such a condition with the error “Invalid conditions: ...”. A filter by a related record is therefore composed of two calls – first the IDs of the referenced records are read and then they are passed as a list (“ng_idcompany IN (12, 15, 18)”).
    • A date written as a text literal (“'2026-06-18'”) would fail on one of the database engines, because their syntax of date literals differs. A token with the “Z” designator or with an offset from UTC is refused by the server.

Writing data

The “write_data” tool creates and updates the records of one table, “delete_data” deletes them by ID or by a condition. The values are sent according to the data type of the column returned by “get_data_model”:

Data type Value
int an integer; for a foreign key the ID of the referenced record (or the value of the column chosen as “The value saved in the database”), for the File and Image controls the ID of the attachment
float a decimal number
datetime a string in the ISO 8601 format without a time zone designator – “2026-06-18T00:00:00.0000000” for a date without time, “2026-06-18T14:30:00.0000000” for a date with time
nvarchar text; for select controls one of the values defined in the model, see below

The value of a select control must match the values the control has in the implementation model:

  • ComboBox, ListBox and Radio – one item from the values of the control, copied verbatim including the “#en:” language variants, spaces and units,
  • MultiListBox – one or more items separated by a tab; the separator set on the control determines only the display,
  • CheckBox – checked is the exact text of the default value of the control, unchecked an empty string,
  • a control with values from a database query – one of the values that exist in the data.
  • Details
    • The server saves an invalid value of a select control without an error. Select controls other than CheckBox show it in the form as an extra option, and the filter of a view table offers it as a further value. A CheckBox with a text other than its default value is shown unchecked in the form, the “Yes” filter nevertheless counts it among the checked ones, and the next saving of the form overwrites the value with an empty string – except for a read-only control with changing the value by JavaScript disabled and a control with the “Current value in the database” default value that is read-only or fills the value in before every save.
    • A date is written as a time in the time zone of the instance; a value with the “Z” designator or with an offset from UTC is refused by the server. Neither a localized format (“18.06.2026”) nor a literal of the database engine is used – the server takes care of the conversion to the database syntax.
    • Whether a field is required is only a validation of the edit form. The database column always accepts an empty value, and writing through the MCP server does not check required fields.
    • The default values of controls are not applied. Unfilled text fields of a new record get an empty string, just as in the form; the “pid” and “pform” columns are filled in only for nested records.
    • The ID of a record may be 64-bit as well, so writing and deleting also serve a form with a primary key of the Long type.
    • The server refuses writing to the table of users (“susers”) with the error “Table not available for writing”; the history tables and “sfiles” are not served for writing at all. User groups and rights groups can be created, renamed and deleted, but the membership of users in user groups and the assignment of user groups to rights groups cannot – they are stored in link tables that are not available through the MCP server, and are changed in NET Genium.
    • Deleting a user group cleans up its links just like the edit form – the membership of users, the assignment to rights groups, the allowed IP addresses and the public external functions of the group. Deleting a rights group cleans up the assigned user groups and clears the “Rights group” field of the users who had it; this clearing is written to the change history of users and to the synchronization queue even when deleting without the change history.
    • A record with the “system” flag – the built-in user groups “Administrators”, “Users” and “External Users” and other records protected by the system – cannot be deleted: deleting by ID ends with an error, deleting by a condition skips it. It can be renamed; the “system” column itself, however, cannot be written (“Column 'system' cannot be written”), so the protection cannot be turned off. The active layout in the “slayout” table is protected in the same way. Writing to it through the MCP server, however, does none of what saving in the “Layout” form does – the styles of the portal are not regenerated, the active layout flag is not cleared on the other layouts and the text size is not limited to the range 10–16 –, so the layout is changed in the form.
    • Deleting with the change history deletes the records one by one, each in its own transaction.

Attachments

The value of the column of a File or Image control is the ID of a record in the “sfiles” table, whose metadata are read by “read_data”. The content of an attachment is returned by “read_attachment” – an image in the png, jpg, gif or webp format as an image, SVG as text, text formats as JSON with metadata and the text (the “encoding” property with the value “text”), and other files as an embedded resource of the MCP protocol with the content in Base64 encoding. The “create_attachment” tool creates a new attachment and returns its ID; the content is carried by exactly one of the parameters “content” (text, saved in UTF-8 encoding with BOM) and “content_base64” (binary content). The returned ID is then written to the column with the “write_data” tool.

  • A saved attachment cannot be changed – replacing an attachment means creating a new one and overwriting the ID in the record.
  • Every attachment ID belongs to a single record and column. Records with the same ID would share one file, so deleting it or modifying it in place (the “REDUCEATTACHMENT” server function) would affect all of them.
  • An attachment whose ID is not written to any record stays in the instance without a reference.
  • Details
    • “read_attachment” refuses an attachment larger than 10 MB. It recognizes the encoding of text by the BOM; a file without a BOM is read with the code page of the server, so older files in the Windows-1250 encoding are read correctly.
    • An image inserted into the text of a RichText control that the framework has moved to the database is not returned – its file is no longer on disk and the tool ends with the error “Attachment file not found on the server”.

Implementation model

The implementation model of the instance is available through the MCP server for reading only, and any of the permissions to read and to write is enough for it – the model can thus be read before writing changes as well. The tools return the same information as the files of the AI model of the implementation downloaded by the “ai-model” utility:

Tool What it returns
get_model the building blocks in JSON: without parameters an overview of application groups, applications and edit forms; with the “app” parameter (name or ID) the inventory of one application; with the “form” parameter (name, identifier or ID) a single edit form with its controls and buttons, without the view pages and categories of the application, searched for in the whole instance. The “depth” parameter with the value “structure” leaves out the bodies of scripts and the definitions of queries. The model of the whole instance is not returned at once.
get_model_history the change history of one script, of one database query or of the code of one HTML or JavaScript control – the saved versions from the newest, each with its date, the user who saved it and the complete text after the save; a script is returned as a text listing of its steps including the definitions of their queries, a query as a text listing of its definition. The script of an edit form event is addressed by the “form” (form ID) and “event” (“onBeforeOpen”, “onAfterOpen”, “onBeforeSave”, “onAfterSave”, “onBeforeDelete”, “onAfterDelete”) parameters, an edit form control by the “formcontrol” parameter, a view page control by the “viewpagecontrol” parameter and a database query by the “query” parameter (the query ID from “get_model”); an HTML or JavaScript control returns the history of its code, other controls (typically Button) the history of their script.
get_permissions user groups and rights groups
get_data_model the data model as CREATE TABLE statements – tables, columns, data types and required fields (the “/*R*/” mark)
get_usage_statistics usage statistics for 30 days – the number of runs and the total, average and maximum time of edit forms, view pages, database queries, external functions and scripts
get_record_counts the record counts of all tables, sorted from the largest table
get_index_analysis the index analysis – for the “pid” and “pform” columns and every database control, whether the index is turned on and the numbers of uses in joins, conditions and filters; a column used in a join without an index carries the “missing_index” flag, and the “missing_only” parameter narrows the output to just such columns
Details
  • The model returned with the “app” parameter is the same JSON as the downloaded model, only narrowed to one application – it is produced the same way.
  • The usage statistics contain data only when logging to the database is turned on in the NET Genium settings; otherwise they list forms and pages with zero values. The period ends at the moment of the call and starts 30 days before last midnight.
  • “get_record_counts” runs “SELECT COUNT(*)” over all tables, so over a large database it takes a long time.
  • The index analysis corresponds to the “Indexes” report; it has no counterpart among the files of the AI model of the implementation.
  • The change history of scripts, database queries and the code of HTML and JavaScript controls has no counterpart among the files of the AI model of the implementation either. A version is recorded on every save of a script, query or code with a change, in NET Genium as well as by the “write_model” tool; an empty text means that the script or the code was removed. The answer carries the total number of versions (“total”) and a flag telling whether older ones follow (“more”). At most 50 versions are returned at once (10 by default, the “limit” parameter); older ones are read with the “before” parameter set to the ID of the oldest returned version.
  • The definition of the query of a script step is part of the version of the script. Saving the query in the query designer, however, does not record a new version of the script – it is recorded only by the next action in the script designer (saving, running, adding, moving or deleting a step). Changing the query of a step with the “write_model” tool records a new version of the script at once.

Renaming

The “rename” tool changes the name of one entity of the implementation model. Its parameters are “type”, “id” and “name”, and the response returns “type”, “id”, the original name (“old_name”) and the new name (“name”). The values of “type” are “appgroup” (application group), “app” (application), “category” (category), “form” (edit form), “viewpage” (view page), “formcontrol” (control of an edit form) and “viewpagecontrol” (control of a view page).

Renaming changes only the name, never the identifier or the data – neither the database table nor the column is renamed, so queries, scripts and code keep working.

Details
  • Follow-up renaming takes place just as in the configuration dialog: the new name of a view page control is propagated to the titles of portlets, the new name of a view page to the names of the favourite items of all users (for a page in a category with a different name in the form “Category / Page”). A view page of the “Open an edit form” or “New email” type without a return page set gets itself set as the return page, just as after saving in the dialog.
  • The same restrictions apply as in admin mode: an entity of an application group restricted to the option User “Administrator” and following administrators or a system object of the “Settings” application is not renamed by a token owner who would not be allowed to change it in the configuration dialog – they get the error “Changing the ... with ID ... is not allowed.”
  • The server refuses a non-existent ID with the error “Record not found”.
  • A merged application group and application (a group with a single application of the same name) are renamed together.
  • Controls without a name – Title, Tab and Space, in an edit form also RichText and History, on a view page Email – cannot be renamed. The label of the Title, Tab and RichText controls is their text, which is changed with the “write_model” tool.
  • The names the model gives for references to columns (displayed columns of tables, keys ending in “ColumnName”) are derived from the referenced control; they have no record of their own and are brought into line by renaming the control itself.
  • After renaming, the server discards the corresponding cache, so the change takes effect immediately. Other processes over the same database (another application pool or server) see it immediately only if several intranet addresses are filled in in the NET Genium settings, otherwise at the latest after their restart.
  • A single “write_model” call carries a whole batch of renames (items changing the “name” property), whereas “rename” always carries just one entity. The identifier and the data stay untouched and the cache is discarded as well.

Writing changes to the model

The “write_model” tool creates, changes and deletes application groups, applications, categories, edit forms, view pages, controls, database queries, scripts, user groups and rights groups. It accepts three arrays of items – “insert”, “update” and “delete” –, which are processed in this order. An item carries the kind of the entity (“key”), its ID and the changed properties (“changes”) under the same names as in the implementation model; a newly created entity has a temporary negative ID, which other items can refer to and which the server replaces with the real one when writing.

{
  "id": -1000,
  "key": "editFormControls",
  "formId": 11,
  "name": "Price",
  "context": "Invoice",
  "changes": {
    "type": "TextBox",
    "dbName": "ng_price",
    "name": "Price"
  }
}
Group Values of “key”
Rights userGroups, rightsGroups
Portal structure appGroups, apps, categories, forms, viewPages
Controls editFormControls, viewPageControls, actionButtons
Scripts editFormControlScript, viewPageControlScript, onBeforeOpen, onAfterOpen, onBeforeSave, onAfterSave, onBeforeDelete, onAfterDelete
Database queries of controls dataSource, valuesQuery, defaultValueQuery, helpQuery, inQuery, resourceQuery, availabilitiesDataSource, picker

A successful write returns the “written” flag, a map of the temporary IDs to the real ones (“ids”) and, where applicable, the “skipped” array with the items the server deliberately did not write – each with the properties “key”, “id”, “name”, “context” and the reason “reason”; the other items of the write are written. Writing through “write_model” is the same path by which the “ai-model” utility uploads the model; they differ only in identity – “write_model” writes as the owner of the token, the utility as the “Administrator” user (ID 1), so it may also change application groups restricted to the option User “Administrator” and following administrators and the system objects of the “Settings” application. The other checks of writing, including the ban on deleting system objects, apply to both paths.

Details
  • Shape of an item. The server accepts the “changes” property as a plain object or as an array of “key” and “value” pairs (an older shape kept for backward compatibility). The “name” and “context” properties of an item are only descriptive – the server returns them in error messages.
  • Parent of a new control. A newly created control of an edit form carries “formId” at the level of the item (not in “changes”), a control of a view page “viewPageId”; without them writing ends with the error “Required key 'formId' was not found”. For an existing control the parent is taken from the model and “formId” is ignored, so it cannot be used to move the control.
  • Location. The “location” property in “changes” is always an object: for an application “{"appGroup": 3}”, for a category and a form “{"appGroup": 3, "app": 2}”, for a view page “{"app": 2}”, optionally with “category”. The value inside may be a number or an object “{"id": 3, "name": "..."}” as given by the model. A location that is not an object or lacks “appGroup” (for an application) or “app” (for the others) ends with an error. A location of a view page without “category” removes the page from its category; the category must exist and belong to the application given in the same location.
  • Temporary IDs. A temporary ID may stand in any reference (“formId”, “viewPageId”, “location”, references of queries, in rights as “G-1000”), but only if the referenced entity is created earlier in the same write – the map of temporary IDs is shared by all three arrays. The server refuses a reference to an entity that has not been created yet with an error about an unresolved temporary ID only for IDs of -1000 and lower; a higher negative number is written literally. References inside JavaScript (“BT-<id>”, “jsUserInGroup(<id>)”) are substituted only after the whole write has been processed, so they may point to an entity created later as well; if the write ends with an error, only the references to entities created up to that point are substituted.
  • Order of creation. The default order of the items of the “insert” array is userGroups, rightsGroups, appGroups, apps, categories, forms, editFormControls, actionButtons, editFormControlScript, viewPages, viewPageControls, viewPageControlScript. The server does not enforce the order – the only thing that matters is whether the referenced entity already exists at the moment the item is processed; a form button that opens a newly created view page therefore belongs after it.
  • Scripts. For the script keys, the ID of the item is the ID of the owner of the script – the control for “editFormControlScript” and “viewPageControlScript”, the form for the form events – and “changes” is an array of steps. Steps are merged into the script by their ID, so only the changed ones are sent. A step is deleted by an item of the “delete” array with the key of the same script, the ID of the owner and “changes” in the form “[{ "id": <step ID> }]”; there is no “scriptStep” key. A step with a positive ID that does not belong to the script of the owner ends with the error “Script step with ID ... was not found in this script.”, a non-existent owner with the error “Referenced ... with ID ... was not found.” The type of an existing step cannot be changed – the step is deleted and created again; when editing without changing the type, the type may be left out. A side of a step that is sent (the target, the source, the left or right side of a condition, for an e-mail the sender, recipient, copy and subject) overwrites its whole group of properties – whatever of it is not sent is cleared. Unlike the script designer, deleting a step does not renumber the lines of the other steps or the targets of jumps, and for a loop it does not delete the paired “Next” step.
  • Nested objects. A picker can be sent nested in the control (“picker”) or as a separate item with the “picker” key and the ID of the control. A picker being created must carry a query (“pickerQuery”), because the assignments and columns of the picker belong to it; without a query only a change of a picker the control already has goes through. Scripts and form buttons cannot be sent nested in a control – they are written only as separate items. A picker is removed by an item of the “delete” array with the “picker” key and the ID of the control, or by the value “null” of the “picker” property (a non-existent control ends with an error, a control without a picker goes through without writing anything); the column assignments are deleted, the picker settings on the control stay and the query of the picker stays in the database without a link to the control, just as after removing the picker in NET Genium.
  • Unknown properties. A property that writing cannot process ends with an error – in the “changes” of a control with the message “Unknown key '...'”, in a nested object (query, condition, join, column, chart series, script step and its parts, displayed columns, picker assignments) with a message listing the properties the object knows. Only derived names, “identifier”, “system” and “type” are tolerated. Directly in the “changes” of an item, every property ending in “Name” that is not a real property (“dbName”, “shortName”, “templateName”, “pickerTemplateName”) is silently ignored, so a typo in it raises no error. A real property on a control type that does not have it ends with the error “not supported by this control type”; “validation” is tolerated only for an existing control whose type changes in the same write. For a script step, the properties are checked according to its type.
  • Enumeration values. An enumeration property accepts exactly the values that reading the model gives; any other is refused with the error “Invalid value '...' in key '...'. Allowed values: '...'.” listing the allowed values. The exception is the function of a data source column (“function”), which writing verifies against the offer of the control type. Letter case matters only when the value could not be matched otherwise (“LEFT” is written as “left”). An empty value is accepted only by the properties for which the model leaves it out (the operator, “andOr”, the type of a join, the priority of an e-mail, “function” and “alignment” of a query column, “sortDirection2”), and further by “sortDirection” (ascending), “filterRecordsPerPage” (“default”), “nestedRecords” (“overwriteRows”) and “displayInForm”, “displayInTable” and “displayInDetails” (“link”), for which it means the default value given in parentheses. The allowed values of the search type (“searchType”) depend on the control – for a text field on its data type and default value; for the file and image controls the meaning of the values “enabled” and “disabled” is reversed.
  • Rights. A newly created control without the “rights” property gets the “Users” user group; an empty array of rights means a control visible only to an administrator, and the server refuses the value “[null]” with the error “Invalid value null in key 'rights'”. A single item of an application, category and view page may carry only one of the “rights”, “replaceRights”, “addRights” and “deleteRights” properties; for a form, “rights” (co-owners) can be combined with one of the others. The “assignedUserGroups” property of a rights group replaces the whole set of assigned user groups; an item of it may be an ID or an object “{ id, name }”, and writing refuses a non-existent group.
  • Restrictions of admin mode. An application group restricted to the option User “Administrator” and following administrators and the system objects of the “Settings” application may be changed by the owner of the token only if they may do so in the configuration dialogs as well. An item of a control, view page control, script, picker or query whose form or page the owner may not change ends with the error “Changing the form with ID ... is not allowed.” (or “view page”, “query”). An existing query may be changed or attached only by someone who may change all its current owners; for groups, applications, categories, forms, pages and buttons such an item is not written and the response lists it among those not written. The target of creating or moving is checked as well – an application group or application that is not allowed ends with the error “Changing the application group with ID ... is not allowed.” (or “application”), a non-existent one with the error “... was not found.” A system application group, application, category, form or view page cannot be deleted (“System ... cannot be deleted.”).
  • Non-existent entities. An item of the “update” array with a positive ID that does not exist ends with the error “Record with ID ... was not found.” (for buttons and form events “Referenced form with ID ... was not found.”, for edit form controls and a separate picker “Referenced column with ID ... was not found.”, for view page controls “Referenced viewfield with ID ... was not found.”) – it does not create a new entity. An item of the “delete” array for an application group, application, category, form, view page, control, view page control or separate picker whose entity does not exist ends the same way; an item of a button is skipped without an error.
  • What writing does not do. “write_model” does not delete a user group or a rights group – an item of the “delete” array with the “userGroups” or “rightsGroups” key ends with an error; the group is deleted in NET Genium or with the “delete_data” tool. A query is not deleted on its own – such an item ends up among those not written; it is detached from the control with the value “null” (for example “"dataSource": null”). It does not clear a column of the Calendar, Planner, TimeTable, Kanban and Map controls – the value 0 means “not specified” and the stored column stays. The range of script variables is not specified; it only shortens the offers of the script designer, which extends it according to the highest variable used when the script is opened.
  • Merged application group and application. If an application group contains exactly one application of the same name (judged in the language of the owner of the token), a change of the name, icons or rights of one of them is written to the other as well, and deleting the application deletes the group too, unless it is a system one. Only a value that the write actually changed is carried over. Creating a group does not create an application – a merged pair has to be created with two items.
  • Error during writing. Writing stops at the first item that fails. The error carries the number of items processed before it, the map of temporary IDs and the list of items the server deliberately did not write up to then. The item on which writing failed may be written partially (a nested query, earlier steps of a script, a control created before an error in its picker) – whatever came into existence from it is in the map of temporary IDs as well.
  • Side effects. Changing the identifier (“dbName”) of an existing form or database control renames the physical table or column. A button with the “openForm”, “openViewPage” or “printTemplate” action runs the script on a click only with “runScript” turned on (the “Run script” setting); the “RunScript.exe” program and the “SCHEDULESCRIPT” server function run it even without it. With the “script” action the script always runs, and the model gives “runScript” with the value “true” for it regardless of the stored value. When a query is replaced with a newly created query over the same form, the server takes over from the old query every list of displayed columns that the new query does not have, even one sent empty; with a query over a different form, the control gets the lists only if they are sent with it.
  • Personal table settings. Writing a DataGrid, History, Tree or Email control overwrites the personal settings of that table for the one who writes, just like saving the control in the configuration dialog – for DataGrid and Tree on a view page and in an edit form alike, and on every change of the control, even one unrelated to the table. For DataGrid, History and Tree, their selection of columns (for Tree the detail columns) is replaced with the columns of the control and their filter values in the columns are cleared; for DataGrid and History, in addition, the display of the table (totals, top navigation bar, filters, details, tooltips, for DataGrid also the number of records per page) is aligned with the control and their portlet settings over this table are deleted. For the Email control, only the selection of the time period and the tooltip are aligned. For DataGrid and History with user customization disabled, all other users have their selection of columns, table settings and portlet settings deleted (the current composite filter stays); for DataGrid, in addition, the composite filter templates of the other users are deleted, except for the “Administrator” user (ID 1) if that user has their own template over the table. The one who writes is the owner of the token for “write_model” and the “Administrator” user for an upload by the “ai-model” utility.
  • Images in the RichText control. The model gives images inserted into the text of a RichText control as the placeholder text “[[Image: removed (base64)]]” (in Czech “[[Obrázek: odstraněn (base64)]]”). Writing replaces them with the images from the stored value in the order in which they stand in the text, so the text around them can be changed. If the number of placeholder texts does not match the number of images in the stored value, writing ends with an error; for a newly created control, where there is nothing to restore the images from, the server refuses the placeholder text.

Security

  • Every request signs in as a particular user – the owner of the token, or the one who allowed the AI tool by signing in – and is subject to the allowed IP addresses and to licences just like a regular login.
  • Permissions are verified on every request – losing administrator rights ends the access immediately.
  • Changes to applications are subject to the same restrictions as the configuration dialogs of the admin mode – what an administrator may not change in a dialog cannot be changed through the MCP server either.
  • A token is valid for 90 days and can be deleted at any time; an application connected by signing in can be disconnected at any time.
  • The server is protected against token guessing.
  • The write permission allows any data of the instance to be changed, not just a selected table or the user's own records – it should therefore be turned on deliberately and only for those who need it.

Typical use cases

  • natural-language questions about data – “find projects without a responsible person”, “how many invoices are added each month”,
  • consistency checks and summary analyses of data across applications,
  • finding out when and how a record changed,
  • orientation in an implementation – how the application is built and which tables and columns belong to it,
  • building new applications and changing existing ones,
  • preparing the home page, favourite items and view tables for whole groups of users,
  • performance analysis – which pages, queries and scripts take the longest and how large the tables they run over are,
  • checking how a particular thing is properly done in the NET Genium framework before designing anything.

This server is naturally followed by agentic development – working with an AI agent that knows both the framework and the particular implementation and can work in it purposefully.