MCP server setup

Quick overview

Every instance of NET Genium contains an integrated MCP server (Model Context Protocol) that lets you connect an AI assistant or agent to it – Claude or its developer variant Claude Code, ChatGPT or its developer variant Codex, Microsoft Copilot Studio or any other tool supporting the protocol. The server is part of the installation, there is nothing to install or start separately.

This text describes how to set the connection up. What the server can do, which tools it offers and what the security rules are is described in the separate text The integrated MCP server. Partners building customer implementations on the platform connect the partner MCP server with the Agent Kit next to it.

Choose your tool

More

1. Before you start

1.1. The address of the server

The MCP server is handled by the “api.aspx” page in the root of the instance of NET Genium:

http(s)://<server>/<path-to-the-instance>/api.aspx

Instance in a subdirectory	https://server/netgenium/api.aspx
Instance in the root of the site	https://netgenium.company.com/api.aspx
NET Genium Online	https://identifier.netgenium.online/api.aspx

The address of the server is not “/mcp”. That one belongs to the separate API project of a customer solution; it does not exist on the NET Genium instance itself.

A signed-in administrator can verify the address in a browser: the address of the “api.aspx” page shows them the information page of the API. The instance does not serve it to other visitors.

1.2. Two ways to connect

A tool connects to the server in one of two ways. Both lead to the same server and give the same tools:

Way	How it works	For which tools	Where it works
With a personal token	You generate a personal MCP token in the instance and pass it to the tool in the request header.	Claude Code, Codex, Microsoft Copilot Studio and other tools that can set the “Authorization” header	any instance, including one in a subdirectory of the server
By signing in	You enter only the address of the server; the tool opens the sign-in screen of the instance and, once you are signed in, asks what it may do. Nothing is copied or stored.	Claude and ChatGPT (web and desktop applications); Claude Code and Codex can do it as well	only an instance running at the root of the web site over HTTPS – always the case in NET Genium Online

The personal token is the recommended way. It works with any instance – including one running in a subdirectory of the server – you set it up once, and it needs no interactive sign-in, which also makes it suitable for an agent running unattended. Use signing in where the tool does not let you set the “Authorization” header – in Claude and ChatGPT in their web and desktop applications.

In both cases every request signs in as a particular user of the instance – the owner of the token, or the one who allowed the connection by signing in – so it is subject to the allowed IP addresses and to licences just like a regular login.

2. The personal MCP token

The personal token is used by Claude Code, Codex, Microsoft Copilot Studio and other tools that can set the “Authorization” header. You generate the token and store it in an environment variable; both are the same for every tool. The configuration of the tool itself is then described in the chapters of the individual tools below.

2.1. Generating the token

The client identifies itself to the server with a personal MCP token in the form “ngt_...”. Each user generates their own token:

1. Sign in to your instance and open the Change password link in the My settings section of the navigation area.
2. Go to the MCP token tab and click Generate token. The token appears at once, but it does not exist yet.
3. Turn on the Reading all data and the model via the MCP server permission – and Writing all data and the model via the MCP server only if the assistant is meant to change the data or the applications as well.
4. Click Save. Only then are the token and its permissions created.
5. Copy the token while the dialog is open. It is displayed in readable form only once; only its fingerprint is stored on the server.

The token is valid for 90 days. Once it expires, an Extend token button appears and generates a new token – which, too, comes into existence only when you save. Each user has at most one token and can delete it at any time; unlike the other changes, deleting is not saved and the access ends immediately.

Only a user with administrator rights can have either permission. Besides the data they cover the implementation model as well: it can be read with either of them, and changed only with the second one. A token with neither box ticked is left with the knowledge of the framework – that one is given to every token whose owner has administrator rights and is not excluded by the list “Administrators with access to the MCP server”. The details of the token permissions are described in the text The integrated MCP server.

2.2. Values for your instance

Next to the token, the “MCP token” tab has three fields with ready-made values for your instance. The icon next to each one copies it to the clipboard, so you do not have to assemble anything in the steps that follow by hand:

Field	What it contains	Where you use it
Server address	the address of the “api.aspx” page of your instance	in the configuration of a tool that is set up by hand – Microsoft Copilot Studio and other tools
Environment variable	the command that stores the token in an environment variable	in the Windows command prompt – see the following section
Setup prompt	the text with which you have the connection set up by your AI tool	in Claude Code, Codex or another AI tool that writes its configuration on its own

The setup prompt is written independently of the tool, so every AI tool writes the entry where it belongs for it.

2.3. Storing the token in an environment variable

The token is a credential – do not write it into configuration files. Store it in an environment variable and only refer to that variable in the configuration. Configuration files are usually part of version control and the token would reach the source code server with the nearest commit.

On Windows you create the variable with the command from the Environment variable field. For the instance at the address “https://identifier.netgenium.online” it looks like this, for example:

