Integrated MCP server

The integrated MCP server in NET Genium

Every NET Genium instance includes an integrated MCP server (Model Context Protocol) that gives AI assistants and agents everything they need to work with a particular implementation – the data of its applications, the model of the implementation, and the knowledge of the NET Genium framework. The data can be read, analysed and, in dedicated environments, modified as well, and so can the model of the implementation with the write permission; the knowledge of the framework is always read only.

Typical clients are Claude or its developer variant Claude Code, ChatGPT or its developer variant Codex, and Microsoft Copilot Studio, but any tool supporting the MCP protocol can connect. The client connects to the “api.aspx” page in the root of the NET Genium instance and authenticates either with a personal MCP token or – on instances running at the root of the web site over HTTPS – by the sign-in of the user. The setup procedure is described in the separate text Connecting an AI tool to the MCP server.

What the server can do

The tools of the server cover six areas:

• Reading data – listing available tables, reading records with optional filtering, and counting records. Change history tables and attachment metadata can be read as well.
• Writing data – creating, updating, and deleting records. When creating or updating a record you can choose whether the change is also written into the change history and takes part in synchronization, that is, whether it behaves like a change made in the user interface – see below. Writing, however, does not run the save scripts of the edit form, so it only fits where no process logic is attached to saving a record – see below.
• The model of the implementation – the overview of application groups, applications and edit forms, the detailed inventory of a single application, user groups and rights groups, and the data model in the form of CREATE TABLE statements. It is the AI model of the implementation, which the assistant is given directly by the server and always in its current form – nothing is downloaded or pasted by hand.
• Writing the model – creating, changing and deleting application groups, applications, categories, edit forms, view pages, controls, database queries and scripts. An agent connected to the instance can therefore not only describe an application but build it and keep changing it. Renaming a building block is a separate operation, which changes only the displayed name, never the identifier.
• The knowledge of the framework – a list of the documentation pages of NET Genium and their full text. The assistant therefore designs forms, queries and scripts according to the current 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.
• The materials for performance analysis – the usage statistics of the last 30 days (the execution count and the total, average and maximum time of edit forms, view pages, database queries, external functions and scripts), the number of records of every database table, and the index analysis that reveals the columns used in joins without an index. The assistant therefore analyses the performance of the instance directly from the running system, without downloading any reports. The usage statistics are collected only when logging to the database is turned on in the settings of NET Genium.

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

Personal MCP token

Access to the server is controlled by a personal MCP token of a specific user. Each user generates their own token in the “Change password” dialog (the “Change password” link in the “My settings” section of the navigation area) on the “MCP token” tab:

• the token is displayed in readable form only once, when generated – only its fingerprint (hash) is stored on the server,
• the token is valid for 90 days; once it expires, a new one can be generated,
• each user has at most one token and can delete it at any time.

The token permissions determine which tools are available to the client:

Reading all data and the model via the MCP server	reading tools and reading the implementation model	only users with administrator rights
Writing all data and the model via the MCP server	writing tools, writing the implementation model and renaming building blocks	only users with administrator rights
Access via a custom API	authentication against a custom API of a customer project	any user

The implementation model belongs to both permissions – reading the model, the data model, the usage statistics, the record counts and the index analysis is unlocked by the reading permission, writing the model and renaming controls by the writing one. The model describes the applications of a particular customer, so a token you deliberately leave without the reading permission does not reach it.

The knowledge of the framework is not turned on by a checkbox – it is given to every token whose owner has administrator rights, regardless of the permissions for reading and writing. It is the general documentation of the platform, not the content of the instance, so no permission is being extended. A token with neither box ticked therefore gets nothing but that.

The built-in Administrator account additionally manages the tokens of other users – it can delete them and toggle their permissions.

Access to the server can be restricted to selected administrators – the “Permissions” tab in the NET Genium settings lists the administrators who are allowed to work with the MCP server. As long as the list is empty, the rules described above apply and the server can be used by any administrator. As soon as the list contains at least one record, only the built-in Administrator account and the listed users get through – for everyone else the request is refused, the knowledge of the framework included, and the reading and writing token permissions are no longer offered to them in the Change password dialog. The restriction applies to connecting by signing in described below as well; the “Access via a custom API” permission is not affected. A detailed description of the list is provided in the separate guide NET Genium settings.

