catence 0.2.1-beta.13 → 0.2.1-beta.15

package/README.md

@@ -120,7 +120,7 @@ Optional local Streamable HTTP MCP and HTTP APIs:
 catence serve --host 127.0.0.1 --port 8787
 ```
 
-`GET /api/v1/athletes` returns IDs and labels only. `GET /api/v1/dashboard` requires `athleteId`, for example `http://127.0.0.1:8787/api/v1/dashboard?athleteId=alex&days=28`. Browser origins must be listed with `--allow-origin`; the packaged Console instead proxies the dashboard through its authenticated same-origin route. `POST /api/v1/athletes` creates a catalog athlete (`{"id": "sam", "label": "Sam", "setDefault": false}`); the packaged Console exposes the same call to admins from **Settings → Athletes**. The MCP server has no authentication of its own.
+`GET /api/v1/athletes` returns IDs and labels only. `GET /api/v1/dashboard` requires `athleteId`, for example `http://127.0.0.1:8787/api/v1/dashboard?athleteId=alex&days=28`. Browser origins must be listed with `--allow-origin`; the packaged Console instead proxies the dashboard through its authenticated same-origin route. `POST /api/v1/athletes` creates a catalog athlete (`{"id": "sam", "label": "Sam", "setDefault": false}`); the packaged Console exposes the same call to admins from **Settings → Athletes**. The MCP server has no authentication of its own beyond the optional bearer-token gate: `catence-data mcp enable` generates a token at `<home>/mcp-token` and every endpoint except the health probes then requires `Authorization: Bearer <token>`; `mcp status`/`mcp token`/`mcp disable` manage it, and the Console Settings expose the same controls to admins.
 
 ## Configuration
 

package/dist/contracts/release.d.ts

@@ -3,7 +3,7 @@
  * Keep these values synchronized with release/manifest.json; release checks
  * deliberately reject drift before a package can be published.
  */
