Serve MCP at a secret path, so claude.ai can connect

claude.ai's connector dialog takes a name and a URL. Sending a bearer token
needs a "Request headers" beta most accounts lack, and OAuth is not built
yet, so with MCP_PATH_SECRET set the endpoint is also served at
/<secret>/mcp without the bearer token — a trial until OAuth replaces it.

The path is the credential there. It is compared in constant time, and a
wrong one answers 404 like any unknown path. The config refuses fewer than 32
URL-safe characters and never echoes the value, nothing in the server logs
request paths, and the Caddy snippet rewrites the segment before an access
log entry is written (verified against Caddy 2.11). Claude Code and the CLI
keep the bearer token; DEPLOYMENT.md says what the path trades away.

178 tests. Smoke 76/76 and 74/74 on the local instance.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/DEPLOYMENT.md

@@ -13,14 +13,16 @@ schulcloud CLI ─────┘                                └─ Caddy
                                                                   └──▶ schulcloud-thueringen.de
 ```
 
-Both front ends use the same hostname and the same bearer token. `/mcp` speaks MCP; `/api` serves the
+Both front ends use the same hostname. `/mcp` speaks MCP; `/api` serves the
 CLI's manifest, file bytes, re-crawl requests and token replacement; `/token` is
 a page for pasting a fresh Schulcloud token.
 
 Claude's custom connectors call the endpoint from Anthropic's cloud
 (`160.79.104.0/21`), so it must be publicly reachable over real TLS — a
 localhost tunnel or self-signed cert will not do. The VPS provides the public
-address; Caddy on the Pi terminates TLS and obtains the certificate.
+address; Caddy on the Pi terminates TLS and obtains the certificate. **Keep the
+VPS forwarding raw TCP** rather than terminating TLS itself: then it never sees
+a request path, which matters once a path carries a secret (below).
 
 **The Pi must stay up.** More than two hours offline ends the Schulcloud session
 however long the token has left — a laptop that sleeps overnight loses it every
@@ -40,6 +42,7 @@ cd /opt/schulcloud-mcp
 cp .env.example .env
 # Fill in TSC_URL and TSC_JWT_COOKIE (see docs/AUTH.md), then:
 openssl rand -hex 32   # → MCP_AUTH_TOKEN
+openssl rand -hex 32   # → MCP_PATH_SECRET, only for claude.ai (see "Connecting Claude")
 
 docker compose up -d --build
 docker compose logs -f schulcloud-mcp
@@ -111,6 +114,9 @@ Two settings in that snippet matter and are easy to miss:
   connector hangs with no error.
 - **`read_timeout`/`write_timeout` of 300s** — a `search` call walks every
   course and can take tens of seconds. Caddy's defaults will cut it off.
+- **The `format filter` in `log`** — rewrites `/<secret>/mcp` before an access
+  log entry is written. Without it every claude.ai request writes the secret to
+  disk. Verified against Caddy 2.11: the entry reads `"uri":"/<secret>/mcp"`.
 
 ## Ports and DNS
 
@@ -128,6 +134,10 @@ curl -s https://mcp.example.org/healthz
 curl -s -o /dev/null -w '%{http_code}\n' -X POST https://mcp.example.org/mcp \
   -H 'content-type: application/json' -d '{}'
 # 401   ← the bearer check is live
+
+curl -s -o /dev/null -w '%{http_code}\n' -X POST https://mcp.example.org/$(openssl rand -hex 32)/mcp \
+  -H 'content-type: application/json' -d '{}'
+# 404   ← a wrong path secret looks like any unknown path
 ```
 
 If `/healthz` answers but `/mcp` returns 401 with a correct token, check that
@@ -136,16 +146,45 @@ newline from a copy-paste.
 
 ## Connecting Claude
 
-1. claude.ai → **Settings → Connectors → Add custom connector**.
-2. URL: `https://mcp.example.org/mcp`
-3. Under **Advanced settings**, add the bearer token as an authorization
-   header. If your organisation has no header-auth field, the server also
-   accepts the token as `X-Api-Key`.
-4. Enable the connector in a conversation via **+ → Add connectors**.
+### claude.ai — a secret path, for now
 
-Ask *"which courses am I in?"* as a first check — that exercises auth, the
+claude.ai's *Add custom connector* dialog takes a name and a URL. Sending a
+bearer token needs its "Request headers" section, a beta most accounts do not
+have, and the proper answer — OAuth — is not built yet. Until it is, the
+server can serve MCP at a path that is itself the secret:
+
+1. Put `MCP_PATH_SECRET=<openssl rand -hex 32>` in `.env` and recreate the
+   container: `docker compose up -d --force-recreate schulcloud-mcp`. The
+   startup line then says `(plus secret MCP path)` — never the secret itself.
+2. claude.ai → **Customize → Connectors → Add custom connector**. Name it, and
+   give the URL `https://mcp.example.org/<secret>/mcp`. No sign-in.
+3. Enable it in a conversation via **+ → Connectors**.
+
+Ask *"which courses am I in?"* as a first check — that exercises the path, the
 Schulcloud token and the API in one call.
 
+**Know what this trades away.** The URL is now the credential, and Anthropic's
+connector documentation calls credentials in URLs a security vulnerability,
+because URLs end up in logs. This deployment keeps it out of its own: the
+server never logs request paths, the Caddy snippet rewrites the segment to
+`<secret>` in the access log, and a VPS forwarding raw TCP never sees it.
+Caddy's *error* log can still name the path if the container is down while
+claude.ai calls, and claude.ai stores the URL in its connector settings. There
+is no revocation short of a new secret: change `MCP_PATH_SECRET`, recreate the
+container, and add the connector again. Anyone holding the URL can read — never
+change — the account. A wrong secret answers 404, like any unknown path.
+
+### Claude Code and the CLI — the bearer token
+
+Both can send a header, so they keep using `MCP_AUTH_TOKEN` on the plain `/mcp`
+and `/api`:
+
+```bash
+claude mcp add --transport http --scope user schulcloud https://mcp.example.org/mcp \
+  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"
+schulcloud login --server https://mcp.example.org --token <MCP_AUTH_TOKEN>
+```
+
 ## Replacing the Schulcloud token
 
 The token lasts 30 days at most and can only come from a browser login (see