Tools
Invantive MCP Server offers the following tools to an AI client such as Anthropic Claude. The tools on a database only read: they change no data and run no SQL statement. Only check_sql accepts one, which it parses without running it. The status tools work on a status page of Invantive Cloud Status instead of a database; four of them change the status page.
describe_entities: lists the entities that can be read from the database, with their name, label, type, data container and the order of magnitude of their number of rows. Available from release 26.0. See below.describe_entity: describes one entity in full, with its fields, primary key, unique keys, foreign keys and the speed to expect. Available from release 27.0. See below.read_records: reads rows from one entity, with a select, filter, sort and number of rows in the notation of the OData version 4 query interface. Available from release 26.0. See below.analyze_records: runs the same read asread_recordsand returns how it was executed instead of the rows. Available from release 28.0. See below.current_cloud_user: returns the profile of the signed-in user and of the organisation of that user, as held in Invantive Cloud. Available from release 26.0. See below.check_sql: checks the syntax of Invantive UniversalSQL and PSQL statements without running them. Available from release 28.0. See below.status_get_summary: returns the state of the status page at a glance. See below.status_list_incidents: lists the incidents of the status page, newest first. See below.status_get_incident: returns one incident with its components and updates. See below.status_create_incident: opens an incident on the status page. See below.status_add_update: posts an update on an incident, which can resolve it. See below.status_set_component_state: sets the state of one component. See below.status_schedule_maintenance: plans maintenance with a window. See below.
Instructions to the Client
When an AI client connects, the server sends it instructions. They name the version of the server and the addresses at which the same database is available for other clients, with whether the user activated each address: Invantive MCP Server, the SQL Server protocol of Invantive UniversalSQL Server for SQL Server clients and ODBC, Bridge Online for Power BI and App Online for applications, both over OData version 4. They also give advice on reading efficiently, name the rate limits of the platforms and point to Invantive Data Hub.
The instructions state as well that Invantive Cloud can exchange data between the database and other platforms, by replicating, combining or integrating it. They list the commercial names of those platforms, such as Exact Online, Salesforce and AFAS Profit. The list holds the platforms for which Invantive Cloud has a driver. Test drivers, helpers, obsolete drivers and the own products of Invantive are left out. The list is available from release 27.0.
Listing Entities
describe_entities lists the entities of the database that can be read, so that an AI client can choose one. It does not describe an entity in full: describe_entity does that for one entity. The tool takes two arguments, both optional:
entities: the names of the entities to list. A name is matched without regard to case and must be written as an earlier answer returned it. A single name or a comma-separated list is accepted in place of an array.nameOnly: when true, every entity is reduced to its name, label, type and data container. Use it only when the answer was truncated. Default is false.
The answer holds:
database: the URL segment of the database.detailLevel:summary, ornamesOnlywhennameOnlyapplied.entityCountandreturnedEntityCount: the number of entities that match the request and the number of entities in the answer.truncatedandtruncationHint: present when the answer holds fewer entities than match. The hint explains how to ask a narrower question, by naming the entities of interest inentities.unknownEntitiesandunknownEntitiesHint: present whenentitiesholds a name which does not exist. The hint names the closest existing entities for at most the first five unknown names.unknownEntitiesHintis available from release 27.0.dataContainers: one object per data container, since partitioning belongs to the data container and not to the entity. It holds thealiaswhich an entity name carries after the@, theproviderwhich serves the data container and whether itsupportsPartitions. A data container which supports partitions also holdspartitionLabelPlural,partitionCount,selectedPartitionCountandallPartitionsSelected: the term the platform uses for several partitions, such as divisions on Exact Online, the number of partitions available, the number a call ofread_recordsqueries and whether that is all of them.partitioningNote: how partitioning relates to the entities of this database. Present when at least one data container supports partitions.selectedPartitionCountTotal: the number of selected partitions over all data containers.entities: one object per entity, ordered by data container and then by name, so that a truncated answer leaves out the same entities on every call.
An entity holds:
name: the name to pass in theentityargument ofread_recordsanddescribe_entity.label: the label the platform uses for the contents. Present only when it differs fromname.type: the kind of object, such astable,viewortablefunction.dataContainer: the alias of the data container which holds the entity.rowCountBand: the order of magnitude of the number of rows, when the platform provides an estimate. The value isempty,<=100,<=1k,<=10k,<=100k,<=1Mor>1M.notReadable: true when the entity cannot be read. Absent otherwise.
The members rowCountBand and notReadable are left out when nameOnly applied.
Up to and including release 26.0 every entity also held description, keyField and partitionSpecific, and a data container held the whole partitioning: the terms, the partition column and the selected partitions. From release 27.0 these are in the answer of describe_entity. That keeps the list short and fast on a database with over a thousand entities.
The size of the answer is limited to 60,000 characters by default. The setting MaxDescribeEntitiesResponseChars changes that limit. It is available from release 26.0. The setting MaxEntityDescriptionChars is not used from release 27.0, since the list holds no descriptions.
The following arguments list two entities of the database:
{ "entities": [ "SalesInvoices", "Accounts" ] }
Describing an Entity
describe_entity describes one entity in full. An AI client calls it with a name from describe_entities, before it reads the entity with read_records. It is available from release 27.0. The tool takes one argument:
entity: the name of the entity, asdescribe_entitiesreturns it. A name is matched without regard to case. Required.
A name which does not exist is refused with message code itgenmcp665. The hint names the closest existing entities.
The answer holds:
database: the URL segment of the database.name,label,labelSingular,typeanddataContainer: as in the list.labelandlabelSingularare present only when they differ fromname.description: what the entity holds, written for a business user and in full.documentationis a further explanation, when the platform gives one.partitionSpecific: true when the contents depend on the selected partitions. Absent otherwise.notReadable: true when the entity cannot be read. Absent otherwise.rowCountBandandestimatedRowCount: the order of magnitude of the number of rows and the estimate itself, when the platform provides one. An estimate is not a count.performance: what to expect of the speed of reading the entity.primaryKey,uniqueKeysandforeignKeys: the keys and the relations to other entities.dataContainerDetailsandpartitioningNote: the data container which holds the entity and how partitioning relates to the entity.fieldCount,returnedFieldCount,truncatedandtruncationHint: the number of fields, the number in the answer and, when fields are left out, what to do about it.fields: the fields of the entity.
A field holds:
name: the name as theselect,filterandorderbyarguments ofread_recordsaccept it.label: the label the platform uses. Present only when it differs fromname.dataType: the OData version 4 primitive type, such asString,Int32,Decimal,DateTimeOffset,BooleanorGuid.nullable: whether the field can be empty.maxLength,precisionandscale: the length of a text or binary field and the digits of a decimal field, when the platform states them.primaryKey: true when the field is part of the primary key. Absent otherwise.description: what the field holds, written for a business user.filterOnPlatform: true when the platform itself evaluates a filter on the field, so that only the matching rows are fetched. False when every row is fetched first and filtered afterwards, which is slow on a large entity.sortOnPlatform: true when the platform itself sorts on the field. Absent when that is not known.
The members uniqueKeys and foreignKeys, and the guarantee of a key, are available from release 28.0. Release 27.0 answers the primary key without a guarantee, since its engine holds no other key metadata.
A key holds fields, guarantee and, when the platform gives one, name. The guarantee is enforced when the platform itself keeps the key unique and declared when the driver or the model states it without the platform enforcing it. The fields of a key are named as the fields of the entity. A name which is no field of the entity is written as the platform names the column. A key which repeats the primary key is not listed in uniqueKeys.
A foreign key is a relation from fields of this entity to the key of another entity. It holds:
fields: the fields of this entity which hold the reference.referencedEntityandreferencedFields: the entity referred to, asdescribe_entitiesnames it, and its fields, in the same order asfields.referencedTable: the name the platform gives the object referred to. Present only when that object is no entity of this database, in which casereferencedFieldsholds the column names of the platform.kind:keywhen the fields refer to a key of the referenced entity,textualwhen the relation exists in words only and holds under a condition, andcandidatewhen it follows from the names of the fields and holds in the data without the platform stating it.guarantee:enforcedordeclared, as for a key.description: says when atextualorcandidaterelation holds. A relation of these kinds does not hold for every row.name: the name of the foreign key on the platform, when it has one.
This server reads one entity per call and does not join. An AI client reads the related rows with a second call of read_records, filtering on the values of fields.
The performance holds the following members, when the driver of the platform states them:
accessLatencyMs: the average time of one round trip to the platform in milliseconds.fullScanRowsPerMinute: the average number of rows per minute when the whole entity is read.pointQueryRowsPerMinute: the average number of rows per minute when rows are read by a filter on a key.estimatedFullScanSeconds: an estimate of the time to read every row of the entity, fromestimatedRowCountandfullScanRowsPerMinute. It is present only when both are known.
The figures are static averages of the driver for the platform and not measurements of this database. The figure for writing is not returned, since the server only reads. A driver which states no figures leaves performance out.
The size of the answer is limited to 60,000 characters by default. The setting MaxDescribeEntityResponseChars changes that limit and MaxSelectedPartitionsDescribed the number of partitions listed in dataContainerDetails. Both are available from release 27.0 and 26.0 respectively. When the fields do not fit, the fields of the keys come first. The keys, the relations and the performance are never left out.
The following arguments describe one entity of the database:
{ "entity": "SalesInvoices" }
Reading Records
read_records reads rows from one entity. An AI client calls it once describe_entities has shown which entity holds the data and describe_entity has listed its fields. The tool takes the following arguments:
entity: the name of the entity, asdescribe_entitiesreturns it. Required.select: a comma-separated list of field names, asdescribe_entityreturns them, in the$selectnotation of the OData version 4 query interface.filter: the condition the rows must meet, in the$filternotation, with the operatorseq,ne,gt,ge,lt,le,and,orandnot.orderby: a list of fields with a direction, in the$orderbynotation, such asAmountDC desc.first: the maximum number of rows to read. When omitted, every row which matches the filter is read.
The read is translated into a select statement and executed under the authorisation of the signed-in user. The rows come back as structured content, one object per row with the selected fields. There is no cursor and no paging. An AI client passes first unless it wants the whole set, and narrows the answer with filter and orderby.
A field or literal which the OData parser does not know is refused with message code itgenmcp640. When the refusal is about a field, the hint names the fields of the entity which come closest. Dates and numbers are written without quotes.
The following arguments read the five largest open invoices of an entity:
{ "entity": "SalesInvoices"
, "select": "InvoiceNumber,AmountDC"
, "filter": "Status eq 20"
, "orderby": [ "AmountDC desc" ]
, "first": 5
}
Analysing a Read
analyze_records takes the arguments of read_records: entity, which is required, and select, filter, orderby and first. The read is translated into the same select statement, executed under the same authorisation and recorded in the same way. Its rows are read and counted, but not returned. The answer holds:
sqlStatement: theselectstatement that was executed.rowsReturnedandrowsRead: the rows the statement returned and the rows it read from all tables.counters: what the statement counted, summed over all steps, such asPairsEvaluatedorRowsSorted; only the counters which are not zero.steps: one object per step of the execution, such as the read of a table, a join or a sort, with the same members as a line of the/stepsfile of Invantive Data Hub: the kind and description of the step, the rows in and out, the duration, processor time and allocation including the steps below, the same figures without the steps below as explain analyze measures them, how a join matched its rows, the number of rows a table declares, and the counters of the step itself. The members of a step are written as on that line, starting with a capital, such asExclusiveCpuMs.
An AI client calls it when a read is slow or reads more rows than it returns, for instance to see whether a filter was handed to the data container, which join algorithm was chosen, or which step allocated the memory. Measuring every step costs a reading of the processor time per row per step, which only this tool pays.
The following arguments analyse the read of the five largest open invoices of an entity, with the same arguments read_records would take:
{ "entity": "SalesInvoices"
, "select": "InvoiceNumber,AmountDC"
, "filter": "Status eq 20"
, "orderby": [ "AmountDC desc" ]
, "first": 5
}
Reading the Current User
current_cloud_user returns the profile of the signed-in user and of the organisation of that user, as held in Invantive Cloud. An AI client calls it when the answer depends on who asks or on which organisation the data belongs to. The tool takes no arguments and reads nothing from the database.
The answer holds the following members of the user:
Uid,IwidandCognitoUserId: the identifiers of the user, of the web user and in the identity provider.Name,GivenNameandFamilyName: the full name, the first name and the last name.Gender:Mfor male,Ffor female andUfor unknown.JobTitle: the job title.EmailAddress,PhoneNumberandMobileNumber: how to reach the user.LanguageCode: the language in ISO 639-1 format. The default language of the service is used when the user has none.CreatedUtcandModifiedUtc: when the user was created and last modified.LogInStartUtcandLogInEndUtc: the period in which the user can log on.UserIconUrlandUserIcon: the thumbnail of the user as an address and in binary form.
The answer holds the following members of the organisation of the user:
PartyName: the name of the organisation. The name in the profile of the user is used first, and the name held by the organisation itself when the profile has none. The fallback is available from release 27.0.PartyAddressLine1,PartyAddressLine2,PartyAddressLine3,PartyPostalCode,PartyCityandPartyCountry: the address. The country of the organisation is used first, and the country in the profile of the user when the organisation holds none. The fallback is available from release 27.0.PartyEmailAddress,PartyPhoneandPartyWebSite: how to reach the organisation.PartyLegalStructure: the legal structure, such asNL-BV.PartyCoCNumber,PartyVatNumber,PartyIbanandPartyBic: the Chamber of Commerce number, the VAT number, the IBAN and the BIC.
The members PartyCurrencyCode, PartyState, PartyGlnNumber, PartyRsinNumber, PartySiretNumber, PartyPaypalIdentifier and PartyWageTaxNumber are part of the answer, but the service does not fill them. Invantive Cloud holds no value for them.
Checking the Syntax of SQL
check_sql parses one or more Invantive UniversalSQL and PSQL statements, separated by ;, without running them and without reading the database. An AI client calls it on a statement it wrote for Invantive Data Hub, Invantive Query Tool or a script, before the statement costs a budget or changes data. Names of tables and columns are not checked, since that needs the database. Available from release 28.0.
The tool takes one argument, sql, with at most 1,000,000 characters. The answer holds:
Valid:truewhen the statements follow the grammar.MessageCode,MessageandHint: the syntax error, its message with an excerpt and carets, and what to do. The codes are explained in Syntax Errors.Url: the address of the section of the message code in Syntax Errors.Position:LineandColumn, counted from 1 with a tab as one column,Offset, counted from 0 in the text, andLength, the number of characters marked.Syntax:Kindsuch asmissingorpremature-end,Expectedwith what is valid at the position as a list of untranslated items such asFROM,,,nameorexpression, andContextwith the part of the statement such aswhereClause.
A syntax error is the answer of the tool and not a failure of it: the result is not marked as an error.
Tools on Invantive Cloud Status
The status tools let an AI client read and maintain a status page of Invantive Cloud Status, for instance to answer whether a service is down or to report an outage. They are offered only on a server where the settings StatusPage:Server and StatusPage:ApiToken are set: the address of the status server, such as https://statuspage.invantive.eu, and an API token of one tenant, created under "Settings" and "API tokens". StatusPage:TimeoutSec sets the number of seconds a call may take, with a default of 20. The tools are not released yet.
The tools work on the pages of the tenant of the token. A token of scope read is enough for the three tools that read. The four tools that change the status page need a token of scope write; with a token of scope read the status server refuses them. A change is visible to readers at once and can notify subscribers, so the AI client is told to confirm the text with the user before calling.
The states of a component are operational, degraded_performance, partial_outage, major_outage and under_maintenance. The phases of an incident are investigating, identified, monitoring and resolved.
status_get_summary takes no arguments. The answer holds:
overallState: the most severe state over the components that count for the overall state.componentCount: the number of components.componentsNotOperational: per component that is not operational itscomponentcode,name,stateand the momentsincewhich it holds that state.openIncidents: per incident that is not resolved itspublicId,title,phase,impactandstartedAt.maintenance: the maintenance in progress or planned within seven days, withpublicId,title,phase,windowStartandwindowEnd.
status_list_incidents takes two optional arguments:
openOnly: when true, only incidents that are not resolved. Default is false.first: the number of the newest incidents to return, from 1 to 100. Default is 20.
The answer holds incidents, with the same members per incident as openIncidents of status_get_summary.
status_get_incident takes the publicId of an incident, such as 2026-0187. The answer is the incident as the management API of the status server returns it, with its affected components and their state, its timeline of updates with their phase and its version.
status_create_incident takes:
title: the title readers see. Required.message: the first update, for customers.impact: one ofnone,minor,majororcritical. Default isminor.phase: the phase of the first update. Default isinvestigating.template: the code of an incident template, which fills what is not given.components: the affected components, each with itscomponentcode and thestateit gets while the incident is open.
status_add_update takes:
publicId: the public id of the incident. Required.message: the text of the update, for customers. Required.phase: the phase of the update. Required. The phaseresolvedcloses the incident and returns its components to operational.internalNote: a note for operators only, which is never published or sent.
status_set_component_state takes:
component: the code of the component, asstatus_get_summaryreturns it. Required.state: the new state. Required.hold: when true, the probes do not change the state until an operator releases it. Default is true.
status_schedule_maintenance takes:
title: the title readers see. Required.message: what happens and what readers notice. Required.windowStartandwindowEnd: the start and end of the window as an ISO 8601 date and time with offset, such as2026-11-08T06:00:00+01:00. Required.components: the codes of the affected components.autoStart: start the maintenance at the start of the window. Default is true.autoComplete: complete the maintenance at the end of the window. Default is true.muteProbes: mute the probes of the affected components during the window. Default is true.
The tools that change the status page return the incident, the component or the maintenance as the status server returns it after the change.
Tracing the Size of an Answer
Invantive MCP Server writes the size of every answer to the trace in characters. The size is the quantity of the trace line with message code itgenmcp664, which is written at the debug level. It adds up the structured content and the text blocks of the answer, and the message names the tool, the database and both parts. The line is written for an answer which succeeded and for one which failed, since the AI client reads both in its context. The envelope of the JSON-RPC message is not counted. Available from release 27.0.
When a Tool Fails
A tool which fails answers with isError set and the details in the structured content, so that the AI client can tell the user what to do. The answer holds:
MessageandMessageCode: what went wrong, and the code to quote when asking for help.KindRequest: the hint, which is the next step for the AI client or the user. Every answer has one. When no specific hint is known, it says whether to send the request again, to correct it or to tell the user.NaturalKey: what the message is about, such as the database or the entity asked for.IsRecoverable: true when sending the same request again later can succeed and false when it cannot. It is left out when nothing indicates either.RetryAfterSec: the number of seconds the service advised to wait before the same request is sent again, from a lock-out or from theRetry-Afterheader of the platform. It is present only whenIsRecoverableis true and a wait was advised; no wait is made up. When the wait is longer than 60 seconds, the hint tells the AI client to leave the wait to the user. Available from release 27.0.Actor: who has to act first.aiwhen the AI client can correct the request or wait and send it again,userwhen a person has to decide or act outside the conversation, such as on a licence, an IP address or a log-on, andforumswhen nobody can solve it in the conversation, so that the reference and message code are looked up or reported at the forums. A wait of more than 60 seconds is for the user. Available from release 27.0.HelpUrl: the address of the forum topic or help page about the message code, when one is known. Available from release 27.0.Uid: the reference of the failure, to quote to support.
A request for an entity or a field which does not exist names the closest existing names in the hint. describe_entities does the same for the names in its entities argument, in unknownEntitiesHint. Both are available from release 27.0.
A request from an IP address which is not authorised for the database is refused with message code itgenmcp326. The message names the address and the hint names the database to which it must be added.
A status tool which fails answers in the same way. When the status server refuses the call, MessageCode holds the message code of the status server, or itgenmst001 when the answer holds none. A refusal for lack of scope write tells the user to ask for a token of scope write. itgenmst002 means that the status tools are not configured on the server, and itgenmst003 that the status server cannot be reached.