-export declare const CATENCE_RUNTIME_VERSION = "0.2.1-beta.13";
+export declare const CATENCE_RUNTIME_VERSION = "0.2.1-beta.15";
 export declare const CATENCE_PROTOCOL_VERSION = 1;
 export type CatenceRuntimeCapabilities = {
     mcp: true;

package/dist/contracts/release.js

@@ -3,7 +3,7 @@
  * Keep these values synchronized with release/manifest.json; release checks
  * deliberately reject drift before a package can be published.
  */
-export const CATENCE_RUNTIME_VERSION = '0.2.1-beta.13';
+export const CATENCE_RUNTIME_VERSION = '0.2.1-beta.15';
 export const CATENCE_PROTOCOL_VERSION = 1;
 export function catenceRuntimeHealth() {
     return {

package/dist/interfaces/cli/commands.js

@@ -2,6 +2,7 @@
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { Command } from 'commander';
+import { defaultBearerTokenPath, disableBearerToken, ensureBearerToken, mcpExposureStatus, readBearerToken, } from '../http/cli-options.js';
 import { addAthlete, athleteStorePaths, CATENCE_RUNTIME_VERSION, CatenceDatabase, channelForVersion, createDemoStore, dataStatus, deleteAthleteSecret, defaultCatalogHome, disconnectStravaAccount, fetchNpmDistTags, fetchPypiReleases, hasCommand, importStagedFile, initializeCatalog, isGlobalNpmInstall, linkActivity, loadCatalog, npmGlobalPrefix, planSelfUpdate, readInstalledConsoleVersion, rebuildRetrievalIndex, reimportNutrition, reimportWeight, resolveExtractionErrors, resolveAthlete, resolveCatalogPaths, retryDataSync, runSelfUpdateCommand, setAthleteSecret, syncData, syncProgress, connectStrava, connectStravaWithCallback, unlinkActivity, } from '../../runtime/index.js';
 const program = new Command()
     .name('catence-data')
@@ -37,6 +38,41 @@ async function stdinSecret() {
         throw new Error('--value-stdin received an empty secret.');
     return value;
 }
+const mcpCommand = program.command('mcp').description('Manage Streamable HTTP MCP exposure: the bearer-token gate, its token, and endpoint URLs.');
+const mcpLocalEndpoint = () => `http://127.0.0.1:${process.env.CATENCE_HTTP_PORT ?? '8787'}`;
+mcpCommand.command('status')
+    .description('Report whether the bearer-token gate is enabled, the token, and the endpoint URLs.')
+    .option('--file <path>', 'non-default token file path')
+    .action(async (options) => {
+    const tokenFile = options.file ?? defaultBearerTokenPath(currentCatalog().root);
+    process.stdout.write(`${JSON.stringify(mcpExposureStatus(tokenFile, mcpLocalEndpoint()), null, 2)}\n`);
+});
+mcpCommand.command('enable')
+    .description('Enable the bearer-token gate: generate the token file (mode 0600) if it does not exist.')
+    .option('--file <path>', 'non-default token file path')
+    .action(async (options) => {
+    const tokenFile = options.file ?? defaultBearerTokenPath(currentCatalog().root);
+    ensureBearerToken(tokenFile);
+    process.stdout.write(`${JSON.stringify(mcpExposureStatus(tokenFile, mcpLocalEndpoint()), null, 2)}\n`);
+});
+mcpCommand.command('disable')
+    .description('Disable the bearer-token gate by removing the token file. Remote access is refused again.')
+    .option('--file <path>', 'non-default token file path')
+    .action(async (options) => {
+    const tokenFile = options.file ?? defaultBearerTokenPath(currentCatalog().root);
+    disableBearerToken(tokenFile);
+    process.stdout.write(`${JSON.stringify(mcpExposureStatus(tokenFile, mcpLocalEndpoint()), null, 2)}\n`);
+});
+mcpCommand.command('token')
+    .description('Print only the bearer token for pasting into an MCP client credential flow.')
+    .option('--file <path>', 'non-default token file path')
+    .action(async (options) => {
+    const tokenFile = options.file ?? defaultBearerTokenPath(currentCatalog().root);
+    const token = readBearerToken(tokenFile);
+    if (token === null)
+        throw new Error(`MCP exposure is not enabled; run 'catence-data mcp enable' first.`);
+    process.stdout.write(`${token}\n`);
+});
 program.command('setup')
     .description('Create a home catalog and its first athlete store. Existing 0.1 stores must be re-synced.')
     .option('--athlete <id>', 'first athlete ID')

package/dist/interfaces/http/cli-options.d.ts

@@ -3,7 +3,37 @@ export type ServeCliOptions = {
     host: string;
     port: number;
     allowedOrigins: string[];
+    authTokenFile?: string;
     help: boolean;
 };
-export declare const SERVE_USAGE = "Usage: catence serve [options]\n\nRun Catence as a local Streamable HTTP MCP server.\n\nOptions:\n  --home <directory>         Catence catalog home. Defaults to CATENCE_HOME or ~/.catence.\n  --host <host>              Listener host. Defaults to 127.0.0.1.\n  --port <port>              Listener port. Defaults to 8787.\n  --allow-origin <origin>    Browser origin allowed to call Catence APIs. May be repeated.\n  -h, --help                 Show this help text.";
+export declare const SERVE_USAGE = "Usage: catence serve [options]\n\nRun Catence as a local Streamable HTTP MCP server.\n\nOptions:\n  --home <directory>         Catence catalog home. Defaults to CATENCE_HOME or ~/.catence.\n  --host <host>              Listener host. Defaults to 127.0.0.1.\n  --port <port>              Listener port. Defaults to 8787.\n  --allow-origin <origin>    Browser origin allowed to call Catence APIs. May be repeated.\n  --auth-token-file <path>   Bearer-token file for the HTTP gate. Its presence switches authentication on;\n                             generate/inspect it with 'catence-data mcp enable|token'.\n                             Defaults to CATENCE_MCP_TOKEN_FILE or <catalog-home>/mcp-token.\n  -h, --help                 Show this help text.";
+/** The canonical token location inside a catalog home. */
+export declare function defaultBearerTokenPath(catalogRoot: string): string;
+/** Read and validate a stored bearer token: trimmed, non-empty, or fail loudly. */
+export declare function loadBearerToken(filePath: string): string;
+/**
+ * The bearer token for the server: the stored one, or a freshly generated
+ * token written to the file (mode 0600) when it does not exist yet. Users
+ * never hand-craft tokens; they enable auth and read the result with
+ * `catence-data mcp-token`.
+ */
+export declare function ensureBearerToken(filePath: string): string;
+export declare function disableBearerToken(filePath: string): void;
+/** The bearer token when exposure is enabled, or null when no token file exists. */
+export declare function readBearerToken(filePath: string): string | null;
+/**
+ * The currently active bearer token for the HTTP gate, cached by the token
+ * file's mtime so enabling or disabling is picked up without a restart. A
+ * missing file disables the gate; an existing but unreadable or empty file
+ * fails closed (the gate rejects everything except health probes).
+ */
+export declare function activeBearerToken(filePath: string): string | null | 'invalid';
+export type McpExposureStatus = {
+    enabled: boolean;
+    tokenFile: string;
+    endpoint: string;
+    healthEndpoint: string;
+    token?: string;
+};
+export declare function mcpExposureStatus(filePath: string, endpointBase: string): McpExposureStatus;
 export declare function parseServeCliOptions(arguments_: readonly string[]): ServeCliOptions;

package/dist/interfaces/http/cli-options.js

@@ -1,3 +1,5 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 export const SERVE_USAGE = `Usage: catence serve [options]
 
 Run Catence as a local Streamable HTTP MCP server.
@@ -7,7 +9,89 @@ Options:
   --host <host>              Listener host. Defaults to 127.0.0.1.
   --port <port>              Listener port. Defaults to 8787.
   --allow-origin <origin>    Browser origin allowed to call Catence APIs. May be repeated.
+  --auth-token-file <path>   Bearer-token file for the HTTP gate. Its presence switches authentication on;
+                             generate/inspect it with 'catence-data mcp enable|token'.
+                             Defaults to CATENCE_MCP_TOKEN_FILE or <catalog-home>/mcp-token.
   -h, --help                 Show this help text.`;
+/** The canonical token location inside a catalog home. */
+export function defaultBearerTokenPath(catalogRoot) {
+    return `${catalogRoot.replace(/[/\\]+$/, '')}/mcp-token`;
+}
+/** Read and validate a stored bearer token: trimmed, non-empty, or fail loudly. */
+export function loadBearerToken(filePath) {
+    let token;
+    try {
+        token = readFileSync(filePath, 'utf8').trim();
+    }
+    catch (error) {
+        throw new Error(`Cannot read the auth token file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!token)
+        throw new Error(`The auth token file ${filePath} is empty.`);
+    return token;
+}
+/**
+ * The bearer token for the server: the stored one, or a freshly generated
+ * token written to the file (mode 0600) when it does not exist yet. Users
+ * never hand-craft tokens; they enable auth and read the result with
+ * `catence-data mcp-token`.
+ */
+export function ensureBearerToken(filePath) {
+    if (existsSync(filePath))
+        return loadBearerToken(filePath);
+    const token = randomBytes(32).toString('hex');
+    writeFileSync(filePath, token, { mode: 0o600 });
+    return token;
+}
+export function disableBearerToken(filePath) {
+    if (existsSync(filePath))
+        rmSync(filePath);
+}
+/** The bearer token when exposure is enabled, or null when no token file exists. */
+export function readBearerToken(filePath) {
+    return existsSync(filePath) ? loadBearerToken(filePath) : null;
+}
+const tokenCache = new Map();
+/**
+ * The currently active bearer token for the HTTP gate, cached by the token
+ * file's mtime so enabling or disabling is picked up without a restart. A
+ * missing file disables the gate; an existing but unreadable or empty file
+ * fails closed (the gate rejects everything except health probes).
+ */
+export function activeBearerToken(filePath) {
+    let mtimeMs = 0;
+    try {
+        mtimeMs = statSync(filePath).mtimeMs;
+    }
+    catch {
+        tokenCache.set(filePath, { mtimeMs: 0, token: null });
+        return null;
+    }
+    const cached = tokenCache.get(filePath);
+    if (cached && cached.mtimeMs === mtimeMs) {
+        return cached.token === null ? 'invalid' : cached.token;
+    }
+    try {
+        const token = loadBearerToken(filePath);
+        tokenCache.set(filePath, { mtimeMs, token });
+        return token;
+    }
+    catch {
+        tokenCache.set(filePath, { mtimeMs, token: null });
+        return 'invalid';
+    }
+}
+export function mcpExposureStatus(filePath, endpointBase) {
+    const token = readBearerToken(filePath);
+    const base = endpointBase.replace(/\/+$/, '');
+    return {
+        enabled: token !== null,
+        tokenFile: filePath,
+        endpoint: `${base}/mcp`,
+        healthEndpoint: `${base}/health`,
+        ...(token !== null ? { token } : {}),
+    };
+}
 function requiredValue(arguments_, index, option) {
     const value = arguments_[index + 1];
     if (!value || value.startsWith('-'))
@@ -27,10 +111,11 @@ export function parseServeCliOptions(arguments_) {
     let host = process.env.CATENCE_HTTP_HOST ?? '127.0.0.1';
     let port = process.env.CATENCE_HTTP_PORT ? parsePort(process.env.CATENCE_HTTP_PORT) : 8787;
     const allowedOrigins = [];
+    let authTokenFile = process.env.CATENCE_MCP_TOKEN_FILE || undefined;
     for (let index = 0; index < arguments_.length; index++) {
         const argument = arguments_[index];
         if (argument === '-h' || argument === '--help')
-            return { home, host, port, allowedOrigins, help: true };
+            return { home, host, port, allowedOrigins, authTokenFile, help: true };
         if (argument === '--home') {
             home = requiredValue(arguments_, index, '--home');
             index++;
@@ -42,6 +127,17 @@ export function parseServeCliOptions(arguments_) {
                 throw new Error('--home requires a value.');
             continue;
         }
+        if (argument === '--auth-token-file') {
+            authTokenFile = requiredValue(arguments_, index, '--auth-token-file');
+            index++;
+            continue;
+        }
+        if (argument.startsWith('--auth-token-file=')) {
+            authTokenFile = argument.slice('--auth-token-file='.length);
+            if (!authTokenFile)
+                throw new Error('--auth-token-file requires a value.');
+            continue;
+        }
         if (argument === '--host') {
             host = requiredValue(arguments_, index, '--host');
             index++;
@@ -76,6 +172,6 @@ export function parseServeCliOptions(arguments_) {
         }
         throw new Error(`Unknown option: ${argument}`);
     }
-    return { home, host, port, allowedOrigins, help: false };
+    return { home, host, port, allowedOrigins, authTokenFile, help: false };
 }
 //# sourceMappingURL=cli-options.js.map

package/dist/interfaces/http/server.d.ts

@@ -6,6 +6,21 @@ export type CatenceHttpServerOptions = {
     /** Internal compatibility hook for tests and embedded single-store callers. */
     paths?: CatencePaths;
     allowedOrigins?: readonly string[];
+    /**
+     * Static bearer token for the gate (tests and embedded single-store callers).
+     * Mutually exclusive with bearerTokenFile.
+     */
+    bearerToken?: string;
+    /**
+     * Token file whose presence switches the gate on: every request except the
+     * health endpoints and CORS preflights must present
+     * `Authorization: Bearer <token>`. The file is re-read on mtime change, so
+     * `catence-data mcp enable|disable` (and the /api/v1/mcp-exposure route)
+     * take effect without a restart. The MCP server has no other
+     * authentication; this gates it (and the JSON APIs) for non-loopback
+     * exposure such as a Cloudflare Tunnel to an MCP client.
+     */
+    bearerTokenFile?: string;
     /** Internal compatibility hook for tests: override the detached sync spawner. */
     startSync?: typeof startDetachedSync;
     /** Internal compatibility hook for tests: passed into the default startDetachedSync. */

package/dist/interfaces/http/server.js

@@ -1,10 +1,26 @@
+import { timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
 import path from 'node:path';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { addAthlete, AthleteFileConflictError, AthleteFileTooLargeError, AthleteFileValidationError, catenceRuntimeHealth, DashboardSnapshotService, deleteAthleteSecret, describeAthleteSecrets, DetachedSyncBusyError, DETACHED_SYNC_PROVIDERS, jsonSafe, listAthleteFileRevisions, loadCatalog, mergeOpenCodeGoConsoleProfiles, openReadOnlyRepository, readAthleteFile, readAthleteFileRevision, resolveAthlete, resolveCatalogPaths, setAthleteSecret, startDetachedSync, syncProgress, updateAthleteFile, } from '../../runtime/index.js';
+import { activeBearerToken, ensureBearerToken, disableBearerToken, mcpExposureStatus } from './cli-options.js';
 import { createCatenceMcpServer } from '../mcp/server.js';
 import { generationStatus } from './generation-status.js';
 const MAX_REQUEST_BYTES = 1_000_000;
+/** Endpoints that stay open when bearer authentication is enabled: they carry
+ * no personal data and must answer unauthenticated readiness probes. */
+const UNAUTHENTICATED_PATHS = new Set(['/health', '/api/v1/health']);
+function isAuthorized(request, options) {
+    const bearerToken = options.bearerToken !== undefined ? options.bearerToken : options.bearerTokenFile !== undefined ? activeBearerToken(options.bearerTokenFile) : undefined;
+    if (bearerToken === undefined || bearerToken === null)
+        return true;
+    if (bearerToken === 'invalid')
+        return false;
+    const received = Buffer.from(request.headers.authorization ?? '');
+    const expected = Buffer.from(`Bearer ${bearerToken}`);
+    // timingSafeEqual throws on length mismatch, so compare sizes first.
+    return received.length === expected.length && timingSafeEqual(received, expected);
+}
 function json(response, statusCode, value) {
     const body = JSON.stringify(jsonSafe(value));
     response.writeHead(statusCode, { 'content-type': 'application/json; charset=utf-8' });
@@ -313,6 +329,12 @@ export function createCatenceHttpServer(options = {}) {
                 response.writeHead(204).end();
                 return;
             }
+            if (!UNAUTHENTICATED_PATHS.has(pathname) && !isAuthorized(request, options)) {
+                // No WWW-Authenticate on purpose: MCP connector auto-detection treats a
+                // plain 401 as a bearer gate rather than an OAuth server.
+                json(response, 401, { error: { code: 'unauthorized', message: 'A valid Authorization: Bearer token is required.' } });
+                return;
+            }
             if (pathname === '/health' && request.method === 'GET') {
                 json(response, 200, catenceRuntimeHealth());
                 return;
@@ -581,6 +603,35 @@ export function createCatenceHttpServer(options = {}) {
                 }
                 return;
             }
+            if (pathname === '/api/v1/mcp-exposure' && request.method === 'GET') {
+                if (!options.bearerTokenFile) {
+                    json(response, 400, { error: { code: 'exposure_not_configured', message: 'This server was started without a bearer-token file; restart it with --auth-token-file to manage MCP exposure.' } });
+                    return;
+                }
+                json(response, 200, mcpExposureStatus(options.bearerTokenFile, `http://${request.headers.host ?? '127.0.0.1:8787'}`));
+                return;
+            }
+            if (pathname === '/api/v1/mcp-exposure' && request.method === 'POST') {
+                if (!options.bearerTokenFile) {
+                    json(response, 400, { error: { code: 'exposure_not_configured', message: 'This server was started without a bearer-token file; restart it with --auth-token-file to manage MCP exposure.' } });
+                    return;
+                }
+                try {
+                    const body = await readJsonBody(request);
+                    if (typeof body !== 'object' || body === null || Array.isArray(body) || !('enabled' in body) || typeof body.enabled !== 'boolean') {
+                        throw new Error('Request body must be a JSON object with a boolean "enabled" field.');
+                    }
+                    if (body.enabled)
+                        ensureBearerToken(options.bearerTokenFile);
+                    else
+                        disableBearerToken(options.bearerTokenFile);
+                    json(response, 200, mcpExposureStatus(options.bearerTokenFile, `http://${request.headers.host ?? '127.0.0.1:8787'}`));
+                }
+                catch (error) {
+                    json(response, 400, { error: { code: 'exposure_update_failed', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
             if (pathname === '/mcp') {
                 await handleMcpRequest(request, response, catalogPaths ?? staticPaths ?? resolveCatalogPaths());
                 return;

package/dist/interfaces/mcp/main.js

@@ -2,7 +2,7 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { existsSync } from 'node:fs';
 import { addAthlete, athleteStorePaths, CatenceDatabase, createDemoStore, defaultCatalogHome, initializeCatalog, loadCatalog, resolveCatalogPaths } from '../../runtime/index.js';
-import { parseServeCliOptions, SERVE_USAGE } from '../http/cli-options.js';
+import { defaultBearerTokenPath, parseServeCliOptions, SERVE_USAGE } from '../http/cli-options.js';
 import { createCatenceHttpServer } from '../http/server.js';
 import { MCP_USAGE, parseMcpCliOptions } from './cli-options.js';
 import { createCatenceMcpServer } from './server.js';
@@ -46,9 +46,13 @@ async function run() {
             return;
         }
         await migrateCatalogStores(options.home);
+        const catalogPaths = resolveCatalogPaths(options.home);
         const httpServer = createCatenceHttpServer({
-            catalogPaths: resolveCatalogPaths(options.home),
+            catalogPaths,
             allowedOrigins: options.allowedOrigins,
+            // The token file's presence switches authentication on; enable it with
+            // `catence-data mcp enable` (or the Console Settings / exposure API).
+            bearerTokenFile: options.authTokenFile ?? defaultBearerTokenPath(catalogPaths.root),
         });
         await new Promise((resolve, reject) => {
             httpServer.once('error', reject);
@@ -58,6 +62,7 @@ async function run() {
             });
         });
         console.error(`Catence Streamable HTTP server is listening at http://${options.host}:${options.port}/mcp`);
+        console.error(`Bearer-token authentication is armed at ${options.authTokenFile ?? defaultBearerTokenPath(catalogPaths.root)}; enable it with 'catence-data mcp enable'. Health endpoints stay open for readiness probes.`);
         const close = () => {
             httpServer.close(() => process.exit(0));
         };

package/docs/configuration.md

@@ -247,6 +247,7 @@ profiles and preserve existing ones, limits, and `defaultProfile` unless
 | --- | --- |
 | `CATENCE_HOME` | Catalog home (default `~/.catence`); equivalent to `--home` |
 | `CATENCE_HTTP_HOST` / `CATENCE_HTTP_PORT` | Defaults for `catence serve --host/--port` (host `127.0.0.1`, port `8787`) |
+| `CATENCE_MCP_TOKEN_FILE` | Overrides the bearer-token file path for `catence serve` (default `<catalog-home>/mcp-token`); the file's presence switches the gate on, managed with `catence-data mcp enable/disable` or the Console Settings |
 
 Provider credentials are stored per athlete, either with `catence-data secret
 set` (see [`local-mcp.md`](deployment/local-mcp.md#3-store-provider-credentials-stdin-only-never-shell-history))

package/docs/deployment/docker.md

@@ -506,6 +506,47 @@ claude mcp add --transport http catence -- http://<tailscale-ip>:8787/mcp
   same-origin route.
 - SSH port forwarding keeps the trust boundary at your SSH credentials.
 
+### Bearer-token authentication for remote MCP clients
+
+To serve the MCP endpoint to a remote MCP client (for example a Mistral Work
+custom connector) over a Cloudflare Tunnel, switch on the native
+bearer-token gate. The deploy scaffold arms it at `/data/mcp-token` (inside
+the data volume, so it survives rebuilds); the file's presence is the switch
+and Catence generates the token itself:
+
+```sh
+# enable from the host (or use the Console Settings once logged in):
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env \
+  exec console catence-data --home /data mcp enable
+
+# print the token for the client's credential flow:
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env \
+  exec console catence-data --home /data mcp token
+
+# disable again:
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env \
+  exec console catence-data --home /data mcp disable
+```
+
+With the gate enabled, every runtime endpoint except `/health` and
+`/api/v1/health` answers `401` without an exact `Authorization: Bearer
+<token>` header — including `/mcp` and the JSON APIs. Toggling takes effect
+without a restart; the Console attaches the header automatically to its own
+runtime calls.
+
+Keep `CATENCE_MCP_BIND=127.0.0.1` (the default): the tunnel client on the
+host forwards to the host-loopback mapping, so the port still never binds a
+LAN interface. Point the tunnel ingress for the MCP hostname at
+`http://127.0.0.1:8787` and complete the client's credential flow with the
+token from `mcp token`. Rotate with `mcp disable && mcp enable` and
+re-authenticate the client. The only additional setup the tunnel needs is
+the ingress rule for the MCP hostname.
+
+A custom host-side token file is still possible: set
+`CATENCE_MCP_TOKEN_FILE=<host path>` in `.env`. The file is then bind-mounted
+read-only at the same path, so it must already exist on the host — enabling
+from the Console cannot create it.
+
 ## Exposing the Console safely
 
 Keep the Console port bound to `127.0.0.1` (the default) and front it with a

package/docs/deployment/local-mcp.md

@@ -302,6 +302,45 @@ catence serve --host 127.0.0.1 --port 8787
 By default it is loopback-only. `CATENCE_HTTP_HOST` and `CATENCE_HTTP_PORT`
 override the host and port when the flags are omitted.
 
+#### Bearer-token authentication
+
+The server has no authentication of its own; when it must be reachable beyond
+loopback (for example through a Cloudflare Tunnel to an MCP client such as
+Mistral Work), switch on the bearer-token gate. The gate is armed at a token
+file — `<catalog-home>/mcp-token` by default, or the path given by
+`--auth-token-file` (environment equivalent: `CATENCE_MCP_TOKEN_FILE`) — and
+the **file's presence is the switch**: create it to enable, remove it to
+disable, no restart needed.
+
+Catence generates the token itself; never hand-craft one:
+
+```sh
+catence-data mcp status    # enabled, token file, endpoint URLs
+catence-data mcp enable    # generate the token file (mode 0600) if missing
+catence-data mcp token      # print the token for the client credential flow
+catence-data mcp disable   # remove the file; remote access is refused again
+```
+
+- Every endpoint except `/health` and `/api/v1/health` (kept open for readiness
+  probes) answers `401` without an exact `Authorization: Bearer <token>`
+  header while the gate is on. The `401` deliberately carries no
+  `WWW-Authenticate`, so MCP clients with auth auto-detection (Mistral Work)
+  classify the server as bearer-auth rather than OAuth.
+- CORS preflights (`OPTIONS`) pass through without a token.
+- An existing but unreadable or empty token file fails closed: the gate
+  rejects everything except the health probes until the file is fixed or
+  removed.
+- `GET /api/v1/mcp-exposure` reports the same status the Console Settings page
+  shows (including the token); `POST /api/v1/mcp-exposure` with
+  `{"enabled": true|false}` toggles the gate. The Console exposes both to
+  admins only.
+- Rotation: `catence-data mcp disable && catence-data mcp enable` (or rewrite
+  the file), then re-authenticate the MCP client. Keep the token out of
+  `.env`, `config.json`, shell history, and repositories.
+- The Console attaches the same header automatically to its runtime calls and
+  reads the token file lazily, so enabling the gate from the Console or CLI
+  needs no Console restart either.
+
 - `GET /api/v1/athletes` returns IDs and labels only.
 - `POST /api/v1/athletes` creates a catalog athlete from
   `{"id": "sam", "label": "Sam", "setDefault": false}` and answers with the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catence",
-  "version": "0.2.1-beta.13",
+  "version": "0.2.1-beta.15",
   "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
   "license": "AGPL-3.0-or-later",
   "repository": {