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 Code, 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.
The setup has three steps: you find out the address of the server, generate your personal MCP token and enter both of them into your AI tool.
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 | http://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 – 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.
2. 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:
- Sign in to your instance and open the Change password link in the My settings section of the navigation area.
- Go to the MCP token tab and click Generate token.
- Turn on the Reading all data via the MCP server permission – and Writing all data via the MCP server only if the assistant is meant to change the data as well.
- Copy the token. It is displayed in readable form only once, when generated; only its fingerprint is stored on the server.
The token is valid for 90 days and one click extends it. Each user has at most one token and can delete it at any time – which ends the access immediately.
The permissions for reading and writing data can only be turned on for a user with administrator rights. The knowledge of the framework and the model of the implementation are not turned on by a checkbox – they are given to every token whose owner has administrator rights. The details of the token permissions are described in the text The integrated MCP server.
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, 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_..."
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.
4. Configuring the AI tool
Claude Code
Create the “.mcp.json” file in the root of the project – replace the address with the address of your instance:
{
"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.
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”,
- 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 via the MCP server permission turned off unless the agent is really meant to change the data. 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,
- 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 without a token (OAuth)
Tools that do not let you set the “Authorization” header – claude.ai and the other Claude surfaces – connect to the instance by signing in, not by a token. You 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.
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.
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 tool reports that the method does not exist | The token does not have the corresponding permission – the writing tools require “Writing all data via the MCP server”, the reading ones “Reading all data via the MCP server”. |
| 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 logs in as the owner of the token, 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.