Rychlý přehled
Každá instance NET Genia obsahuje integrovaný MCP server (Model Context Protocol), přes který se k ní připojí AI asistent nebo agent – Claude nebo jeho vývojářská varianta Claude Code, ChatGPT nebo jeho vývojářská varianta Codex, Microsoft Copilot Studio nebo kterýkoli jiný nástroj podporující tento protokol. Server je součástí instalace, nic se neinstaluje ani nespouští zvlášť.
Tento text popisuje, jak připojení nastavit. Co server umí, jaké nástroje nabízí a jaká pravidla platí pro bezpečnost, popisuje samostatný text Integrovaný MCP server. Partneři, kteří na platformě staví zákaznické implementace, připojují vedle něj ještě partnerský MCP server s agentní výbavou.
Vyberte svůj nástroj
Další
1. Než začnete
1.1. Adresa serveru
MCP server obsluhuje stránka „api.aspx“ v kořeni instance NET Genia:
http(s)://<server>/<cesta-k-instanci>/api.aspx
| Instance v podadresáři | https://server/netgenium/api.aspx |
| Instance v kořeni webu | https://netgenium.firma.cz/api.aspx |
| NET Genium Online | https://identifikator.netgenium.online/api.aspx |
Adresou serveru není „/mcp“. Ta patří samostatnému projektu API v zákaznickém řešení; na samotné instanci NET Genia neexistuje.
Správnost adresy si přihlášený administrátor ověří v prohlížeči: na adrese stránky „api.aspx“ se mu zobrazí informační stránka rozhraní API. Ostatním návštěvníkům ji instance nevydá.
1.2. Dva způsoby připojení
Nástroj se k serveru připojí jedním ze dvou způsobů. Oba vedou na tentýž server a dávají tytéž nástroje:
| Způsob | Jak probíhá | Pro které nástroje | Kde funguje |
| Osobním tokenem | V instanci si vygenerujete osobní MCP token a nástroji ho předáte v hlavičce požadavku. | Claude Code, Codex, Microsoft Copilot Studio a další nástroje, které si umí nastavit hlavičku „Authorization“ | kterákoli instance, i v podadresáři serveru |
| Přihlášením | Zadáte jen adresu serveru; nástroj otevře přihlašovací obrazovku instance a po přihlášení se zeptá, co smí. Nic se nekopíruje ani neukládá. | Claude a ChatGPT (webová i desktopová aplikace); umí to i Claude Code a Codex | jen instance běžící v kořeni webu přes HTTPS – v NET Genium Online vždy |
Doporučeným způsobem je osobní token. Funguje u kterékoli instance – i u té, která běží v podadresáři serveru – nastavíte ho jednou a nevyžaduje interaktivní přihlášení, takže se hodí i pro agenta běžícího bez obsluhy. Přihlášení použijte tam, kde si nástroj hlavičku „Authorization“ nastavit nedovolí – v aplikacích Claude a ChatGPT ve webové i desktopové podobě.
V obou případech se každý požadavek přihlašuje jako konkrétní uživatel instance – vlastník tokenu, nebo ten, kdo připojení přihlášením povolil – takže podléhá povoleným IP adresám i licencím stejně jako běžné přihlášení.
2. Osobní MCP token
Osobní token používají Claude Code, Codex, Microsoft Copilot Studio a ostatní nástroje, které si umí nastavit hlavičku „Authorization“. Token si vygenerujete a uložíte do proměnné prostředí; obojí je pro všechny nástroje stejné. Konfiguraci samotného nástroje pak popisují kapitoly jednotlivých nástrojů níže.
2.1. Vygenerování tokenu
Klient se serveru prokazuje osobním MCP tokenem ve tvaru „ngt_...“. Token si vygeneruje každý uživatel sám:
- Přihlaste se do své instance a v navigační oblasti v sekci Moje nastavení otevřete odkaz Změnit heslo.
- Přejděte na záložku MCP token a klikněte na Vygenerovat token. Token se hned zobrazí, ale zatím nevznikl.
- Zapněte oprávnění Čtení všech dat a modelu přes MCP server – a Zápis všech dat a modelu přes MCP server jen tehdy, má-li asistent data nebo aplikace i měnit.
- Klikněte na Uložit. Teprve tím token i jeho oprávnění vzniknou.
- Token si zkopírujte, dokud je dialog otevřený. V čitelné podobě se zobrazí pouze jednou; na serveru se ukládá jen jeho otisk.
Platnost tokenu je 90 dnů. Po jejím vypršení přibude tlačítko Prodloužit token, které vygeneruje token nový – i ten vznikne až uložením. Každý uživatel má nejvýše jeden token a může ho kdykoli smazat; smazání se na rozdíl od ostatních změn neukládá a přístup končí okamžitě.
Obě oprávnění může mít jen uživatel s administrátorskými právy. Kromě dat pokrývají i implementační model: číst ho lze s kterýmkoli z nich, měnit jen s druhým. Token bez obou zaškrtnutí zůstane u znalostí frameworku – ty dostane každý token, jehož vlastník má administrátorská práva a není vyloučený seznamem „Administrátoři s přístupem k MCP serveru“. Podrobnosti o oprávněních tokenu popisuje text Integrovaný MCP server.
2.2. Hodnoty pro vaši instanci
Na záložce „MCP token“ jsou vedle tokenu tři pole s hotovými hodnotami pro vaši instanci. Každé zkopírujete do schránky ikonou vedle něj, takže nic z dalšího postupu nemusíte skládat ručně:
| Pole | Co obsahuje | Kam ho použijete |
| Adresa serveru | adresu stránky „api.aspx“ vaší instance | do konfigurace nástroje, který se nastavuje ručně – Microsoft Copilot Studio a ostatní nástroje |
| Proměnná prostředí | příkaz, kterým token uložíte do proměnné prostředí | do příkazového řádku Windows – viz následující oddíl |
| Prompt pro nastavení | text, kterým si připojení necháte nastavit svým AI nástrojem | do Claude Code, Codexu nebo jiného AI nástroje, který si konfiguraci zapíše sám |
Prompt pro nastavení je psaný nezávisle na nástroji, takže si každý AI nástroj záznam zapíše tam, kam patří u něj.
2.3. Uložení tokenu do proměnné prostředí
Token je přihlašovací údaj – nevpisujte ho do konfiguračních souborů. Uložte si ho do proměnné prostředí a v konfiguraci se na ni jen odkazujte. Konfigurační soubory bývají součástí správy verzí a token by se s nejbližším uložením dostal na server se zdrojovým kódem.
Ve Windows proměnnou vytvoříte příkazem z pole Proměnná prostředí. Pro instanci na adrese „https://identifikator.netgenium.online“ vypadá například takto:
setx MCP_TOKEN_IDENTIFIKATOR_NETGENIUM_ONLINE "ngt_..."
Skutečný token je v poli jen hned po vygenerování; později se místo něj zobrazuje „ngt_…“. Název proměnné se odvozuje z adresy instance pravidlem popsaným v kapitole Název serveru a proměnné prostředí.
Nová hodnota se projeví až v nově spuštěných programech – po vytvoření nebo změně proměnné svůj AI nástroj restartujte. Po prodloužení tokenu měníte pouze hodnotu proměnné, konfigurace zůstává beze změny.
3. Claude Code
Připojení předpokládá osobní MCP token uložený v proměnné prostředí.
3.1. Nastavení promptem
Zkopírujte hotový text z pole Prompt pro nastavení na záložce „MCP token“ a vložte ho do Claude Code spuštěného v kořeni projektu. Claude Code založí soubor „.mcp.json“ sám, s adresou vaší instance i s odkazem na proměnnou prostředí. Nakonec ověří, že proměnná existuje a její hodnota začíná „ngt_“, a řekne vám, co ještě udělat, aby server viděl.
Server ze souboru „.mcp.json“ – ať ho založil prompt, nebo jste ho napsali ručně – musí každý uživatel při prvním spuštění schválit; Claude Code se na to sám zeptá.
3.2. Ruční konfigurace
Claude Code čte konfiguraci MCP serverů ze souboru „.mcp.json“ v kořeni projektu. Konfigurace se skládá z adresy vaší instance a dvou názvů z ní odvozených. Pro instanci na adrese „https://identifikator.netgenium.online“ vypadá například takto:
{
"mcpServers": {
"identifikator-netgenium-online": {
"type": "http",
"url": "https://identifikator.netgenium.online/api.aspx",
"headers": {
"Authorization": "Bearer ${MCP_TOKEN_IDENTIFIKATOR_NETGENIUM_ONLINE}"
}
}
}
}
U vaší instance se liší tři hodnoty: adresa v klíči „url“, název serveru nad ní a název proměnné v hlavičce „Authorization“. Adresu zkopírujete z pole Adresa serveru, oba názvy odvodíte pravidlem v kapitole Název serveru a proměnné prostředí.
Zápis „${MCP_TOKEN_IDENTIFIKATOR_NETGENIUM_ONLINE}“ se při načtení souboru nahradí hodnotou proměnné prostředí, takže samotný token v souboru není. Pracujete-li s více instancemi, přidejte pro každou samostatný záznam – díky pravidlu má každá vlastní jméno i vlastní proměnnou a žádné dvě se nepotkají.
3.3. Připojení přihlášením
Claude Code se umí připojit i přihlášením, bez tokenu: server přidáte příkazem „claude mcp add --transport http netgenium https://identifikator.netgenium.online/api.aspx“ s adresou serveru své instance a přihlášení spustíte příkazem „/mcp“ v otevřené konverzaci. Osobní token je ale jednodušší volbou – funguje i u instance v podadresáři a nevyžaduje interaktivní přihlášení.
4. Codex
Připojení předpokládá osobní MCP token uložený v proměnné prostředí.
4.1. Nastavení promptem
Zkopírujte hotový text z pole Prompt pro nastavení na záložce „MCP token“ a vložte ho do Codexu. Codex si záznam zapíše do své konfigurace sám, s adresou vaší instance i s odkazem na proměnnou prostředí.
4.2. Ruční konfigurace
Codex si konfiguraci MCP serverů drží v souboru „config.toml“ v adresáři „.codex“ ve vašem domovském adresáři. Pro instanci na adrese „https://identifikator.netgenium.online“ vypadá záznam v něm například takto:
[mcp_servers.identifikator-netgenium-online]
url = "https://identifikator.netgenium.online/api.aspx"
bearer_token_env_var = "MCP_TOKEN_IDENTIFIKATOR_NETGENIUM_ONLINE"
Klíč „bearer_token_env_var“ nese název proměnné prostředí, ne token samotný – Codex si hodnotu přečte při startu a pošle ji v hlavičce „Authorization“.
U vaší instance se liší tři hodnoty: název serveru v hranatých závorkách, adresa v klíči „url“ a název proměnné v klíči „bearer_token_env_var“. Adresu zkopírujete z pole Adresa serveru, oba názvy odvodíte pravidlem v kapitole Název serveru a proměnné prostředí. Pro každou další instanci přidáte další záznam.
4.3. Připojení přihlášením
Codex se umí připojit i přihlášením, bez tokenu: server přidáte příkazem „codex mcp add netgenium --url https://identifikator.netgenium.online/api.aspx“ s adresou serveru své instance a přihlásíte se příkazem „codex mcp login netgenium“. Osobní token je ale jednodušší volbou – funguje i u instance v podadresáři a nevyžaduje interaktivní přihlášení.
5. Microsoft Copilot Studio
Copilot Studio se k MCP serveru připojuje přes streamable HTTP, takže integrovaný server instance nepotřebuje nic navíc. Připojení předpokládá osobní MCP token. Při přidávání serveru jako nástroje agenta zadejte:
- adresu – stránku „api.aspx“ v kořeni instance, například „https://identifikator.netgenium.online/api.aspx“; zkopírujete ji ze záložky „MCP token“ z pole Adresa serveru,
- autentizaci – hlavičku „Authorization“ s hodnotou „Bearer ngt_...“.
Dvě věci stojí za rozhodnutí ještě před připojením agenta:
- Čí token agent používá. Každý požadavek se přihlašuje jako vlastník tokenu, takže agent vidí přesně to co on a každá změna se zapíše pod jeho jménem. Agent sdílený týmem si proto obvykle zaslouží vlastní účet – počítejte ale s tím, že takový účet se počítá mezi uživatele instance jako každý jiný.
- Jestli agent smí zapisovat. Oprávnění Zápis všech dat a modelu přes MCP server nechte vypnuté, dokud agent opravdu nemá data nebo aplikace měnit. Na dotazy a analýzy stačí čtení.
Průvodce přidáním nástrojů se v Copilot Studiu s produktem mění; hodnoty výše jsou to, na co se ptá, bez ohledu na formulaci jednotlivých kroků.
6. Ostatní nástroje
V nástroji, který se k MCP serveru připojuje přes protokol HTTP, zadejte:
- adresu serveru – stránku „api.aspx“ v kořeni instance; zkopírujete ji ze záložky „MCP token“ z pole Adresa serveru,
- hlavičku „Authorization“ s hodnotou „Bearer ngt_...“ – token vygenerujete podle kapitoly Osobní MCP token.
Umí-li si nástroj konfiguraci zapsat sám, použijte místo toho Prompt pro nastavení ze záložky „MCP token“.
Server podporuje i dotaz „OPTIONS“ (CORS preflight), takže se k němu připojí i nástroje běžící v prohlížeči.
7. Claude a ChatGPT
Aplikace Claude a ChatGPT ve webové i desktopové podobě si hlavičku „Authorization“ nastavit nedovolují, a proto se k instanci připojují přihlášením, ne tokenem. Nic se přitom nekopíruje ani neukládá.
7.1. Podmínky
- Instance běží v kořeni webu (v NET Genium Online vždy) a přes HTTPS. Instance v podadresáři serveru zůstává u osobního tokenu.
- Přístup takto získá jen uživatel s administrátorskými právy – stejně jako u osobního tokenu.
7.2. Postup
- V aplikaci přidejte instanci jako vlastní konektor a zadejte pouze adresu serveru.
- Aplikace si zbytek zjistí sama a otevře přihlašovací obrazovku vaší instance. Přihlaste se.
- Na obrazovce „Připojení aplikace“ zkontrolujte, co aplikace smí, a připojení povolte.
Obrazovka „Připojení aplikace“ ukazuje název připojované aplikace, adresu, kam se vrací, a dvě zaškrtávátka – Číst data a model a Zapisovat data a model. Zaškrtnutá jsou podle toho, oč aplikace požádala; kterékoli z nich můžete odebrat. Model implementace dostane aplikace jen se zaškrtnutým čtením nebo zápisem dat. Není-li zaškrtnuté čtení ani zápis, připojení se odmítne – s jedinou výjimkou popsanou v oddílu Podrobnosti.
7.3. Odpojení
Připojené aplikace vidíte v dialogu Změna hesla na záložce „Připojené aplikace“, kde je také odpojíte. Odpojení platí okamžitě – aplikace přijde o přístup ještě než jí vyprší token.
7.4. Podrobnosti
Po povolení dostane aplikace přístupový token s platností jedné hodiny. Automaticky si ho obnovuje jen tehdy, požádala-li o trvalý přístup (rozsah „offline_access“) – pak dostane i obnovovací token s platností 30 dnů. Aplikace, která o trvalý přístup požádala, se připojí i bez zaškrtnutého čtení a zápisu a dostane jen znalosti frameworku – stejně jako osobní token bez oprávnění ke čtení a zápisu.
Stránka „api.aspx“ rozpozná požadavek MCP podle tokenu v hlavičce „Authorization“. Bez platného tokenu odpovídá stavovým kódem 401 a hlavičkou „WWW-Authenticate“, jak předepisuje protokol MCP – právě podle ní si aplikace najde, kam uživatele poslat přihlásit.
Registraci aplikace, stažení jejího popisu (metadata dokumentu) při vydávání tokenů a stažení popisu na obrazovce souhlasu před přihlášením instance omezuje dohromady na 60 požadavků za hodinu z jedné IP adresy. Po přihlášení má stažení popisu na obrazovce souhlasu vlastní limit 60 požadavků za hodinu, zvlášť pro každého uživatele. Před stažením popisu instance ověří, že se jeho adresa nepřekládá do vnitřní sítě serveru.
8. Název serveru a proměnné prostředí
Název MCP serveru v konfiguraci nástroje i název proměnné prostředí s tokenem se odvozují z adresy instance jediným pravidlem:
- název serveru je adresa bez protokolu, portu a „www“, čtená zleva doprava, s tečkami a lomítky nahrazenými pomlčkou,
- název proměnné je tentýž text velkými písmeny, s podtržítky místo pomlček a s předponou „MCP_TOKEN_“.
| Adresa instance | Název serveru | Název proměnné |
| https://identifikator.netgenium.online | identifikator-netgenium-online | MCP_TOKEN_IDENTIFIKATOR_NETGENIUM_ONLINE |
| https://portal.firma.cz/dev | portal-firma-cz-dev | MCP_TOKEN_PORTAL_FIRMA_CZ_DEV |
Každá instance tak má jméno jedinečné napříč vším, k čemu se připojujete, a odvodíte si ho z adresy i bez dialogu – dialog, utilita „ai-model“ i tato příručka používají totéž pravidlo. Partnerský MCP server má pevný název „netgenium-framework“; proměnná „MCP_TOKEN_NETGENIUM_FRAMEWORK“ z něj vzniká týmž přepisem.
9. Partnerský MCP server
Partneři, kteří na platformě staví zákaznické implementace (viz Partnerský program), připojují vedle serveru instance ještě druhý MCP server – partnerský MCP server společnosti NetGenium. Každý z nich dává agentovi něco jiného:
| Server | Co dává |
| MCP server instance („api.aspx“) | data a implementační model konkrétní instance, diagnostiku jejího výkonu a výběr znalostí frameworku odpovídající její verzi |
| Partnerský MCP server | agentní výbavu – pravidla platformy, skilly, subagenty, pomocné skripty a úplnou dokumentaci frameworku; žádná data ani model žádné instance |
9.1. Co partnerský server vydává
| Nástroj | Co vrací |
| search_framework_docs | odpovídající sekce z dokumentace, pravidel, skillů a subagentů najednou – výchozí vstup do znalostí |
| get_framework_doc, list_framework_docs | stránku dokumentace frameworku nebo její sekci, seznam všech stránek |
| get_rule, get_skill, get_agent | pravidlo, skill (soubor „SKILL.md“) nebo subagenta, celé nebo po sekcích |
| get_script | zdrojový kód pomocného skriptu v PowerShellu |
| list_resources | seznam pravidel, skillů, subagentů a skriptů s jejich velikostí |
Všechny nástroje jen čtou. Dokumentace a pravidla odpovídají poslední vydané verzi frameworku; obsah určený jen týmu NetGenia server nevydává.
9.2. Adresa a token
Server běží na adrese:
https://www.netgenium.com/api/mcp
Klient se prokazuje partnerským tokenem v hlavičce „Authorization“ („Bearer“). Tento token si v instanci nevygenerujete – vydává ho NetGenium na žádost zaslanou na support@netgenium.com. Na rozdíl od osobního MCP tokenu není vázaný na uživatele žádné instance, nemá tvar „ngt_...“ a nemá omezenou platnost: platí, dokud ho NetGenium nezruší. S tokenem se nastavuje jazyk vydávaných znalostí (čeština nebo angličtina) a jazyk názvů souborů implementačního modelu, na které se pravidla odkazují.
Token je přihlašovací údaj stejně jako osobní MCP token – uložte ho do proměnné prostředí „MCP_TOKEN_NETGENIUM_FRAMEWORK“ a v konfiguraci se na ni jen odkazujte:
setx MCP_TOKEN_NETGENIUM_FRAMEWORK "..."
9.3. Konfigurace AI nástroje
V Claude Code stojí oba servery vedle sebe v souboru „.mcp.json“ v kořeni repozitáře:
{
"mcpServers": {
"netgenium-framework": {
"type": "http",
"url": "https://www.netgenium.com/api/mcp",
"headers": {
"Authorization": "Bearer ${MCP_TOKEN_NETGENIUM_FRAMEWORK}"
}
},
"identifikator-netgenium-online": {
"type": "http",
"url": "https://identifikator.netgenium.online/api.aspx",
"headers": {
"Authorization": "Bearer ${MCP_TOKEN_IDENTIFIKATOR_NETGENIUM_ONLINE}"
}
}
}
}
V Codexu přibude do souboru „config.toml“ k záznamu instance další záznam:
[mcp_servers.netgenium-framework]
url = "https://www.netgenium.com/api/mcp"
bearer_token_env_var = "MCP_TOKEN_NETGENIUM_FRAMEWORK"
Stahujete-li implementační model utilitou „ai-model“, zapíše oba záznamy do „.mcp.json“ sama – server instance podle adresy, ze které model stahuje. Proměnné prostředí s oběma tokeny je ale nutné vytvořit ručně.
9.4. Oba servery vedle sebe
Servery spolu fungují bez konfliktu. AI nástroj rozlišuje nástroje podle názvu serveru, takže nástroje se stejným názvem z různých serverů si nepřekážejí. Stejně se jmenují jen nástroje znalostí frameworku („search_framework_docs“, „get_framework_doc“, „list_framework_docs“), které nabízí oba servery – každý ale s jiným rozsahem:
| Partnerský MCP server | MCP server instance | |
| Dokumentace frameworku | všechny stránky, poslední vydaná verze | výběr stránek, verze, na které instance běží |
| Pravidla | všechna kromě interních | jen výběr pravidel platformy přibalený ke znalostem |
| Skilly, subagenti, skripty | ano | ne |
| Data a implementační model | ne | ano, podle oprávnění tokenu |
Znalosti frameworku proto agent bere z partnerského serveru a server instance používá na data, implementační model a diagnostiku. Totéž oba servery agentovi sdělují v instrukcích, které mu posílají při připojení, takže správný server volí sám.
10. Řešení potíží
| Projev | Příčina a řešení |
| Server vrací chybu 404 | Nesprávná adresa – endpoint je stránka „api.aspx“ v kořeni instance, nikoli „/mcp“. |
| Server vrací chybu 401 | Token chybí, je neplatný nebo mu vypršela platnost. Zkontrolujte záložku „MCP token“ ve své instanci. |
| Server vrací chybu 403 | Token je platný, ale přístup jeho vlastníka byl odmítnut: nemá administrátorská práva, není v seznamu administrátorů s přístupem k MCP serveru, licenční klíč nepovoluje AI, jeho IP adresa není mezi povolenými v nastavení NET Genia nebo jsou vyčerpané licence. Důvod je uveden v odpovědi serveru a v protokolu „Auth“. |
| Nástroj nenabízí přihlášení nebo hlásí, že server přihlášení nepodporuje | Instance neběží v kořeni webu přes HTTPS, takže není autorizačním serverem. Použijte osobní token. |
| Nástroj hlásí, že metoda neexistuje | Token nemá odpovídající oprávnění – zapisovací nástroje a zápis modelu vyžadují „Zápis všech dat a modelu přes MCP server“, čtecí nástroje „Čtení všech dat a modelu přes MCP server“ a čtení modelu kterékoli z obou oprávnění. U připojení přihlášením nebylo zaškrtnuté příslušné oprávnění na obrazovce souhlasu – aplikaci odpojte a připojte znovu. |
| Nástroj server vůbec nevidí | Chybí proměnná prostředí s tokenem, uživatel server neschválil, nebo od změny konfigurace neproběhl restart nástroje. |
| Partnerský MCP server vrací chybu 401 | Partnerský token chybí nebo ho NetGenium zrušil. Zkontrolujte proměnnou prostředí s tokenem; osobní MCP token „ngt_...“ zde neplatí. |
| Místo odpovědi přichází stránka „please wait“ | Opakované požadavky s neplatným tokenem aktivovaly ochranu proti hádání tokenů a server na chvíli neobsluhuje žádné požadavky z dané IP adresy. Do téhož limitu se počítají i neúspěšné požadavky z téže IP adresy na výměnu autorizačního kódu nebo obnovovacího tokenu při připojení přes OAuth a chybně zadaná hesla stránek chráněných heslem z dialogu nastavení NET Genia (tiskové šablony, restart, AI model), zadává-li je z téže IP adresy nepřihlášený návštěvník. Je potřeba opravit token a chvíli počkat; zkoušení dalších hodnot situaci jen prodlouží. |
Na nastavené připojení navazuje agentní vývoj – práce s AI agentem, který zná framework i konkrétní implementaci a dokáže v ní cíleně pracovat.