setx MCP_TOKEN_IDENTIFIER_NETGENIUM_ONLINE "ngt_..."

The real token is in the field only right after it has been generated; later a “ngt_…” placeholder is shown instead. The name of the variable is derived from the address of the instance by the rule described in the chapter The name of the server and the environment variable.

The new value only takes effect in newly started programs – after creating or changing the variable, restart your AI tool. After extending the token you only change the value of the variable, the configuration stays as it is.

3. Claude Code

The connection requires a personal MCP token stored in an environment variable.

3.1. Setting up with the prompt

Copy the ready-made text from the Setup prompt field on the “MCP token” tab and paste it into Claude Code started in the root of the project. Claude Code creates the “.mcp.json” file on its own, with the address of your instance and with the reference to the environment variable. Finally it verifies that the variable exists and that its value starts with “ngt_”, and tells you what else to do so that it sees the server.

The server from the “.mcp.json” file – whether the prompt created it or you wrote it by hand – has to be approved by every user at the first start; Claude Code asks about it on its own.

3.2. Manual configuration

Claude Code reads the configuration of MCP servers from the “.mcp.json” file in the root of the project. The configuration consists of the address of your instance and two names derived from it. For the instance at the address “https://identifier.netgenium.online” it looks like this, for example:

{
 "mcpServers": {
  "identifier-netgenium-online": {
   "type": "http",
   "url": "https://identifier.netgenium.online/api.aspx",
   "headers": {
    "Authorization": "Bearer ${MCP_TOKEN_IDENTIFIER_NETGENIUM_ONLINE}"
   }
  }
 }
}

For your instance three values differ: the address in the “url” key, the name of the server above it and the name of the variable in the “Authorization” header. You copy the address from the Server address field and derive both names by the rule in the chapter The name of the server and the environment variable.

The “${MCP_TOKEN_IDENTIFIER_NETGENIUM_ONLINE}” notation is replaced with the value of the environment variable when the file is loaded, so the token itself is not in the file. If you work with several instances, add a separate entry for each one – thanks to the rule each has its own name and its own variable, and no two of them collide.

3.3. Connecting by signing in

Claude Code can also connect by signing in, without a token: you add the server with the command “claude mcp add --transport http netgenium https://identifier.netgenium.online/api.aspx” with the server address of your instance and start the sign-in with the “/mcp” command in an open conversation. The personal token is the simpler choice, though – it works for an instance in a subdirectory as well and needs no interactive sign-in.

4. Codex

The connection requires a personal MCP token stored in an environment variable.

4.1. Setting up with the prompt

Copy the ready-made text from the Setup prompt field on the “MCP token” tab and paste it into Codex. Codex writes the entry into its configuration on its own, with the address of your instance and with the reference to the environment variable.

4.2. Manual configuration

Codex keeps the configuration of MCP servers in the “config.toml” file in the “.codex” directory of your home directory. For the instance at the address “https://identifier.netgenium.online” the entry in it looks like this, for example:

[mcp_servers.identifier-netgenium-online]
url = "https://identifier.netgenium.online/api.aspx"
bearer_token_env_var = "MCP_TOKEN_IDENTIFIER_NETGENIUM_ONLINE"

The “bearer_token_env_var” key carries the name of the environment variable, not the token itself – Codex reads the value at start-up and sends it in the “Authorization” header.

For your instance three values differ: the name of the server in the square brackets, the address in the “url” key and the name of the variable in the “bearer_token_env_var” key. You copy the address from the Server address field and derive both names by the rule in the chapter The name of the server and the environment variable. For every further instance you add a further entry.

4.3. Connecting by signing in

Codex can also connect by signing in, without a token: you add the server with the command “codex mcp add netgenium --url https://identifier.netgenium.online/api.aspx” with the server address of your instance and sign in with the command “codex mcp login netgenium”. The personal token is the simpler choice, though – it works for an instance in a subdirectory as well and needs no interactive sign-in.

5. Microsoft Copilot Studio

Copilot Studio connects to an MCP server over streamable HTTP, so the integrated server of the instance needs nothing special. The connection requires a personal MCP token. When adding the server as a tool of the agent, enter:

• the address – the “api.aspx” page in the root of the instance, for example “https://identifier.netgenium.online/api.aspx”; you copy it from the Server address field on the “MCP token” tab,
• the authentication – the “Authorization” header with the value “Bearer ngt_...”.

Two things are worth deciding before you connect the agent:

• Whose token the agent uses. Every request logs in as the owner of the token, so the agent sees exactly what that user sees and every change is recorded under their name. An agent shared by a team therefore usually deserves its own account – keep in mind, though, that such an account counts as a user of the instance like any other.
• Whether the agent may write. Leave the Writing all data and the model via the MCP server permission turned off unless the agent is really meant to change the data or the applications. Reading is enough for questions and analyses.