Connecting by signing in

Tools that do not let you set the request header – typically Claude and ChatGPT – connect to the instance by signing in instead of by a token: the user enters only the address of the server, goes through the usual sign-in to the instance and on the consent screen ticks whether the application may read and write data. For them the instance is also an authorization server (OAuth 2.1) and issues them an access token of their own, valid for one hour, which the application renews on its own.

The rules are the same as with the personal token: access is granted only to a user with administrator rights, every request signs in as that user, and the permissions for reading and writing data are set by their consent. The connected applications are listed in the “Change password” dialog on the “Connected applications” tab, where the user can disconnect them at any time – disconnecting takes effect immediately. This way is available only on instances running at the root of the web site over HTTPS, so always in NET Genium Online; an instance in a subdirectory of the server stays with the personal token. The procedure is described in the text Connecting an AI tool to the MCP server.

Writing with or without the change history

When creating or updating a record you choose whether the change is also written into the change history and takes part in synchronization. By default it is written without them – the record is created or changed, but leaves no trace in the history.

• With the history write changes that have to stay traceable, and changes that some part of the platform reacts to.
• Without the history write bulk batches, typically test and sample data. The history would only grow without telling anyone anything.

If the “Disable history” property is turned on for the edit form, no history is written in any case.

What writing through the MCP server does not do

The record is saved directly, without the save scripts of the edit form. Neither “OnBeforeSave” nor “OnAfterSave” runs, and neither do the validations, recalculations, notifications and status changes built on them – the record is created, but the process logic that follows it is not.

What decides is therefore the nature of the data, not the environment: wherever process logic is attached to saving a record, the writing belongs in the form, even on a development instance. Where it is not, the MCP server can be used for writing in production as well – with the history turned on, so that the change stays traceable.

How an agent changes the model

Writing the model takes three steps, and an agent handles them on its own, directly against the running instance and with no files on a disk:

1. It reads the model – without a parameter it gets the overview of application groups, applications and edit forms, and with the name of an application its detailed inventory. The whole model is never returned at once because it is too large, so it is assembled application by application.
2. It composes the changes into three arrays – what to create, what to change and what to delete. Every item carries the kind of the entity, its identifier and the list of the properties being set; a newly created entity is given a temporary identifier, which the other items refer to and which the server replaces with the real one as it writes.
3. It sends them with the “write_model” tool. The arrays are processed in the order create, change, delete, and writing stops at the first item that fails – the error then carries the number of items already written and the map of the temporary identifiers, so the agent sends only the rest and creates nothing twice.

Application groups, applications, categories, edit forms, view pages, the controls of both, database queries, scripts, user groups and rights groups can all be created this way. What the model contains and how the agent reads it is described in the text The AI model of the implementation.

The images embedded in the text of a RichText control are returned by the server as the placeholder “Image: removed (base64)” in double square brackets, so that the answer does not grow by hundreds of kilobytes because of them. As the model is written, the placeholders are replaced back with the images of the stored value, in the order they appear in the text, so the text around the images can be changed without sending the images with it; when the number of the placeholders does not match the number of the images, the write ends with an error and the value stays unchanged.

Security

• Every request through the MCP server logs in as the token owner – it is therefore subject to the allowed IP addresses in the NET Genium settings and to licences, just like a regular login.
• Permissions are verified on every access – if the token owner loses administrator rights, access to the data ends immediately.
• When the list of users with access to the MCP server is filled in the NET Genium settings, only the built-in Administrator account and the listed users get through – removing somebody from the list ends their access immediately, with no need to delete the token.
• The server is protected against token guessing – repeated requests with an invalid token are slowed down.
• The write permission allows any data of the instance to be changed, not just a selected table or the user's own records – enable it 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,
• reading the change history to find out when and how a record changed,
• finding your way around an implementation – how the application is built and which tables and columns belong to it,
• 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,
• authenticating users against a custom API in customer projects.

This server is naturally followed by agentic development – an agent that asks the instance itself for the knowledge of the framework and for the model of the implementation can also work with the real contents of the applications.