Táto časť je pre správcov, ktorí chcú prevádzkovať CDESK MCP server na vlastnom serveri tak, aby sa všetci vo firme pripájali na jednu adresu a prihlasovali sa svojím vlastným kontom v CDESK.
Predpokladá sa základná skúsenosť s prevádzkou webového servera za HTTPS. Samotný CDESK MCP server je jediný malý program a kroky nižšie sme sa snažili udržať čo najstručnejšie – vaša vlastná HTTPS proxy, DNS a správa služieb zostávajú vo vašich rukách, keďže svoje prostredie poznáte oveľa lepšie než my.
Architektúra riešenia
Jeden CDESK MCP server obsluhuje množstvo ľudí. Nemá žiadnu vlastnú databázu a neukladá nič na disk – žiadny zoznam používateľov, žiadne heslá, žiadne údaje z CDESK. Každý sa prihlási svojím vlastným kontom v CDESK cez prihlasovaciu stránku a odvtedy drží jeho AI aplikácia zašifrované sedenie, ktoré CDESK MCP pri každej požiadavke rozbalí.
Inštalácia servera
CDESK MCP žije v repozitári na GitHube: https://github.com/Inovalogic-s-r-o/CDESK-MCP. Naklonujte si ho na server, alebo si ho z tej istej stránky stiahnite ako ZIP, ak Git použiť nechcete – s Gitom sú neskoršie aktualizácie jediný git pull.
Projekt obsahuje pripravenú kontajnerovú zostavu – obraz python:3.12-slim, závislosti cez uv sync –frozen –no-dev a vstupný bod python -m cdesk_mcp – takže celá inštalácia sú štyri prí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 (ďalší krok)
docker compose up --build -dServer sa tým sprístupní len na 127.0.0.1:8000 a bude sa automaticky reštartovať. Port 8000 komunikuje cez čisté HTTP – nikdy ho nevystavujte priamo. Pred neho patrí vaša HTTPS proxy (Postavte pred server HTTPS).
Vyplnenie nastavení
Podstatné sú štyri nastavenia. Všetko ostatné má rozumnú predvolenú hodnotu; úplný zoznam nájdete v kapitole Prehľad konfiguračných nastavení.
- CDESK_TRANSPORT=http – vyberá zdieľaný server pre viacerých používateľov. Druhá možnosť, stdio, je verzia pre jedného používateľa, ktorú si AI aplikácia spúšťa na vlastnom počítači.
- CDESK_PUBLIC_URL=https://mcp.example.com – verejná adresa CDESK MCP servera, ktorý prevádzkujete: tá, na ktorej ho podáva vaša HTTPS proxy, a tá, na ktorú sa pripájajú AI aplikácie vašich používateľov. Nie je to adresa vášho CDESK. Bez lomky na konci, pretože sa k nej pripája CDESK_MCP_PATH a spolu tvoria adresu, ktorú si používatelia vkladajú do poľa pre konektor vo svojej AI aplikácii. Server túto adresu rozposiela AI aplikáciám a vtláča ju do každého sedenia, takže ak nezodpovedá tomu, čo vaša proxy naozaj podáva, prihlásenie sa nikdy nedokončí.
- CDESK_BASE_URL=https://cdesk.example.com – váš vlastný CDESK, tak, ako by ste ho napísali do prehliadača; zvyšok cesty sa doplní za vás. Povinné. Používatelia si adresu svojho CDESK pri prihlasovaní bežne zadávajú sami, takže táto hodnota sa uplatní vtedy, keď by ste to radšej nechceli: s CDESK_ALLOW_CUSTOM_BASE_URL=false je to jediná adresa, ktorú tento server prijme, a čokoľvek iné odmietne. Pri viacerých pevných adresách použite radšej CDESK_BASE_URLS (Prehľad konfiguračných nastavení).
- CDESK_ENCRYPTION_KEY – zamyká a odomyká sedenia. Keďže server nič neukladá, každé sedenie putuje ako zašifrovaný reťazec, ktorý drží AI aplikácia používateľa. Držte ho v tajnosti, nemeňte ho a dajte ten istý každej kópii servera – práve vďaka tomu sedenia prežijú reštart a fungujú naprieč viacerými kópiami. Bez neho sa server aj tak spustí, s dočasným kľúčom, zapíše varovanie a pri ďalšom reštarte všetkých odhlási.
Adresa, ktorú si ľudia vkladajú do AI aplikácie, je CDESK_PUBLIC_URL nasledovaná hodnotou CDESK_MCP_PATH, čo je /mcp, pokiaľ to nezmeníte. Ak CDESK_MCP_PATH nastavíte na /, používajú samotnú CDESK_PUBLIC_URL.
Šifrovací kľúč vygenerujte raz, držte ho v tajnosti a nemeňte ho:
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"Ak ho nenastavíte, server si pri každom štarte vymyslí nový, zapíše varovanie a každý reštart všetkých odhlási. Ak ho neskôr zmeníte, stane sa to isté raz – narábajte preto so zmenou kľúča ako s plánovaným hromadným odhlásením.
Nenastavujte CDESK_LOGIN, CDESK_PASSWORD, CDESK_CLIENT_ID ani CDESK_CLIENT_SECRET. Zdieľaný server sa nikdy neprihlasuje z vlastných nastavení; každé spojenie vzniká zo sedenia prihláseného používateľa. Tieto štyri tu nerobia nič.
Keď sa server nespustí
Server odmietne naštartovať v dvoch prípadoch a toto je tá jedna vec, ktorú je dobré vedieť dopredu: dôvod zapíše do logu a potom sa ukončí čisto. Návratový kód 0 vyzerá ako úspech, takže dohľad, ktorý sleduje len zlyhania, nepovie nič a restart: unless-stopped ho jednoducho bude reštartovať dokola. Čítajte log, nie návratový kód.
Tie dva prípady sú:
- Chýba CDESK_BASE_URL alebo CDESK_PUBLIC_URL.
- Niektorá z nich je obyčajné http:// namiesto https:// (okrem localhostu). Cez čisté HTTP by heslá do CDESK a sedenia putovali nezašifrované, takže to server neurobí.
Nastavenie HTTPS proxy
Nasmerujte svoju HTTPS proxy na port 8000. Podstatné sú štyri veci:
1. Ukončite HTTPS na adrese CDESK_PUBLIC_URL a všetko na nej preposielajte na port 8000.
2. Nebufferujte. Spojenie je dlho bežiaci prúd dát a buffering ho rozbije.
3. Zachovajte hlavičku Host, ktorú vaša proxy dostáva, alebo tú, ktorú posiela, pridajte do CDESK_ALLOWED_HOSTS.
4. Posielajte IP adresu návštevníka v X-Forwarded-For alebo CF-Connecting-IP a nastavte CDESK_TRUST_PROXY=1. Limit je 10 pokusov za 60 sekúnd na IP adresu; bez tejto hlavičky považuje všetkých za jedného návštevníka. Limit je zároveň na jednu bežiacu kópiu servera, takže pri viacerých kópiách sa násobí.
Prevádzka na podceste – teda CDESK_PUBLIC_URL v tvare https://example.com/cdesk-mcp – potrebuje ešte jednu vec: preposielať aj /.well-known/* z koreňa domény. AI aplikácie to hľadajú tam, bez ohľadu na to, na akej ceste sedí samotný server. Ak je CDESK_PUBLIC_URL obyčajná adresa bez cesty, netreba to.
Overenie funkčnosti servera
Dve rýchle kontroly z príkazového riadka:
curl -s https://<vasa-adresa>/.well-known/oauth-authorization-server | jq .
curl -si https://<vasa-adresa>/mcp | head -1 # očakávajte 401(Druhá počíta s predvoleným /mcp – ak ste ho zmenili, použite svoju hodnotu CDESK_MCP_PATH.)
Odpoveď 401 pri druhej kontrole je správna: dokazuje, že server beží a pýta si prihlásenie.
Potom to urobte poriadne: pridajte tú istú adresu do AI aplikácie a prihláste sa ako testovací používateľ CDESK. Tým naraz preveríte celý reťazec – informácie, podľa ktorých si vás AI aplikácia nájde, prihlasovaciu stránku, výmenu sedenia aj prvú skutočnú požiadavku do CDESK.
Pripojenie používateľov
Na serveri nie je žiadne nastavovanie pre jednotlivých používateľov. Každý sa prihlási svojím vlastným kontom v CDESK pri prvom pripojení svojej AI aplikácie.
Rozdajte jeden riadok – vašu adresu, teda CDESK_PUBLIC_URL nasledovanú hodnotou CDESK_MCP_PATH – a pošlite ľuďom odkaz na časť dokumentácie Pripojenie do cloudu CDESK MCP, ktorá ich prevedie zvyškom obrazovku po obrazovke.
Bežná prevádzka a údržba
Logy idú len na chybový výstup a nikdy neobsahujú heslá, prihlasovacie údaje ani údaje z CDESK. Pri zdravom štarte uvidíte niečo takéto:
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žite /.well-known/oauth-authorization-server, ktorá odpovedá 200 bez prihlásenia, alebo cestu /mcp, kde odpoveď 401 dokazuje, že server žije.
Sedenia trvajú 8 hodín a obnovujú sa samy; samotná obnova platí 30 dní. Kto bol preč dlhšie, ten sa jednoducho prihlási znova.
Zmena šifrovacieho kľúča všetkých odhlási. Naplánujte si ju.
Odpoveď 200 vo vašich logoch nie je dôkazom úspechu. CDESK vracia niektoré chyby v tele odpovede so stavovým kódom 200 – napríklad konflikt pri súbežnej úprave záznamu, zlyhanú kontrolu údajov alebo vypnutý modul.
Prehľad konfiguračných nastavení
Vychádzajte z .env.production.example.
| Nastavenie | Povinné | Čo robí |
|---|---|---|
CDESK_TRANSPORT=http | áno | Vyberá zdieľaný server pre viacerých používateľov |
CDESK_PUBLIC_URL | áno | HTTPS adresa, na ktorú sa ľudia dostanú. Používa sa pri presmerovaniach počas prihlásenia a na identifikáciu servera. Bez lomky na konci |
CDESK_BASE_URL | áno | Adresa vášho CDESK, len hostiteľ. Slúži ako záloha pre sedenia vytvorené ešte predtým, než si ľudia mohli vyberať vlastný server, a – keď je CDESK_ALLOW_CUSTOM_BASE_URL nastavené na false a CDESK_BASE_URLS je prázdne – ako jediná prijímaná adresa. Na prihlasovacej stránke nie je predvyplnená |
CDESK_ENCRYPTION_KEY | dôrazne odporúčané | Chráni sedenia. Nemenný → sedenia prežijú reštart a fungujú naprieč viacerými kópiami servera. Nenastavený → nový kľúč pri každom reštarte, takže sú všetci odhlásení |
CDESK_MCP_PATH | nie, predvolene /mcp | Cesta, na ktorú sa ľudia pripájajú, pripojená k CDESK_PUBLIC_URL. Nastavte na /, ak ju chcete podávať na samotnej adrese. Zmena presmeruje každú AI aplikáciu inam a zneplatní existujúce sedenia |
CDESK_HTTP_HOST / CDESK_HTTP_PORT | nie | Kde server počúva. Kontajner nastavuje 0.0.0.0 a 8000; mimo kontajnera je predvolené 127.0.0.1, dostupné len z toho stroja |
CDESK_ALLOW_CUSTOM_BASE_URL | nie, predvolene true | Umožňuje ľuďom zadať pri prihlásení ľubovoľnú adresu CDESK. Neexistuje žiadny zoznam povolených adries ani ochrana pred internými adresami – server sa pokúsi prihlásiť voči čomukoľvek, čo bolo zadané. Nastavte na false, ak chcete prijímať len adresy z CDESK_BASE_URLS, prípadne z CDESK_BASE_URL, ak ste ho nevyplnili |
CDESK_BASE_URLS | nie | Dvojice Popis=URL oddelené čiarkami, teda CDESK servery, ktoré poznáte. Prijímané sú vždy a pri hodnote false vyššie tvoria zoznam povolených. Adresy sa porovnávajú zhovievavo – chýbajúce https://, lomka na konci či iné veľké písmená stále sedia. Popisy sa nikdy nezobrazujú: prihlasovacia stránka má voľné textové pole, nie rozbaľovací zoznam, takže týmto vzniká zoznam povolených adries, nie ponuka |
CDESK_AZURE_LOGIN_ENABLED | nie | Povoľuje tlačidlo prihlásenia cez Microsoft. Zobrazí sa potom len pri CDESK, ktorý prihlásenie cez Microsoft naozaj ponúka, čo sa overí pri overení adresy používateľom. Pre jednotlivé CDESK servery netreba nič nastavovať; podrobnosti sa zisťujú automaticky |
CDESK_ALLOWED_HOSTS / CDESK_ALLOWED_ORIGINS | nie | Ďalšie názvy, ktoré uvádza vaša proxy, oddelené čiarkami |
CDESK_TRUST_PROXY=1 | odporúčané za proxy | Berie IP adresu návštevníka z CF-Connecting-IP / X-Forwarded-For. Dajú sa sfalšovať, takže to zapnite len vtedy, keď ich nastavuje vaša vlastná proxy |
CDESK_TIMEZONE | nie | Napríklad Europe/Bratislava. Dátumy bez časovej zóny číta ako miestny čas systému CDESK |
CDESK_EVIDENCE_THRESHOLD | nie, predvolene 3 | Koľko samostatných záznamov asistent potrebuje, než niečo potvrdí ako trend |
CDESK_LOG_LEVEL / CDESK_TIMEOUT_SECONDS | nie | INFO / 30 |
Ochrana pred volaniami z neočakávaných adries je zapnutá predvolene. Server prijíma požiadavky, ktoré uvádzajú jeho vlastnú verejnú adresu, adresu, na ktorej počúva, 127.0.0.1 a localhost na ľubovoľnom porte, a ako pôvod požiadavky svoju verejnú adresu, https://claude.ai alebo https://claude.com. Ak vaša proxy uvádza niečo iné, pridajte to do CDESK_ALLOWED_HOSTS alebo CDESK_ALLOWED_ORIGINS.
Priebeh prihlásenia používateľa
1. AI aplikácia používateľa sa zaregistruje u vášho servera a požiada o prihlásenie.
2. Používateľ sa dostane na prihlasovaciu stránku, ktorá má dva kroky. Najprv sa pýta na jeho vlastnú adresu CDESK vo voľnom textovom poli, ktoré je na začiatku prázdne – žiadny rozbaľovací zoznam, žiadna predvolená hodnota a prázdna adresa sa odmietne. S CDESK_ALLOW_CUSTOM_BASE_URL=false musí zodpovedať niektorej z vašich adries a odmietnutie vymenuje tie, ktoré sú prijímané.
3. Používateľ klikne Verify server a váš server overí, čo sa na tej adrese nachádza. Následne sa priamo na mieste odkryjú polia pre meno a heslo a s nimi aj tlačidlo Microsoftu – ale len pri CDESK, ktorý prihlásenie cez Microsoft naozaj ponúka, takže ľuďom sa nikdy nezobrazí tlačidlo, ktoré nemôže fungovať. Ak samotné overenie zlyhá, prihlásenie nie je zablokované: stránka to napíše a nechá ich pokračovať, len bez tlačidla Microsoftu.
4. Meno a heslo sa overia jediným volaním na CDESK server, ktorý zadali. Konto so zapnutým 2FA to nedokáže dokončiť a bude odmietnuté; nesprávne heslo sa odmietne ako nesprávne heslo.
5. Heslo sa hneď po tomto jednom volaní zahodí. Ďalej pokračuje už len sedenie v CDESK, zašifrované vnútri toho, čo drží AI aplikácia.
6. Zvolená adresa CDESK sa zapamätá ako súčasť daného sedenia, takže každá ďalšia požiadavka, obnova aj odhlásenie mieria na správny server. Ľudia z rôznych CDESK serverov môžu súčasne zdieľať jednu inštaláciu.