The wizard for adding tools in Copilot Studio changes with the product; the values above are what it asks for, regardless of the wording of the individual steps.

6. Other tools

In a tool that connects to an MCP server over HTTP, enter:

• the address of the server – the “api.aspx” page in the root of the instance; you copy it from the Server address field on the “MCP token” tab,
• the header “Authorization” with the value “Bearer ngt_...” – you generate the token as described in the chapter The personal MCP token.

If the tool can write its configuration on its own, use the Setup prompt from the “MCP token” tab instead.

The server also supports the “OPTIONS” request (CORS preflight), so tools running in a browser can connect to it as well.

7. Claude and ChatGPT

The Claude and ChatGPT applications, web and desktop alike, do not let you set the “Authorization” header, so they connect to the instance by signing in, not by a token. Nothing is copied or stored in the process.

7.1. Requirements

• The instance runs at the root of the web site (which is always the case in NET Genium Online) and over HTTPS. An instance in a subdirectory of the server stays with the personal token.
• Access is granted this way only to a user with administrator rights – the same as with a personal token.

7.2. Procedure

1. In the application, add the instance as a custom connector and enter only the address of the server.
2. The application finds out the rest on its own and opens the sign-in screen of your instance. Sign in.
3. On the “Connecting an application” screen, check what the application may do and allow the connection.

The “Connecting an application” screen shows the name of the application, the address it returns to, and two check boxes – Read data and the model and Write data and the model. They are ticked according to what the application asked for; you may untick either of them. The model of the implementation is given to the application only with reading or writing data ticked. With neither reading nor writing ticked, the connection is refused – with the single exception described in the Details section.

7.3. Disconnecting

The connected applications are listed in the Change password dialog on the “Connected applications” tab, where you also disconnect them. Disconnecting takes effect immediately – the application loses the access before its token expires.

7.4. Details

Once allowed, the application receives an access token valid for one hour. It renews the token on its own only if it asked for permanent access (the “offline_access” scope) – it then also receives a refresh token valid for 30 days. An application that asked for permanent access connects even with neither reading nor writing ticked and receives just the knowledge of the framework – the same as a personal token without the permissions to read and write.

The “api.aspx” page recognises an MCP request by the token in the “Authorization” header. Without a valid token it answers with the status code 401 and the “WWW-Authenticate” header, as the MCP protocol prescribes – that is how the application finds out where to send the user to sign in.

The instance limits the registration of an application, the download of its description (the metadata document) when issuing tokens and the download of the description on the consent screen before signing in to a combined 60 requests per hour from one IP address. After signing in, the download of the description on the consent screen has its own limit of 60 requests per hour, separate for each user. Before downloading the description, the instance verifies that its address does not resolve to the internal network of the server.

8. The name of the server and the environment variable

The name of the MCP server in the configuration of the tool and the name of the environment variable with the token are both derived from the address of the instance by a single rule:

• the name of the server is the address without the protocol, the port and “www”, read from left to right, with dots and slashes replaced by hyphens,
• the name of the variable is the same text in upper case, with underscores instead of hyphens and with the “MCP_TOKEN_” prefix.

Address of the instance	Name of the server	Name of the variable
https://identifier.netgenium.online	identifier-netgenium-online	MCP_TOKEN_IDENTIFIER_NETGENIUM_ONLINE
https://portal.company.com/dev	portal-company-com-dev	MCP_TOKEN_PORTAL_COMPANY_COM_DEV

Every instance thus has a name unique across everything you connect to, and you can derive it from the address even without the dialog – the dialog, the “ai-model” utility and this guide all use the same rule. The partner MCP server has the fixed name “netgenium-framework”; the variable “MCP_TOKEN_NETGENIUM_FRAMEWORK” comes from it by the same rewriting.

9. The partner MCP server

Partners building customer implementations on the platform (see Partner program) connect a second MCP server next to the server of the instance – the partner MCP server of NetGenium. Each of them gives the agent something different:

Server	What it gives
MCP server of the instance (“api.aspx”)	the data and the implementation model of the particular instance, the diagnostics of its performance and a selection of the framework knowledge matching its version
Partner MCP server	the Agent Kit – the platform rules, skills, subagents, helper scripts and the complete framework documentation; no data and no model of any instance

9.1. What the partner server provides

Tool	What it returns
search_framework_docs	the matching sections of the documentation, the rules, the skills and the subagents at once – the default way into the knowledge
get_framework_doc, list_framework_docs	a page of the framework documentation or one of its sections, the list of all pages
get_rule, get_skill, get_agent	a rule, a skill (the “SKILL.md” file) or a subagent, whole or by sections
get_script	the source code of a PowerShell helper script
list_resources	the list of rules, skills, subagents and scripts with their size

