Nastavení MCP serveru

Připojení AI nástroje k MCP serveru

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 Code, 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.

Nastavení má tři kroky: zjistíte adresu serveru, vygenerujete si osobní MCP token a obojí zadáte do svého AI nástroje.

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	http://server/netgenium/api.aspx
Instance v kořeni webu	https://netgenium.firma.cz/api.aspx
NET Genium Online	https://identifikator.netgenium.online/api.aspx

Stránka 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 – informační stránku rozhraní API vydá jedině přihlášenému administrátorovi, který si tak v prohlížeči ověří, že instance na dané adrese odpovídá.

Adresou serveru není „/mcp“. Ta patří samostatnému projektu API v zákaznickém řešení; na samotné instanci NET Genia neexistuje.

2. Osobní MCP token

Klient se serveru prokazuje osobním MCP tokenem ve tvaru „ngt_…“. Token si vygeneruje každý uživatel sám:

1. Přihlaste se do své instance a v navigační oblasti v sekci Moje nastavení otevřete odkaz Změnit heslo.
2. Přejděte na záložku MCP token a klikněte na Vygenerovat token.
3. Zapněte oprávnění Čtení všech dat přes MCP server – a Zápis všech dat přes MCP server jen tehdy, má-li asistent data i měnit.
4. Token si zkopírujte. V čitelné podobě se zobrazí pouze jednou, při vygenerování; na serveru se ukládá jen jeho otisk.

Platnost tokenu je 90 dnů a jedním kliknutím ho prodloužíte. Každý uživatel má nejvýše jeden token a může ho kdykoli smazat – tím přístup okamžitě končí.

Oprávnění ke čtení a zápisu dat lze zapnout jen uživateli s administrátorskými právy. Znalosti frameworku a model implementace se nezapínají zaškrtnutím – dostane je každý token, jehož vlastník má administrátorská práva. Podrobnosti o oprávněních tokenu popisuje text Integrovaný MCP server.

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í, například „NETGENIUM_MCP_TOKEN“, 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:

setx NETGENIUM_MCP_TOKEN "ngt_..."

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.

4. Konfigurace AI nástroje

Claude Code

V kořeni projektu vytvořte soubor „.mcp.json“ – adresu nahraďte adresou své instance:

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

Zápis „${NETGENIUM_MCP_TOKEN}“ se při načtení souboru nahradí hodnotou proměnné prostředí, takže samotný token v souboru není. Název serveru („netgenium“) je libovolný; pracujete-li s více instancemi, přidejte pro každou samostatný záznam s vlastní adresou a vlastní proměnnou.

Server z projektového souboru musí každý uživatel při prvním spuštění schválit – Claude Code se na to sám zeptá.

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ř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“,
• 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 přes MCP server nechte vypnuté, dokud agent opravdu nemá data 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ů.

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,
• hlavičku „Authorization“ s hodnotou „Bearer ngt_…“.

Server podporuje i dotaz „OPTIONS“ (CORS preflight), takže se k němu připojí i nástroje běžící v prohlížeči.

Připojení bez tokenu (OAuth)

Nástroje, které si hlavičku „Authorization“ nastavit nedovolují – claude.ai a další prostředí Clauda – se k instanci připojí přihlášením, ne tokenem. Zadáte v nich pouze adresu serveru; nástroj si zbytek zjistí sám, otevře přihlašovací obrazovku vaší instance a po přihlášení se zeptá, co smí.

Na obrazovce „Připojení aplikace“ vidíte název připojované aplikace, adresu, kam se vrací, a dvě zaškrtávátka – číst data a zapisovat data. Zaškrtnutá jsou podle toho, oč aplikace požádala; kterékoli z nich můžete odebrat. Po povolení dostane aplikace přístupový token s platností jedné hodiny, který si sama automaticky obnovuje.

Přístup takto získá jen uživatel s administrátorskými právy – stejně jako u osobního tokenu.

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.

Tento způsob připojení je dostupný jen tam, kde 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.

Ř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, nemá zapnuté čtení ani zápis, jeho vlastník ztratil administrátorská práva, jeho IP adresa není mezi povolenými v nastavení NET Genia, nebo jsou vyčerpané licence. Zkontrolujte záložku „MCP token“ ve své instanci.
Nástroj hlásí, že metoda neexistuje	Token nemá odpovídající oprávnění – zapisovací nástroje vyžadují „Zápis všech dat přes MCP server“, čtecí „Čtení všech dat přes MCP server“.
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.
Odpovědi se náhle zdržují	Opakované požadavky s neplatným tokenem aktivovaly ochranu proti hádání tokenů. Opravte token a chvíli počkejte; zkoušení dalších hodnot situaci jen prodlouží.

Každý požadavek přes MCP server se přihlašuje jako vlastník tokenu, takže podléhá povoleným IP adresám i licencím stejně jako běžné přihlášení.

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.