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>
This commit is contained in:
MechaCat02
23
docs/AUTH.md
23
docs/AUTH.md
@@ -192,16 +192,29 @@ a shared secret checked in constant time on every `/mcp` request
|
||||
Generate one with `openssl rand -hex 32`. If it is unset the server logs a loud
|
||||
warning and serves unauthenticated — only acceptable bound to localhost.
|
||||
|
||||
Rotating it: change `MCP_AUTH_TOKEN` in `.env`, restart the container, update
|
||||
the connector in Claude. Nothing else stores it.
|
||||
Rotating it: change `MCP_AUTH_TOKEN` in `.env`, recreate the container, and
|
||||
update Claude Code and the CLI (`schulcloud login`). Nothing else stores it.
|
||||
|
||||
### The secret path, for claude.ai
|
||||
|
||||
claude.ai's connector dialog takes a URL and no header, so `MCP_PATH_SECRET`
|
||||
opens a second way in: `/<secret>/mcp`, with no bearer token. The path is the
|
||||
credential there. `http/auth.ts` compares it in constant time and answers a
|
||||
wrong one with the same 404 as any unknown path; `config.ts` insists on at
|
||||
least 32 URL-safe characters and never echoes the value; the server never logs
|
||||
request paths; and `deploy/Caddyfile.snippet` rewrites the segment before an
|
||||
access log entry is written. Rotating it means a new value, a recreated
|
||||
container, and re-adding the connector. It is a stopgap: OAuth is how
|
||||
connectors are meant to authenticate, and it would make the URL a plain
|
||||
address again.
|
||||
|
||||
## Blast radius
|
||||
|
||||
Every path in this server is a `GET`, including the `api_get` escape hatch,
|
||||
which rejects anything not starting with `/api/` and anything carrying a scheme
|
||||
or host. Someone who obtained both the endpoint URL and `MCP_AUTH_TOKEN` could
|
||||
read this account's Schulcloud data; they could not post, submit, delete, or
|
||||
otherwise act as the user. With `MCP_AUTH_TOKEN` they
|
||||
or host. Someone who obtained both the endpoint URL and `MCP_AUTH_TOKEN` — or
|
||||
the secret MCP path — could read this account's Schulcloud data; they could not
|
||||
post, submit, delete, or otherwise act as the user. With `MCP_AUTH_TOKEN` they
|
||||
could also call `PUT /api/token`, but it accepts only a live token for the same
|
||||
account, so the most it can do is hand the server a session the owner already
|
||||
has. Keep it that way — adding a single write tool would change that property
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -107,9 +107,9 @@ node dist/bin/cli.js sync
|
||||
## Run the test suites
|
||||
|
||||
```bash
|
||||
npm test # 174 offline tests
|
||||
npm test # 178 offline tests
|
||||
npm run smoke # end-to-end against the live instance, live-only mode
|
||||
DATABASE_URL=… npm run smoke # end-to-end with the index (74 checks)
|
||||
DATABASE_URL=… npm run smoke # end-to-end with the index (76 checks)
|
||||
```
|
||||
|
||||
Store tests need a database and skip without one:
|
||||
|
||||
Reference in New Issue
Block a user