EN

Nastavení MCP serveru

Hlavní stránka / Dokumentace / Příručka administrátora /

Nastavení MCP serveru

EN

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

Dva způsoby připojení

Nástroj se k serveru připojí jedním ze dvou způsobů. Oba vedou na tentýž server, dávají tytéž nástroje a v obou případech se každý požadavek přihlašuje jako konkrétní uživatel instance:

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 potřebujete znát adresu serveru.

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

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 – právě podle ní si nástroj připojovaný přihlášením najde, kam uživatele poslat. 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.

Připojení osobním tokenem

Nastavení má tři kroky: vygenerujete si osobní MCP token, uložíte ho do proměnné prostředí a spolu s adresou serveru ho zadáte do konfigurace svého AI nástroje.

1. 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. Token se hned zobrazí, ale zatím nevznikl.
  3. 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.
  4. Klikněte na Uložit. Teprve tím token i jeho oprávnění vzniknou.
  5. Token si zkopírujte, dokud je dialog otevřený. V čitelné podobě se zobrazí pouze jednou; na serveru se ukládá jen jeho otisk.

01-mcp-token.png

Na téže záložce najdete i hotové hodnoty pro svou instanci – adresu serveru, příkaz, kterým token uložíte do proměnné prostředí, a text, kterým si připojení necháte nastavit svým AI nástrojem. Oba následující kroky tedy nemusíte skládat ručně; každou hodnotu vedle sebe zkopírujete jedním kliknutím.

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: první jeho čtení, druhé jeho změny. Token bez obou zaškrtnutí zůstane u znalostí frameworku – ty dostane každý token, jehož vlastník má administrátorská práva. Podrobnosti o oprávněních tokenu popisuje text Integrovaný MCP server.

2. 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_..."

Skládat ho ručně nemusíte – celý příkaz i se svým tokenem najdete na záložce „MCP token“ v poli Proměnná prostředí a ikonou vedle něj si ho zkopírujete do schránky. Skutečný token v něm je jen hned po vygenerování; později se místo něj zobrazuje „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.

3. Konfigurace AI nástroje

Claude Code

Claude Code čte konfiguraci MCP serverů ze souboru „.mcp.json“ v kořeni projektu. Psát ho ale nemusíte. Na záložce „MCP token“ je v poli Prompt pro nastavení hotový text – ikonou vedle něj si ho zkopírujete, vložíte do Claude Code spuštěného v kořeni projektu a ten soubor založí 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. Týž text funguje i v ostatních AI nástrojích – je psaný nezávisle na tom, kam si který nástroj konfiguraci ukládá.

Hotová konfigurace pak v souboru vypadá takto:

{
 "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á.

Codex

Codex si konfiguraci MCP serverů drží v souboru „config.toml“ v adresáři „.codex“ ve vašem domovském adresáři. Psát ho také nemusíte – použijte tentýž Prompt pro nastavení ze záložky „MCP token“; 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.

Hotový záznam pak v souboru vypadá takto:

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

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“. Název serveru („netgenium“) je opět libovolný a pro každou další instanci přidáte další záznam.

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“; 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ů.

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

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í přihlášením

Nástroje, které si hlavičku „Authorization“ nastavit nedovolují – Claude a ChatGPT ve webové i desktopové aplikaci – se k instanci připojí přihlášením, ne tokenem. Instanci v nich přidáte jako vlastní konektor a zadáte 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. Znalosti frameworku a model implementace dostane bez zaškrtávání – stejně jako u osobního tokenu.

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.

Přihlášením se umí připojit i vývojářské nástroje: v Codexu přidáte server příkazem „codex mcp add netgenium --url https://identifikator.netgenium.online/api.aspx“ a přihlásíte se příkazem „codex mcp login netgenium“, v Claude Code přidáte server příkazem „claude mcp add --transport http netgenium https://identifikator.netgenium.online/api.aspx“ a přihlášení spustíte příkazem „/mcp“ v otevřené konverzaci. Osobní token je v nich ale jednodušší volbou – funguje i u instance v podadresáři a nevyžaduje interaktivní přihlášení.

Ř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.
Server vrací chybu 403 Vlastník tokenu nemá administrátorská práva, nebo je v Nastavení NET Genia na záložce „Oprávnění“ vyplněný seznam uživatelů s přístupem k MCP serveru a on v něm není. Požádejte administrátora instance, aby vás do seznamu doplnil.
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 a čtení modelu „Čtení všech dat a modelu přes MCP server“. 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.
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 konkrétní uživatel – vlastník tokenu, nebo ten, kdo aplikaci přihlášením povolil – 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.