CS

MCP server setup

Home / Documentation / Administrator guide /

MCP server setup

CS

Connecting an AI tool to the MCP server

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.

Two ways to connect

A tool connects to the server in one of two ways. Both lead to the same server, give the same tools, and in both cases every request signs in as a particular user of the instance:

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 you need to know the address of the server.

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 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 a tool connecting by sign-in finds out where to send the user. The information page of the API is served to a signed-in administrator only, who can thus verify in a browser that the instance answers at that address.

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.

Connecting with a personal token

The setup has three steps: you generate your personal MCP token, store it in an environment variable and enter it together with the address of the server into the configuration of your AI tool.

1. The personal MCP 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.

01-mcp-token.png

On the same tab you will also find ready-made values for your instance – the server address, the command that stores the token in an environment variable, and the text with which you have the connection set up by your AI tool. You therefore do not have to assemble either of the two steps below by hand; each value next to it is copied with a single click.

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: the first one reading it, the second one changing it. 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. The details of the token permissions are described in the text The integrated MCP server.

2. 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, for example “NETGENIUM_MCP_TOKEN”, 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 following command:

setx NETGENIUM_MCP_TOKEN "ngt_..."

You do not have to assemble it by hand – the whole command with your own token is on the “MCP token” tab in the Environment variable field, and the icon next to it copies it to the clipboard. The real token is in it only right after it has been generated; later a “ngt_…” placeholder is shown instead.

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. Configuring the AI tool

Claude Code

Claude Code reads the configuration of MCP servers from the “.mcp.json” file in the root of the project. You do not have to write it, though. The “MCP token” tab has a ready-made text in the Setup prompt field – the icon next to it copies it, you paste it into Claude Code started in the root of the project, and it creates the 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 same text works in the other AI tools as well – it is written independently of where each tool keeps its configuration.

The finished configuration then looks like this in the file:

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

The “${NETGENIUM_MCP_TOKEN}” notation is replaced with the value of the environment variable when the file is loaded, so the token itself is not in the file. The name of the server (“netgenium”) is arbitrary; if you work with several instances, add a separate entry for each one with its own address and its own variable.

The server from the project file has to be approved by every user at the first start – Claude Code asks about it on its own.

Codex

Codex keeps the configuration of MCP servers in the “config.toml” file in the “.codex” directory of your home directory. You do not have to write it either – use the same Setup prompt from the “MCP token” tab; it is written independently of the tool, so every AI tool writes the entry where it belongs for it.

The finished entry then looks like this in the file:

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

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. The name of the server (“netgenium”) is again arbitrary, and for every further instance you add a further entry.

Microsoft Copilot Studio

Copilot Studio connects to an MCP server over streamable HTTP, so the integrated server of the instance needs nothing special. 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.

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_…”.

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

Connecting by signing in

Tools that do not let you set the “Authorization” header – Claude and ChatGPT in their web and desktop applications – connect to the instance by signing in, not by a token. You add the instance in them as a custom connector and enter the address of the server and nothing else; the tool finds out the rest on its own, opens the sign-in screen of your instance and asks what it may do once you are signed in.

The “Connecting an application” screen shows the name of the application, the address it returns to, and two check boxes – Read data and Write data. They are ticked according to what the application asked for; you may untick either of them. Once you allow it, the application receives an access token valid for one hour, which it renews on its own. The knowledge of the framework and the model of the implementation are given to it without any ticking – the same as with a personal token.

Access is granted this way only to a user with administrator rights – the same as with a personal token.

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.

This way of connecting is available only where 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.

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

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, it has neither reading nor writing turned on, its owner has lost administrator rights, its IP address is not among the allowed ones in the NET Genium settings, or the licences are exhausted. Check the “MCP token” tab in your instance.
The server returns the 403 error The owner of the token does not have administrator rights, or the list of users with access to the MCP server is filled in on the “Permissions” tab of the NET Genium settings and they are not on it. Ask the administrator of the instance to add you to the list.
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 and reading the model “Reading all data and the model via the MCP server”. 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 answers suddenly get slow Repeated requests with an invalid token have activated the protection against guessing tokens. Fix the token and wait a while; trying further values only prolongs the situation.

Every request through the MCP server signs in as a particular user – the owner of the token, or the one who allowed the application by signing in – so it is subject to the allowed IP addresses and to licences just like a regular login.

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.