All the tools only read. The documentation and the rules match the latest released version of the framework; content meant only for the NetGenium team is not provided by the server.

9.2. Address and token

The server runs at the address:

https://www.netgenium.com/api/mcp

The client identifies itself with a partner token in the “Authorization” header (“Bearer”). You do not generate this token in an instance – NetGenium issues it on request sent to support@netgenium.com. Unlike the personal MCP token it is not tied to a user of any instance, it does not have the “ngt_...” form and its validity is not limited: it is valid until NetGenium revokes it. The token also sets the language of the knowledge provided (Czech or English) and the language of the file names of the implementation model the rules refer to.

The token is a credential just like the personal MCP token – store it in the environment variable “MCP_TOKEN_NETGENIUM_FRAMEWORK” and only refer to that variable in the configuration:

setx MCP_TOKEN_NETGENIUM_FRAMEWORK "..."

9.3. Configuring the AI tool

In Claude Code both servers stand next to each other in the “.mcp.json” file in the root of the repository:

{
 "mcpServers": {
  "netgenium-framework": {
   "type": "http",
   "url": "https://www.netgenium.com/api/mcp",
   "headers": {
    "Authorization": "Bearer ${MCP_TOKEN_NETGENIUM_FRAMEWORK}"
   }
  },
  "identifier-netgenium-online": {
   "type": "http",
   "url": "https://identifier.netgenium.online/api.aspx",
   "headers": {
    "Authorization": "Bearer ${MCP_TOKEN_IDENTIFIER_NETGENIUM_ONLINE}"
   }
  }
 }
}

In Codex a further entry is added to the “config.toml” file next to the entry of the instance:

[mcp_servers.netgenium-framework]
url = "https://www.netgenium.com/api/mcp"
bearer_token_env_var = "MCP_TOKEN_NETGENIUM_FRAMEWORK"

If you download the implementation model with the “ai-model” utility, it writes both entries into “.mcp.json” on its own – the server of the instance according to the address the model is downloaded from. The environment variables with both tokens have to be created by hand, though.

9.4. Both servers side by side

The servers work together without any conflict. An AI tool tells the tools apart by the name of the server, so tools with the same name coming from different servers do not get in each other's way. Only the framework knowledge tools (“search_framework_docs”, “get_framework_doc”, “list_framework_docs”) have the same names, as both servers offer them – each of them with a different scope, though:

	Partner MCP server	MCP server of the instance
Framework documentation	all pages, the latest released version	a selection of pages, the version the instance runs on
Rules	all except the internal ones	only a selection of the platform rules bundled with the knowledge
Skills, subagents, scripts	yes	no
Data and implementation model	no	yes, according to the permissions of the token

The agent therefore takes the framework knowledge from the partner server and uses the server of the instance for the data, the implementation model and the diagnostics. Both servers tell the agent the same in the instructions they send it when it connects, so it picks the right server on its own.

10. Troubleshooting

Symptom	Cause and remedy
The server returns error 404	A wrong address – the endpoint is the “api.aspx” page in the root of the instance, not “/mcp”.
The server returns the 401 error	The token is missing, invalid or has expired. Check the “MCP token” tab in your instance.
The server returns the 403 error	The token is valid, but access of its owner was denied: the owner does not have administrator rights, is not in the list of administrators with access to the MCP server, the licence key does not allow AI, their IP address is not among the allowed ones in the NET Genium settings, or the licences are exhausted. The reason is given in the server response and in the “Auth” log.
The tool offers no sign-in, or reports that the server does not support it	The instance does not run at the root of the web site over HTTPS, so it is not an authorization server. Use the personal token.
The tool reports that the method does not exist	The token does not have the corresponding permission – the writing tools and writing the model require “Writing all data and the model via the MCP server”, the reading tools “Reading all data and the model via the MCP server”, and reading the model either of the two permissions. With a connection by sign-in the corresponding permission was not ticked on the consent screen – disconnect the application and connect it again.
The tool does not see the server at all	The environment variable with the token is missing, the user has not approved the server, or the tool has not been restarted since the configuration changed.
The partner MCP server returns the 401 error	The partner token is missing or NetGenium has revoked it. Check the environment variable with the token; a personal MCP token “ngt_...” is not valid here.
A “please wait” page arrives instead of an answer	Repeated requests with an invalid token have activated the protection against guessing tokens, and the server does not serve any requests from that IP address for a while. Failed requests from the same IP address to exchange an authorization code or a refresh token when connecting through OAuth count towards the same limit as well, and so do wrong passwords entered on the pages protected by a password from the NET Genium settings dialog (print templates, restart, AI model) if a visitor who has not signed in enters them from the same IP address. The token needs to be fixed, followed by a short wait; trying further values only prolongs the situation.

The connection you have set up is the basis of agentic development – working with an AI agent that knows both the framework and the particular implementation and can work in it purposefully.