Tato část je pro správce, kteří chtějí provozovat CDESK MCP server na vlastním serveru tak, aby se všichni ve firmě připojovali na jednu adresu a přihlašovali se svým vlastním účtem v CDESK.
Předpokládá se základní zkušenost s provozem webového serveru za HTTPS. Samotný CDESK MCP server je jediný malý program a kroky níže jsme se snažili udržet co nejstručnější – vaše vlastní HTTPS proxy, DNS a správa služeb zůstávají ve vašich rukou, protože své prostředí znáte mnohem lépe než my.
Architektura řešení
Jeden CDESK MCP server obsluhuje množství lidí. Nemá žádnou vlastní databázi a neukládá nic na disk – žádný seznam uživatelů, žádná hesla, žádné údaje z CDESK. Každý se přihlásí svým vlastním účtem v CDESK přes přihlašovací stránku a od té chvíle drží jeho AI aplikace zašifrovanou relaci, kterou CDESK MCP při každém požadavku rozbalí.
Instalace serveru
CDESK MCP žije v repozitáři na GitHubu: https://github.com/Inovalogic-s-r-o/CDESK-MCP. Naklonujte si ho na server, nebo si ho ze stejné stránky stáhněte jako ZIP, pokud Git použít nechcete – s Gitem jsou pozdější aktualizace jediný git pull.
Projekt obsahuje připravené kontejnerové sestavení – obraz python:3.12-slim, závislosti přes uv sync –frozen –no-dev a vstupní bod python -m cdesk_mcp – takže celá instalace jsou čtyři příkazy:
git clone https://github.com/Inovalogic-s-r-o/CDESK-MCP cdesk-mcp
cd cdesk-mcp
cp .env.production.example .env.production # potom ho vyplňte (další krok)
docker compose up --build -dServer se tím zpřístupní jen na 127.0.0.1:8000 a bude se automaticky restartovat. Port 8000 komunikuje přes čisté HTTP – nikdy ho nevystavujte přímo. Před něj patří vaše HTTPS proxy (Postavte před server HTTPS).
Vyplnění nastavení
Podstatná jsou čtyři nastavení. Vše ostatní má rozumnou výchozí hodnotu; úplný seznam najdete v kapitole Přehled konfiguračních nastavení.
- CDESK_TRANSPORT=http – vybírá sdílený server pro více uživatelů. Druhá možnost, stdio, je verze pro jednoho uživatele, kterou si AI aplikace spouští na vlastním počítači.
- CDESK_PUBLIC_URL=https://mcp.example.com – veřejná adresa CDESK MCP serveru, který provozujete: ta, na které ho poskytuje vaše HTTPS proxy, a ta, na kterou se připojují AI aplikace vašich uživatelů. Není to adresa vašeho CDESK. Bez lomítka na konci, protože se k ní připojuje CDESK_MCP_PATH a spolu tvoří adresu, kterou si uživatelé vkládají do pole pro konektor ve své AI aplikaci. Server tuto adresu rozesílá AI aplikacím a vtiskne ji do každé relace, takže pokud neodpovídá tomu, co vaše proxy skutečně poskytuje, přihlášení se nikdy nedokončí.
- CDESK_BASE_URL=https://cdesk.example.com – váš vlastní CDESK, tak, jak byste ho napsali do prohlížeče; zbytek cesty se doplní za vás. Povinné. Uživatelé si adresu svého CDESK při přihlašování běžně zadávají sami, takže tato hodnota se uplatní tehdy, když byste to raději nechtěli: s CDESK_ALLOW_CUSTOM_BASE_URL=false je to jediná adresa, kterou tento server přijme, a cokoli jiného odmítne. Při více pevných adresách použijte raději CDESK_BASE_URLS (Přehled konfiguračních nastavení).
- CDESK_ENCRYPTION_KEY – zamyká a odemyká relace. Protože server nic neukládá, každá relace putuje jako zašifrovaný řetězec, který drží AI aplikace uživatele. Držte ho v tajnosti, neměňte ho a dejte tentýž každé kopii serveru – právě díky tomu relace přežijí restart a fungují napříč více kopiemi. Bez něj se server i tak spustí, s dočasným klíčem, zapíše varování a při dalším restartu všechny odhlásí.
Adresa, kterou si lidé vkládají do AI aplikace, je CDESK_PUBLIC_URL následovaná hodnotou CDESK_MCP_PATH, což je /mcp, pokud to nezměníte. Pokud CDESK_MCP_PATH nastavíte na /, používají samotnou CDESK_PUBLIC_URL.
Šifrovací klíč vygenerujte jednou, držte ho v tajnosti a neměňte ho:
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"Pokud ho nenastavíte, server si při každém startu vymyslí nový, zapíše varování a každý restart všechny odhlásí. Pokud ho později změníte, stane se totéž jednou – zacházejte proto se změnou klíče jako s plánovaným hromadným odhlášením.
Nenastavujte CDESK_LOGIN, CDESK_PASSWORD, CDESK_CLIENT_ID ani CDESK_CLIENT_SECRET. Sdílený server se nikdy nepřihlašuje z vlastního nastavení; každé spojení vzniká z relace přihlášeného uživatele. Tyto čtyři zde nedělají nic.
Když se server nespustí
Server odmítne nastartovat ve dvou případech a toto je ta jedna věc, kterou je dobré vědět dopředu: důvod zapíše do logu a potom se čistě ukončí. Návratový kód 0 vypadá jako úspěch, takže dohled, který sleduje jen selhání, neřekne nic a restart: unless-stopped ho jednoduše bude restartovat dokola. Čtěte log, ne návratový kód.
Ty dva případy jsou:
- Chybí CDESK_BASE_URL nebo CDESK_PUBLIC_URL.
- Některá z nich je obyčejné http:// místo https:// (kromě localhostu). Přes čisté HTTP by hesla do CDESK a relace putovaly nezašifrované, takže to server neudělá.
Nastavení HTTPS proxy
Nasměrujte svou HTTPS proxy na port 8000. Podstatné jsou čtyři věci:
1. Ukončete HTTPS na adrese CDESK_PUBLIC_URL a vše na ní přeposílejte na port 8000.
2. Nebufferujte. Spojení je dlouho běžící proud dat a buffering ho rozbije.
3. Zachovejte hlavičku Host, kterou vaše proxy dostává, nebo tu, kterou posílá, přidejte do CDESK_ALLOWED_HOSTS.
4. Posílejte IP adresu návštěvníka v X-Forwarded-For nebo CF-Connecting-IP a nastavte CDESK_TRUST_PROXY=1. Limit je 10 pokusů za 60 sekund na IP adresu; bez této hlavičky považuje všechny za jednoho návštěvníka. Limit je zároveň na jednu běžící kopii serveru, takže při více kopiích se násobí.
Provoz na podcestě – tedy CDESK_PUBLIC_URL ve tvaru https://example.com/cdesk-mcp – potřebuje ještě jednu věc: přeposílat i /.well-known/* z kořene domény. AI aplikace to hledají tam, bez ohledu na to, na jaké cestě sedí samotný server. Pokud je CDESK_PUBLIC_URL obyčejná adresa bez cesty, není to třeba.
Ověření funkčnosti serveru
Dvě rychlé kontroly z příkazového řádku:
curl -s https://<vasa-adresa>/.well-known/oauth-authorization-server | jq .
curl -si https://<vasa-adresa>/mcp | head -1 # očekávejte 401(Druhá počítá s výchozím /mcp – pokud jste ho změnili, použijte svou hodnotu CDESK_MCP_PATH.)
Odpověď 401 u druhé kontroly je správná: dokazuje, že server běží a vyžaduje přihlášení.
Potom to udělejte pořádně: přidejte stejnou adresu do AI aplikace a přihlaste se jako testovací uživatel CDESK. Tím najednou prověříte celý řetězec – informace, podle kterých si vás AI aplikace najde, přihlašovací stránku, výměnu relace i první skutečný požadavek do CDESK.
Připojení uživatelů
Na serveru není žádné nastavování pro jednotlivé uživatele. Každý se přihlásí svým vlastním účtem v CDESK při prvním připojení své AI aplikace.
Rozdejte jeden řádek – vaši adresu, tedy CDESK_PUBLIC_URL následovanou hodnotou CDESK_MCP_PATH – a pošlete lidem odkaz na část dokumentace Připojení ke cloudu CDESK MCP, která je provede zbytkem obrazovku po obrazovce.
Běžný provoz a údržba
Logy jdou jen na chybový výstup a nikdy neobsahují hesla, přihlašovací údaje ani údaje z CDESK. Při zdravém startu uvidíte něco takového:
cdesk-mcp starting (transport=http)
cdesk-mcp listening on http://0.0.0.0:8000/mcp (clients connect to: https://…/mcp) - OAuth issuer https://…Kontroly dostupnosti: adresa /health neexistuje. Použijte /.well-known/oauth-authorization-server, která odpovídá 200 bez přihlášení, nebo cestu /mcp, kde odpověď 401 dokazuje, že server žije.
Relace trvají 8 hodin a obnovují se samy; samotná obnova platí 30 dní. Kdo byl pryč déle, ten se jednoduše přihlásí znovu.
Změna šifrovacího klíče všechny odhlásí. Naplánujte si ji.
Odpověď 200 ve vašich lozích není důkazem úspěchu. CDESK vrací některé chyby v těle odpovědi se stavovým kódem 200 – například konflikt při souběžné úpravě záznamu, neúspěšnou kontrolu údajů nebo vypnutý modul.
Přehled konfiguračních nastavení
Vycházejte z .env.production.example.
| Nastavení | Povinné | Co dělá |
|---|---|---|
CDESK_TRANSPORT=http | ano | Vybírá sdílený server pro více uživatelů |
CDESK_PUBLIC_URL | ano | HTTPS adresa, na kterou se lidé dostanou. Používá se při přesměrováních během přihlášení a k identifikaci serveru. Bez lomítka na konci |
CDESK_BASE_URL | ano | Adresa vašeho CDESK, jen hostitel. Slouží jako záloha pro relace vytvořené ještě předtím, než si lidé mohli vybírat vlastní server, a – když je CDESK_ALLOW_CUSTOM_BASE_URL nastaveno na false a CDESK_BASE_URLS je prázdné – jako jediná přijímaná adresa. Na přihlašovací stránce není předvyplněná |
CDESK_ENCRYPTION_KEY | důrazně doporučeno | Chrání relace. Neměnný → relace přežijí restart a fungují napříč více kopiemi serveru. Nenastavený → nový klíč při každém restartu, takže jsou všichni odhlášeni |
CDESK_MCP_PATH | ne, výchozí /mcp | Cesta, na kterou se lidé připojují, připojená k CDESK_PUBLIC_URL. Nastavte na /, pokud ji chcete poskytovat na samotné adrese. Změna přesměruje každou AI aplikaci jinam a zneplatní existující relace |
CDESK_HTTP_HOST / CDESK_HTTP_PORT | ne | Kde server naslouchá. Kontejner nastavuje 0.0.0.0 a 8000; mimo kontejner je výchozí 127.0.0.1, dostupné jen z toho stroje |
CDESK_ALLOW_CUSTOM_BASE_URL | ne, výchozí true | Umožňuje lidem zadat při přihlášení libovolnou adresu CDESK. Neexistuje žádný seznam povolených adres ani ochrana před interními adresami – server se pokusí přihlásit vůči čemukoli, co bylo zadáno. Nastavte na false, pokud chcete přijímat jen adresy z CDESK_BASE_URLS, případně z CDESK_BASE_URL, pokud jste ho nevyplnili |
CDESK_BASE_URLS | ne | Dvojice Popis=URL oddělené čárkami, tedy CDESK servery, které znáte. Přijímány jsou vždy a při hodnotě false výše tvoří seznam povolených. Adresy se porovnávají shovívavě – chybějící https://, lomítko na konci či jiná velká písmena stále sedí. Popisy se nikdy nezobrazují: přihlašovací stránka má volné textové pole, ne rozbalovací seznam, takže tímto vzniká seznam povolených adres, ne nabídka |
CDESK_AZURE_LOGIN_ENABLED | ne | Povoluje tlačítko přihlášení přes Microsoft. Zobrazí se pak jen u CDESK, který přihlášení přes Microsoft skutečně nabízí, což se ověří při ověření adresy uživatelem. Pro jednotlivé CDESK servery není třeba nic nastavovat; podrobnosti se zjišťují automaticky |
CDESK_ALLOWED_HOSTS / CDESK_ALLOWED_ORIGINS | ne | Další názvy, které uvádí vaše proxy, oddělené čárkami |
CDESK_TRUST_PROXY=1 | doporučeno za proxy | Bere IP adresu návštěvníka z CF-Connecting-IP / X-Forwarded-For. Dají se zfalšovat, takže to zapněte jen tehdy, když je nastavuje vaše vlastní proxy |
CDESK_TIMEZONE | ne | Například Europe/Bratislava. Data bez časové zóny čte jako místní čas systému CDESK |
CDESK_EVIDENCE_THRESHOLD | ne, výchozí 3 | Kolik samostatných záznamů asistent potřebuje, než něco potvrdí jako trend |
CDESK_LOG_LEVEL / CDESK_TIMEOUT_SECONDS | ne | INFO / 30 |
Ochrana před voláními z neočekávaných adres je zapnutá ve výchozím stavu. Server přijímá požadavky, které uvádějí jeho vlastní veřejnou adresu, adresu, na které naslouchá, 127.0.0.1 a localhost na libovolném portu, a jako původ požadavku svou veřejnou adresu, https://claude.ai nebo https://claude.com. Pokud vaše proxy uvádí něco jiného, přidejte to do CDESK_ALLOWED_HOSTS nebo CDESK_ALLOWED_ORIGINS.
Průběh přihlášení uživatele
1. AI aplikace uživatele se zaregistruje u vašeho serveru a požádá o přihlášení.
2. Uživatel se dostane na přihlašovací stránku, která má dva kroky. Nejprve se ptá na jeho vlastní adresu CDESK ve volném textovém poli, které je na začátku prázdné – žádný rozbalovací seznam, žádná výchozí hodnota a prázdná adresa se odmítne. S CDESK_ALLOW_CUSTOM_BASE_URL=false musí odpovídat některé z vašich adres a odmítnutí vyjmenuje ty, které jsou přijímány.
3. Uživatel klikne na Verify server a váš server ověří, co se na té adrese nachází. Následně se přímo na místě odkryjí pole pro jméno a heslo a s nimi i tlačítko Microsoftu – ale jen u CDESK, který přihlášení přes Microsoft skutečně nabízí, takže lidem se nikdy nezobrazí tlačítko, které nemůže fungovat. Pokud samotné ověření selže, přihlášení není zablokované: stránka to napíše a nechá je pokračovat, jen bez tlačítka Microsoftu.
4. Jméno a heslo se ověří jediným voláním na CDESK server, který zadali. Účet se zapnutým 2FA to nedokáže dokončit a bude odmítnut; nesprávné heslo se odmítne jako nesprávné heslo.
5. Heslo se hned po tomto jednom volání zahodí. Dále pokračuje už jen relace v CDESK, zašifrovaná uvnitř toho, co drží AI aplikace.
6. Zvolená adresa CDESK se zapamatuje jako součást dané relace, takže každý další požadavek, obnova i odhlášení míří na správný server. Lidé z různých CDESK serverů mohou současně sdílet jednu instalaci.