MCP clients need a long-lived credential that works only on the MCP routes (a login token dies in 15 minutes)

Start by reviewing auth/jwt.ts, auth/authorize.ts, worker.ts, routes/admin.ts, and the listed authorization and audit tests. Confirm the owner decisions on lifetime, caller-only minting, secret rotation, and endpoint scope before implementing the planned changes. Done means scoped tokens work only on the MCP routes, existing access tokens still work there, invalid tokens are rejected elsewhere, audit and startup-safety tests pass, workflows and documentation are updated, and the audit checks remain consistent.

Problem

Claude Desktop reaches WorkWell's MCP server through mcp-remote with a fixed Authorization: Bearer <JWT> header (docs/MCP.md). The only bearer token the backend issues is the login access token: 900 s (createJwt default, backend-ts/src/auth/jwt.ts), and mcp-remote cannot refresh a fixed header. So the connection dies 15 minutes after each mint, and Claude Desktop reports the WorkWell MCP server as disconnected on every launch.

Verified 2026-09-24:

• No route accepts anything but that access token. extractPrincipal (auth/authorize.ts) verifies only WORKWELL_AUTH_JWT_SECRET access tokens; there is no API key or service credential anywhere in backend-ts/src.
• The 30-day WORKWELL_AUTH_ACCESS_TTL_SECONDS that once covered this was read only by the Java backend; the TypeScript port never wired it, and #703 removes it from the workflows.
• Making every access token long-lived is rejected: access tokens are stateless and unrevocable, so a 30-day one outlives logout for every browser user (and undoes #688's revocation).
• ROLE_MCP_CLIENT also opens /cds-services/** and /$cql (auth/authorize.ts), so a new credential must not simply reuse the role gate.

Workaround until this ships: disable the workwell entry in Claude Desktop's MCP settings, or re-mint a token from /api/auth/login per session.

Design

A separate token that is long-lived and accepted only on /sse and /mcp/**.

• Own secret: signed with WORKWELL_MCP_TOKEN_SECRET, never WORKWELL_AUTH_JWT_SECRET. The ordinary verifier therefore cannot accept an MCP token even if the route check is wrong, and rotating the MCP secret revokes every MCP token without signing anyone out of the app. Unset secret = feature off.
• Claims: { sub, role, scope: "mcp", jti, iat, exp }. sub/role are the minting user's, so the audit actor (MCP_TOOL_CALLED), the demo-account profile refusal and the per-tool role gates in mcp/dispatch.ts behave exactly as today. The tools stay read-only.
• Route scope: the MCP verifier is consulted only when the path is /sse or /mcp/**. Everywhere else, including /cds-services/**, /$cql, /api/** and /api/auth/*, an MCP token is an unauthenticated request. The MCP routes keep accepting a normal access token.
• Minting: POST /api/admin/mcp-tokens { ttlDays } (ADMIN, via the existing /api/admin/** rule), for the caller only. Default 30 days, cap 90. Audit-first: MCP_TOKEN_MINTED (subject, role, jti, expiresAt; never the token) is written before the token is returned, once.
• No table. Revocation is all-at-once by rotating the secret. That is acceptable on a synthetic-data sandbox with a few MCP users; per-token revocation is the PHI-phase step below.

Plan (one PR, feat/mcp-scoped-token)

1. auth/jwt.ts: export the HS256 sign/verify helpers (don't copy them); add a small auth/mcp-token.ts that issues and verifies the scoped token (rejects a missing or wrong scope, expired, or wrong-secret token).
2. auth/authorize.ts + worker.ts: extractPrincipal takes the pathname and an optional MCP verifier, used only on /sse and /mcp/**; rebuildAuthIfNeeded builds it from WORKWELL_MCP_TOKEN_SECRET and rebuilds when either secret changes.
3. config/startup-safety.ts: when set in production, the MCP secret passes the same strength rule as the JWT secret and must differ from it.
4. Mint route under routes/admin.ts, audit-first, added to audit/audit-order.test.ts. Re-run scripts/audit-order-sweep.py and keep DATA_MODEL_CONTRACTS.md §4's count in step if it moves. Add to the OpenAPI spec if admin routes are listed there.
5. Workflows: add WORKWELL_MCP_TOKEN_SECRET to the three deploy workflows and both reconcilers (mirrored). The owner creates WORKWELL_MCP_TOKEN_SECRET_TWH / _MAUI / _STAGING in GitHub secrets.
6. Docs: MCP.md (mint, configure mcp-remote, rotate to revoke), DEPLOY.md secret table, one gap line in PRODUCTION_READINESS_2026-07.md (below), JOURNAL.md.

Tests (each mutation-checked: break the guard, see the test fail)

• An MCP token authenticates /sse and /mcp/** and is 401 on /api/cases, /api/admin/*, /cds-services/*, /$cql.
• A normal access token still works on the MCP routes.
• verifyAccessToken rejects an MCP token (secret separation), and a main-secret token carrying scope: "mcp" is not accepted as an MCP token.
• Expired, wrong-scope and tampered MCP tokens are 401.
• Secret unset: the mint route answers 404 and no MCP token verifies.
• A demo account's MCP token is refused on a profile that refuses demo accounts (Maui).
• Mint is audit-first; the event payload never contains the token; ttlDays above 90 or below 1 is a 400.
• Startup safety refuses a weak MCP secret, or one equal to the JWT secret, in production.

Decisions for the owner before building

1. Lifetime: default 30 days, cap 90?
2. Caller-only minting, or may an admin mint for a named service account (e.g. a ROLE_MCP_CLIENT + ROLE_CASE_MANAGER identity)? Recommendation: caller-only first.
3. Revoke by rotating the secret (no DDL) for the sandbox, per-token revocation later? Recommendation: yes.
4. Endpoint + documented curl only, or also a button on the Admin page? Recommendation: endpoint only first.

Not in scope

• OAuth for mcp-remote (it supports the MCP authorization flow, but WorkWell would need an authorization server).
• Per-token revocation. Before the PHI phase, replace the stateless token with stored, hashed API keys: per-key revocation, last-used time, a list in Admin. That is a table (owner DDL); record it in PRODUCTION_READINESS_2026-07.md as part of this PR.
• /cds-services/** and /$cql. They keep their current credential.