This section is for administrators who wish to run the CDESK MCP server on their own server, so that everyone in the company can connect to a single address and log in using their own CDESK account.
Basic experience of running a web server over HTTPS is assumed. The CDESK MCP server itself is a single, small programme, and we have tried to keep the steps below as concise as possible – your own custom HTTPS proxy, DNS and service management remain in your hands, as you know your environment far better than we do.
Solution architecture
A single CDESK MCP server serves a large number of users. It has no custom database and does not store anything on the hard drive – no user lists, no passwords, no data from CDESK. Each user logs in with their own CDESK custom account via the login page, and from then on, their AI application maintains an encrypted session, which CDESK MCP decrypts with every request.
Server installation
CDESK MCP is hosted on GitHub: https://github.com/Inovalogic-s-r-o/CDESK-MCP. Clone it to your server, or download it as a ZIP file from the same page if you do not wish to apply Git – with Git, future updates are as simple as a single `git pull`.
The project includes a ready-made container build – the `python:3.12-slim` image, dependencies via `uv sync –frozen –no-dev`, and an entry point of `python -m cdesk_mcp` – so the entire installation consists of four work orders:
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 -dThe server will then only be accessible at 127.0.0.1:8000 and will restart automatically. Port 8000 communicates via plain HTTP – never issue it directly. Your HTTPS proxy should be placed in front of it (Place an HTTPS server in front of it).
Completing the settings
Podstatné sú štyri nastavenia. Všetko ostatné má rozumnú predvolenú hodnotu; úplný zoznam nájdete v kapitole Úplný zoznam 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 (Úplný zoznam 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.
The address that people enter into the AI application is CDESK_PUBLIC_URL followed by the value of CDESK_MCP_PATH, which is /mcp unless you change it. If you set CDESK_MCP_PATH to /, they will apply CDESK_PUBLIC_URL on its own.
Generate the encryption key once, keep it secret and do not change it:
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"If you do not set it, the server will generate a new one each time it starts up, log a warning, and log everyone out on every restart. If you change it later, the same thing will happen once – so treat changing the key as a planned mass logout.
Do not set CDESK_LOGIN, CDESK_PASSWORD, CDESK_CLIENT_ID or CDESK_CLIENT_SECRET. The shared server never logs in using its custom settings; every connection originates from a logged-in user’s session. These four settings have no effect here.
If the server fails to start
The server will be declined to start in two scenarios, and this is the one thing it’s good to know in advance: it will log the reason for completion and then shut down cleanly. A return code of 0 appears to indicate success, so monitoring that only tracks failures will not detect anything, and the ‘unless-stopped’ restart will simply keep restarting it indefinitely. Check the log, not the return code.
The two cases are:
- CDESK_BASE_URL or CDESK_PUBLIC_URL is missing.
- One of them is ordinary http:// instead of https:// (except for localhost). Via plain HTTP, passwords for CDESK and sessions would be transmitted unencrypted, so the server will not do this.
HTTPS proxy settings
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í.
The branch running on the subdomain – that is, CDESK_PUBLIC_URL in the form https://example.com/cdesk-mcp – requires one more thing: it must also forward /.well-known/* from the domain root. AI applications look for this there, regardless of the path on which the server itself is located. If CDESK_PUBLIC_URL is an ordinary address without a path, this is not necessary.
Server functionality confirmation
Two quick checks from the command line:
curl -s https://<vasa-adresa>/.well-known/oauth-authorization-server | jq .
curl -si https://<vasa-adresa>/mcp | head -1 # očakávajte 401(The second one uses the default /mcp – if you have changed this, apply your own CDESK_MCP_PATH value.)
A 401 answer on the second check is correct: it proves that the server is running and is requesting a login.
Then do it properly: add the same address to the AI application and log in as the test user CDESK. This will allow you to verify the entire chain in one go – the information the AI application uses to locate you, the login page, the session exchange, and the first actual request to CDESK.
User connections
There are no individual user settings on the server. Each user logs in with their own CDESK account the first time they connect their AI application.
Share a single line – your address, i.e. CDESK_PUBLIC_URL followed by the value CDESK_MCP_PATH – and send people a link to the ‘Connecting to the CDESK MCP Cloud’ section of the documentation, which will guide them through the rest of the process, screen by screen.
Common branch operations and maintenance
Logs are only sent to the error output and never contain passwords, login details or data from CDESK. If the system starts up correctly, you will see something like this:
cdesk-mcp starting (transport=http)
cdesk-mcp listening on http://0.0.0.0:8000/mcp (clients connect to: https://…/mcp) - OAuth issuer https://…Availability checks: the address /health does not exist. Apply /.well-known/oauth-authorization-server, which returns a 200 status code without requiring authentication, or the path /mcp, where a 401 answer confirms that the server is active.
Sessions last for 8 hours and renew automatically; the renewal itself is valid for 30 days. Anyone who has been away for longer simply logs in again.
Changing the encryption key will log everyone out. Plan ahead for this.
A 200 answer in your logs is not proof of success. CDESK returns certain errors in the body of an answer with a 200 status code – for example, a conflict during concurrent record editing, a failed data validation check, or a disabled module.
Overview of configuration settings
Use .env.production.example as a starting point.
| Settings | Mandatory | What it does |
|---|---|---|
CDESK_TRANSPORT=http | Yes | Selects a shared server for multiple users |
CDESK_PUBLIC_URL | Yes | The HTTPS address that people are directed to. It is used for call forwarding during login and to identify the server. No slash at the end |
CDESK_BASE_URL | yes | Your CDESK address, host only. Serves as a fallback for sessions created before users were able to select their own server, and – when CDESK_ALLOW_CUSTOM_BASE_URL settings for false and CDESK_BASE_URLS is left blank – as the only accepted address. It is not pre-filled on the login page |
CDESK_ENCRYPTION_KEY | strongly recommended | Protects sessions. Fixed → sessions survive a restart and work across multiple server instances. Not set → a new key on every restart, so everyone is logged out |
CDESK_MCP_PATH | no, by default /mcp | The path people connect to, linked to CDESK_PUBLIC_URL. Set to /if you wish to serve it at that address itself. The change will forward all AI applications elsewhere and invalidate existing sessions |
CDESK_HTTP_HOST / CDESK_HTTP_PORT | no | Where the server is listening. The container sets the settings 0.0.0.0 and 8000; outside the container, the default is 127.0.0.1, accessible only from that machine |
CDESK_ALLOW_CUSTOM_BASE_URL | no, by default true | Allows users to enter any CDESK address when logging in. There is no whitelist of permitted addresses nor any protection against internal addresses – the server will attempt to log in to whatever has been entered. Set to falseif you wish to accept addresses only from CDESK_BASE_URLS, or from CDESK_BASE_URL, if you have left it blank |
CDESK_BASE_URLS | no | Pairs Popis=URL separated by commas, i.e. the CDESK servers you are familiar with. These are always accepted, and when the value is false above, they form a list of permitted servers. Addresses are matched leniently – missing https://, a slash at the end or other capital letters are still accepted. Descriptions are never displayed: the login page has a free-text field, not a drop-down list, so this creates a list of permitted addresses, not an offer |
CDESK_AZURE_LOGIN_ENABLED | no | Enables the ‘Log in with Microsoft’ button. This will then only be viewed on CDESK servers that actually offer login via Microsoft, which is confirmed when the user confirms their address. No configuration is required for individual CDESK servers; details are determined automatically |
CDESK_ALLOWED_HOSTS / CDESK_ALLOWED_ORIGINS | no | Other names listed by your proxy, separated by commas |
CDESK_TRUST_PROXY=1 | Recommended behind a proxy | Takes the visitor’s IP address from CF-Connecting-IP / X-Forwarded-For. These can be spoofed, so only enable this if your custom proxy is configuring them |
CDESK_TIMEZONE | No | For example Europe/Bratislava. Dates without a time zone are interpreted as the local time on the CDESK system |
CDESK_EVIDENCE_THRESHOLD | no, by default 3 | How many separate records does the assistant need before confirming something as a trend? |
CDESK_LOG_LEVEL / CDESK_TIMEOUT_SECONDS | No | INFO / 30 |
Protection against requests from unexpected addresses is enabled by default. The server accepts requests that specify its own custom public address, the address on which it is listening, 127.0.0.1 and localhost on any port, and its custom public address as the request’s origin, https://claude.ai or https://claude.com. If your proxy specifies something else, add it to CDESK_ALLOWED_HOSTS or CDESK_ALLOWED_ORIGINS.
The user login process
1. The user’s AI application signs up with your server and requests to log in.
2. The user is taken to a login page consisting of two steps. First, it asks for their own custom CDESK address in a free-text field, which is initially empty – there is no drop-down list, no default value, and an empty address will be declined. With CDESK_ALLOW_CUSTOM_BASE_URL=false, it must match one of your addresses, and if it is declined, the system will list those that are accepted.
3. The user clicks Verify server and your server confirms what is located at that address. The fields for the username and password will then appear on the page, along with the Microsoft button – but only for CDESK, which actually offers sign-in via Microsoft, so users will never see a button that cannot work. If the authentication itself fails, login is not blocked: the page will display a message to this effect and allow them to continue, just without the Microsoft button.
4. The username and password are confirmed via a single call to the CDESK server they have specified. An account with 2FA enabled cannot complete this process and will be declined; an incorrect password will be declined as such.
5. The password is discarded immediately after this single call. From then on, the session continues solely within CDESK, encrypted within the AI application.
6. The selected CDESK address is remembered as part of that session, so every subsequent request, refresh and logout is directed to the correct server. Users from different CDESK servers can share a single installation simultaneously.