@harness-fe/mcp-server 3.2.0 → 3.4.0

package/README.md

@@ -116,12 +116,19 @@ Remote Claude Code / Cursor config:
 --mcp-transport <kind>  stdio (default) | http
 --mcp-path <path>       Default /mcp
 --public-host <addr>    Override the host printed in outbound URLs
+--experimental-env-var <name>
+                        Restrict experimental tools to hosts where <name> is
+                        set. Omit for fully-on (default).
 -h, --help
 ```
 
 Matching env vars: `HARNESS_FE_HOST`, `HARNESS_FE_PORT`,
 `HARNESS_FE_TOKEN`, `HARNESS_FE_MCP_TRANSPORT`, `HARNESS_FE_MCP_PATH`,
-`HARNESS_FE_HEADLESS`.
+`HARNESS_FE_HEADLESS`. Experimental (in-testing) tools are **on by default** —
+no config. To restrict them, pass `--experimental-env-var <name>` /
+`HARNESS_FE_EXPERIMENTAL_ENV_VAR` (or `createDaemon({ experimentalEnvVar })`
+when embedding): the tools then show up only on machines where `<name>` is set
+to a non-empty value.
 
 ## Embedding into a host app
 
@@ -159,6 +166,7 @@ the hood — there is exactly one boot path.
 | `mcpHttp: false` | Boot only the WS bridge; skip mounting `/mcp`. Use when you want to wire MCP through stdio yourself (this is how the CLI's stdio mode embeds the daemon). |
 | `mcpPath: '/agents/mcp'` | Move the MCP HTTP endpoint to a non-default path. |
 | `dataDir` | Override the on-disk root for default JSONL stores. |
+| `experimentalEnvVar: 'MY_FLAG'` | Restrict experimental (in-testing) tools to hosts where `MY_FLAG` is set to a non-empty value. Omit for fully-on (the default). |
 
 ### Resumable SSE
 

package/dist/cli.js

@@ -37,14 +37,19 @@ Options:
   --mcp-path <path>      URL path for the MCP HTTP endpoint. Default /mcp.
   --public-host <addr>   Override the host printed in outbound URLs. Useful when
                          binding 0.0.0.0 and the auto-detected LAN IP is wrong.
+  --experimental-env-var <name>
+                         Restrict experimental (in-testing) tools to machines
+                         where <name> is set to a non-empty value. Omit this and
+                         experimental tools are fully on (the default).
   -h, --help             Show this help.
 
 Environment:
-  HARNESS_FE_HOST           Same as --host
-  HARNESS_FE_TOKEN          Same as --token (use "auto" to generate)
-  HARNESS_FE_MCP_TRANSPORT  Same as --mcp-transport
-  HARNESS_FE_MCP_PATH       Same as --mcp-path
-  HARNESS_FE_URL            Full ws:// URL (legacy; --host/--port override it)
+  HARNESS_FE_HOST                Same as --host
+  HARNESS_FE_TOKEN               Same as --token (use "auto" to generate)
+  HARNESS_FE_MCP_TRANSPORT       Same as --mcp-transport
+  HARNESS_FE_MCP_PATH            Same as --mcp-path
+  HARNESS_FE_EXPERIMENTAL_ENV_VAR  Same as --experimental-env-var
+  HARNESS_FE_URL                 Full ws:// URL (legacy; --host/--port override it)
 `;
     process.stderr.write(help);
     process.exit(0);
@@ -57,6 +62,7 @@ function parseArgs(argv) {
     let mcpTransport;
     let mcpPath;
     let publicHost;
+    let experimentalEnvVar;
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
         const next = () => {
@@ -100,6 +106,9 @@ function parseArgs(argv) {
             case '--public-host':
                 publicHost = next();
                 break;
+            case '--experimental-env-var':
+                experimentalEnvVar = next();
+                break;
             default:
                 process.stderr.write(`harness-fe: unknown argument ${a}\n`);
                 process.exit(2);
@@ -137,6 +146,9 @@ function parseArgs(argv) {
     // Data dir defaults to port-keyed path. Explicit env override wins.
     const finalDataDir = process.env.HARNESS_FE_DATA_DIR ?? defaultDataDir(finalPort);
     const finalLabel = process.env.HARNESS_FE_LABEL || undefined;
+    // Omitted → undefined → experimental tools fully on (no gate). Supply a
+    // name only to restrict them to machines where that var is set.
+    const finalExperimentalEnvVar = experimentalEnvVar || process.env.HARNESS_FE_EXPERIMENTAL_ENV_VAR || undefined;
     return {
         host: finalHost,
         port: finalPort,
@@ -146,6 +158,7 @@ function parseArgs(argv) {
         publicHost,
         label: finalLabel,
         dataDir: finalDataDir,
+        experimentalEnvVar: finalExperimentalEnvVar,
     };
 }
 function validate(_cfg) {
@@ -212,7 +225,7 @@ async function main() {
     const { active, shutdown, role } = await startBridgeOrAttach(cfg);
     printBanner(cfg, role, active.getViewerBaseUrl());
     if (cfg.mcpTransport === 'stdio') {
-        await startMcpStdioServer(active);
+        await startMcpStdioServer(active, { experimentalEnvVar: cfg.experimentalEnvVar });
         process.stderr.write('[harness-fe] MCP stdio server connected\n');
     }
     else {
@@ -249,6 +262,7 @@ async function startBridgeOrAttach(cfg) {
         publicHost: cfg.publicHost,
         mcpHttp: cfg.mcpTransport === 'http',
         mcpPath: cfg.mcpPath,
+        experimentalEnvVar: cfg.experimentalEnvVar,
     });
     try {
         await daemon.start();

package/dist/daemon.d.ts

@@ -95,6 +95,13 @@ export interface DaemonOptions {
      * exposing an HTTP MCP endpoint).
      */
     mcpHttp?: boolean;
+    /**
+     * Name of the environment variable that gates experimental (in-testing)
+     * tools. Omit (the default) for fully-on, zero-config. Supply a name only
+     * when the host wants the tools restricted to machines where that var is
+     * set to a non-empty value.
+     */
+    experimentalEnvVar?: string;
 }
 export interface DaemonHandle {
     /**

package/dist/daemon.js

@@ -64,6 +64,7 @@ export function createDaemon(opts = {}) {
                     path: mcpPath,
                     stateful: opts.mcpStateful,
                     eventStore: opts.eventStore,
+                    experimentalEnvVar: opts.experimentalEnvVar,
                 });
             }
         },

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { Bridge, defaultDataDir, type BridgeOptions } from './bridge.js';
 export { createDaemon, type DaemonOptions, type DaemonHandle } from './daemon.js';
 export { SessionRouter, type PeerSession } from './sessionRouter.js';
-export { startMcpStdioServer } from './mcp.js';
+export { startMcpStdioServer, createMcpServer, experimentalEnabled, type McpServerOptions, } from './mcp.js';
 export { startMcpHttpServer, type McpHttpOptions, type McpHttpHandle } from './mcpHttp.js';
 export { JsonlStore, JsonTaskStore, JsonMemoryStore, MemoryEventStore, sanitizeId, type MemoryEventStoreOptions, } from './store/index.js';
 export type { IStore, ITaskStore, IMemoryStore, EventStore, EventId, StreamId, ProjectMeta, ProjectTreeNode, BuildMeta, SessionMeta, TabMeta, } from './store/index.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 export { Bridge, defaultDataDir } from './bridge.js';
 export { createDaemon } from './daemon.js';
 export { SessionRouter } from './sessionRouter.js';
-export { startMcpStdioServer } from './mcp.js';
+export { startMcpStdioServer, createMcpServer, experimentalEnabled, } from './mcp.js';
 export { startMcpHttpServer } from './mcpHttp.js';
 export { JsonlStore, JsonTaskStore, JsonMemoryStore, MemoryEventStore, sanitizeId, } from './store/index.js';

package/dist/mcp.d.ts

@@ -7,9 +7,32 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { IBridge } from './bridge.js';
+export interface McpServerOptions {
+    /**
+     * Name of the environment variable that gates experimental tools.
+     *
+     * **Omit it (the default) and experimental tools are fully on** — no env
+     * var needed, lowest mental burden. Only supply a name when you *don't*
+     * want them unconditionally on: the tools then show up only if that env
+     * var is set to a non-empty value at server-construction time.
+     */
+    experimentalEnvVar?: string;
+}
+/**
+ * Experimental-feature gate.
+ *
+ * Default (no `envVar`): **fully enabled**. Experimental tools are registered
+ * unconditionally, so a plain dev setup gets them with zero config.
+ *
+ * Gated (an `envVar` name supplied): enabled only when that env var is set on
+ * the machine running the daemon. *Presence* enables — any non-empty value
+ * (after trimming) counts as "on"; unset or empty means off. There's
+ * deliberately no required magic value, so `=1`, `=true`, `=yes` all work.
+ */
+export declare function experimentalEnabled(envVar?: string): boolean;
 /**
  * Build an McpServer with every harness-fe tool registered for the given
  * bridge. Transport (stdio / HTTP) is attached separately.
  */
-export declare function createMcpServer(bridge: IBridge): McpServer;
-export declare function startMcpStdioServer(bridge: IBridge): Promise<McpServer>;
+export declare function createMcpServer(bridge: IBridge, options?: McpServerOptions): McpServer;
+export declare function startMcpStdioServer(bridge: IBridge, options?: McpServerOptions): Promise<McpServer>;

package/dist/mcp.js

@@ -15,6 +15,25 @@ import { createReplayExport } from './replayCreate.js';
 import { openBrowser } from './openBrowser.js';
 import { buildDashboardUrl } from './dashboardUrl.js';
 const SERVER_NAME = 'harness-fe';
+/**
+ * Experimental-feature gate.
+ *
+ * Default (no `envVar`): **fully enabled**. Experimental tools are registered
+ * unconditionally, so a plain dev setup gets them with zero config.
+ *
+ * Gated (an `envVar` name supplied): enabled only when that env var is set on
+ * the machine running the daemon. *Presence* enables — any non-empty value
+ * (after trimming) counts as "on"; unset or empty means off. There's
+ * deliberately no required magic value, so `=1`, `=true`, `=yes` all work.
+ */
+export function experimentalEnabled(envVar) {
+    // No gate configured → fully on.
+    if (envVar == null || envVar.trim() === '')
+        return true;
+    // Gated → on only when the named env var carries a non-empty value.
+    const raw = process.env[envVar];
+    return typeof raw === 'string' && raw.trim() !== '';
+}
 const tabIdParam = z
     .string()
     .optional()
@@ -23,12 +42,17 @@ const tabIdParam = z
  * Build an McpServer with every harness-fe tool registered for the given
  * bridge. Transport (stdio / HTTP) is attached separately.
  */
-export function createMcpServer(bridge) {
+export function createMcpServer(bridge, options = {}) {
     const server = new McpServer({
         name: SERVER_NAME,
         version: PROTOCOL_VERSION,
     });
     registerTools(server, bridge);
+    // Experimental tools are on by default. They only get gated when the host
+    // supplies an env-var name to key off; see experimentalEnabled().
+    if (experimentalEnabled(options.experimentalEnvVar)) {
+        registerExperimentalTools(server, bridge);
+    }
     // Register store tools for both leader (direct store access) and follower
     // (proxied via RemoteBridge → mcp.call channel to the leader).
     const leaderStore = bridge.store;
@@ -41,8 +65,8 @@ export function createMcpServer(bridge) {
     }
     return server;
 }
-export async function startMcpStdioServer(bridge) {
-    const server = createMcpServer(bridge);
+export async function startMcpStdioServer(bridge, options = {}) {
+    const server = createMcpServer(bridge, options);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     return server;
@@ -500,6 +524,25 @@ function registerTools(server, bridge) {
         };
     });
 }
+// ─── Experimental tools (gated by HARNESS_FE_EXPERIMENTAL) ────────────────────
+/**
+ * Tools that are still in the testing phase. They are only registered when
+ * `experimentalEnabled()` is true, so default/production setups never see them
+ * in the tool list. When a feature graduates, move its `registerTool` call up
+ * into `registerTools` and drop it from here.
+ */
+function registerExperimentalTools(server, bridge) {
+    // Probe tool: lets a developer confirm experimental mode is active on the
+    // daemon they're connected to. Also serves as the canonical example for how
+    // to add a gated tool. Safe to keep around — it touches nothing.
+    server.registerTool('experimental.ping', {
+        description: 'Experimental-mode probe. Present whenever experimental tools are enabled (the default; ' +
+            'suppressed only when a gate env var is configured and unset on the daemon host). ' +
+            'Returns ok plus the protocol version — use it to confirm experimental tools are reachable.',
+        inputSchema: {},
+    }, async () => ok({ ok: true, experimental: true, protocolVersion: PROTOCOL_VERSION }));
+    void bridge;
+}
 // ─── Store tools (session history, timeline, memory) ──────────────────────────
 function registerStoreTools(server, store, memoryStore, bridge) {
     server.registerTool('session.list', {

package/dist/mcpHttp.d.ts

@@ -25,6 +25,11 @@ export interface McpHttpOptions {
      * disable resumability entirely.
      */
     eventStore?: EventStore | null;
+    /**
+     * Name of the environment variable that gates experimental tools.
+     * Forwarded to `createMcpServer`. Omit for fully-on (no gate).
+     */
+    experimentalEnvVar?: string;
 }
 export interface McpHttpHandle {
     /** Close the MCP server and detach the transport. */

package/dist/mcpHttp.js

@@ -21,7 +21,7 @@ export async function startMcpHttpServer(bridge, opts = {}) {
     const eventStore = opts.eventStore === null
         ? undefined
         : opts.eventStore ?? new MemoryEventStore();
-    const server = createMcpServer(bridge);
+    const server = createMcpServer(bridge, { experimentalEnvVar: opts.experimentalEnvVar });
     const transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: stateful ? () => randomUUID() : undefined,
         eventStore,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-fe/mcp-server",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Unified MCP daemon: stdio MCP for AI agents + WS bridge for Vite plugin and runtime client.",
   "type": "module",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "rrweb-player": "1.0.0-alpha.4",
     "ws": "^8.18.0",
     "zod": "^4.4.3",
-    "@harness-fe/dashboard-ui": "0.2.0",
-    "@harness-fe/protocol": "3.2.0"
+    "@harness-fe/protocol": "3.2.0",
+    "@harness-fe/dashboard-ui": "0.2.0"
   },
   "devDependencies": {
     "@types/ws": "^8.5.10",

package/src/cli.ts

@@ -42,6 +42,8 @@ interface CliConfig {
     label: string | undefined;
     /** Resolved data directory. Defaults to defaultDataDir(port). */
     dataDir: string;
+    /** Env-var name that gates experimental tools. Undefined = fully on (no gate). */
+    experimentalEnvVar: string | undefined;
 }
 
 function printHelpAndExit(): never {
@@ -60,14 +62,19 @@ Options:
   --mcp-path <path>      URL path for the MCP HTTP endpoint. Default /mcp.
   --public-host <addr>   Override the host printed in outbound URLs. Useful when
                          binding 0.0.0.0 and the auto-detected LAN IP is wrong.
+  --experimental-env-var <name>
+                         Restrict experimental (in-testing) tools to machines
+                         where <name> is set to a non-empty value. Omit this and
+                         experimental tools are fully on (the default).
   -h, --help             Show this help.
 
 Environment:
-  HARNESS_FE_HOST           Same as --host
-  HARNESS_FE_TOKEN          Same as --token (use "auto" to generate)
-  HARNESS_FE_MCP_TRANSPORT  Same as --mcp-transport
-  HARNESS_FE_MCP_PATH       Same as --mcp-path
-  HARNESS_FE_URL            Full ws:// URL (legacy; --host/--port override it)
+  HARNESS_FE_HOST                Same as --host
+  HARNESS_FE_TOKEN               Same as --token (use "auto" to generate)
+  HARNESS_FE_MCP_TRANSPORT       Same as --mcp-transport
+  HARNESS_FE_MCP_PATH            Same as --mcp-path
+  HARNESS_FE_EXPERIMENTAL_ENV_VAR  Same as --experimental-env-var
+  HARNESS_FE_URL                 Full ws:// URL (legacy; --host/--port override it)
 `;
     process.stderr.write(help);
     process.exit(0);
@@ -82,6 +89,7 @@ function parseArgs(argv: string[]): CliConfig {
     let mcpTransport: McpTransport | undefined;
     let mcpPath: string | undefined;
     let publicHost: string | undefined;
+    let experimentalEnvVar: string | undefined;
 
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
@@ -126,6 +134,9 @@ function parseArgs(argv: string[]): CliConfig {
             case '--public-host':
                 publicHost = next();
                 break;
+            case '--experimental-env-var':
+                experimentalEnvVar = next();
+                break;
             default:
                 process.stderr.write(`harness-fe: unknown argument ${a}\n`);
                 process.exit(2);
@@ -169,6 +180,11 @@ function parseArgs(argv: string[]): CliConfig {
 
     const finalLabel = process.env.HARNESS_FE_LABEL || undefined;
 
+    // Omitted → undefined → experimental tools fully on (no gate). Supply a
+    // name only to restrict them to machines where that var is set.
+    const finalExperimentalEnvVar =
+        experimentalEnvVar || process.env.HARNESS_FE_EXPERIMENTAL_ENV_VAR || undefined;
+
     return {
         host: finalHost,
         port: finalPort,
@@ -178,6 +194,7 @@ function parseArgs(argv: string[]): CliConfig {
         publicHost,
         label: finalLabel,
         dataDir: finalDataDir,
+        experimentalEnvVar: finalExperimentalEnvVar,
     };
 }
 
@@ -248,7 +265,7 @@ async function main() {
     printBanner(cfg, role, active.getViewerBaseUrl());
 
     if (cfg.mcpTransport === 'stdio') {
-        await startMcpStdioServer(active);
+        await startMcpStdioServer(active, { experimentalEnvVar: cfg.experimentalEnvVar });
         process.stderr.write('[harness-fe] MCP stdio server connected\n');
     } else {
         // HTTP transport: the leader's createDaemon() call already mounted
@@ -290,6 +307,7 @@ async function startBridgeOrAttach(
         publicHost: cfg.publicHost,
         mcpHttp: cfg.mcpTransport === 'http',
         mcpPath: cfg.mcpPath,
+        experimentalEnvVar: cfg.experimentalEnvVar,
     });
     try {
         await daemon.start();

package/src/daemon.ts

@@ -99,6 +99,13 @@ export interface DaemonOptions {
      * exposing an HTTP MCP endpoint).
      */
     mcpHttp?: boolean;
+    /**
+     * Name of the environment variable that gates experimental (in-testing)
+     * tools. Omit (the default) for fully-on, zero-config. Supply a name only
+     * when the host wants the tools restricted to machines where that var is
+     * set to a non-empty value.
+     */
+    experimentalEnvVar?: string;
 }
 
 export interface DaemonHandle {
@@ -164,6 +171,7 @@ export function createDaemon(opts: DaemonOptions = {}): DaemonHandle {
                     path: mcpPath,
                     stateful: opts.mcpStateful,
                     eventStore: opts.eventStore,
+                    experimentalEnvVar: opts.experimentalEnvVar,
                 });
             }
         },

package/src/experimental.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Tests for the experimental-feature gate.
+ *
+ * Default (no gate var named) → experimental tools fully on. Supplying a gate
+ * var name restricts them to machines where that var is set (presence
+ * semantics — any non-empty value enables). Covered at three layers:
+ *   1. experimentalEnabled() — the predicate
+ *   2. createMcpServer() over InMemory transport — registration ↔ listTools
+ *   3. createDaemon() over real HTTP — the full option-threading path
+ *      (daemon → mcpHttp → createMcpServer)
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Bridge } from './bridge.js';
+import { JsonlStore } from './store/index.js';
+import { createMcpServer, experimentalEnabled } from './mcp.js';
+import { createDaemon } from './daemon.js';
+
+const cleanups: Array<() => Promise<void>> = [];
+const TRACKED = ['HARNESS_FE_EXPERIMENTAL', 'CUSTOM_EXP_FLAG'];
+const saved: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+    for (const k of TRACKED) saved[k] = process.env[k];
+});
+
+afterEach(async () => {
+    for (const k of TRACKED) {
+        if (saved[k] === undefined) delete process.env[k];
+        else process.env[k] = saved[k];
+    }
+    while (cleanups.length > 0) await cleanups.pop()!();
+});
+
+async function listToolNames(envVar?: string): Promise<string[]> {
+    const dir = mkdtempSync(join(tmpdir(), 'harness-exp-'));
+    const store = new JsonlStore(dir);
+    const bridge = new Bridge({
+        port: 0,
+        host: '127.0.0.1',
+        store,
+        taskStore: null,
+        autoPurge: { enabled: false },
+    });
+    await bridge.start();
+    const server = createMcpServer(bridge, { experimentalEnvVar: envVar });
+    const [serverTransport, clientTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: 'test-client', version: '0.0.0' }, { capabilities: {} });
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+    cleanups.push(async () => {
+        await client.close();
+        await server.close();
+        await bridge.stop();
+        await store.close();
+    });
+    const { tools } = await client.listTools();
+    return tools.map((t) => t.name);
+}
+
+describe('experimentalEnabled()', () => {
+    it('is fully on when no gate var is configured', () => {
+        expect(experimentalEnabled()).toBe(true);
+        expect(experimentalEnabled('')).toBe(true);
+        expect(experimentalEnabled('   ')).toBe(true);
+    });
+
+    it('is off when the configured gate var is unset/empty', () => {
+        delete process.env.CUSTOM_EXP_FLAG;
+        expect(experimentalEnabled('CUSTOM_EXP_FLAG')).toBe(false);
+        process.env.CUSTOM_EXP_FLAG = '';
+        expect(experimentalEnabled('CUSTOM_EXP_FLAG')).toBe(false);
+        process.env.CUSTOM_EXP_FLAG = '   ';
+        expect(experimentalEnabled('CUSTOM_EXP_FLAG')).toBe(false);
+    });
+
+    it('is on when the configured gate var carries any non-empty value', () => {
+        process.env.CUSTOM_EXP_FLAG = '1';
+        expect(experimentalEnabled('CUSTOM_EXP_FLAG')).toBe(true);
+        process.env.CUSTOM_EXP_FLAG = 'true';
+        expect(experimentalEnabled('CUSTOM_EXP_FLAG')).toBe(true);
+    });
+});
+
+describe('experimental tool gating', () => {
+    it('exposes experimental tools by default (no gate configured)', async () => {
+        const names = await listToolNames();
+        expect(names).toContain('experimental.ping');
+    });
+
+    it('hides experimental tools when a gate var is configured but unset', async () => {
+        delete process.env.CUSTOM_EXP_FLAG;
+        const names = await listToolNames('CUSTOM_EXP_FLAG');
+        expect(names).not.toContain('experimental.ping');
+    });
+
+    it('exposes them again when the configured gate var is set', async () => {
+        process.env.CUSTOM_EXP_FLAG = '1';
+        const names = await listToolNames('CUSTOM_EXP_FLAG');
+        expect(names).toContain('experimental.ping');
+    });
+});
+
+// Proves the option actually threads createDaemon → startMcpHttpServer →
+// createMcpServer over a real HTTP transport, not just the in-process path.
+async function daemonToolNames(experimentalEnvVar?: string): Promise<string[]> {
+    const dir = mkdtempSync(join(tmpdir(), 'harness-exp-daemon-'));
+    const daemon = createDaemon({ port: 0, host: '127.0.0.1', dataDir: dir, experimentalEnvVar });
+    await daemon.start();
+    const port = daemon.getBoundPort();
+    const transport = new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${port}/mcp`));
+    const client = new Client({ name: 'test-client', version: '0.0.0' }, { capabilities: {} });
+    await client.connect(transport);
+    cleanups.push(async () => {
+        await client.close();
+        await daemon.stop();
+        rmSync(dir, { recursive: true, force: true });
+    });
+    const { tools } = await client.listTools();
+    return tools.map((t) => t.name);
+}
+
+describe('experimental tool gating — createDaemon over HTTP', () => {
+    it('exposes experimental tools by default through the daemon', async () => {
+        const names = await daemonToolNames();
+        expect(names).toContain('experimental.ping');
+    });
+
+    it('threads the gate var: hidden when unset, shown when set', async () => {
+        delete process.env.CUSTOM_EXP_FLAG;
+        expect(await daemonToolNames('CUSTOM_EXP_FLAG')).not.toContain('experimental.ping');
+        process.env.CUSTOM_EXP_FLAG = '1';
+        expect(await daemonToolNames('CUSTOM_EXP_FLAG')).toContain('experimental.ping');
+    });
+});

package/src/index.ts

@@ -1,7 +1,12 @@
 export { Bridge, defaultDataDir, type BridgeOptions } from './bridge.js';
 export { createDaemon, type DaemonOptions, type DaemonHandle } from './daemon.js';
 export { SessionRouter, type PeerSession } from './sessionRouter.js';
-export { startMcpStdioServer } from './mcp.js';
+export {
+    startMcpStdioServer,
+    createMcpServer,
+    experimentalEnabled,
+    type McpServerOptions,
+} from './mcp.js';
 export { startMcpHttpServer, type McpHttpOptions, type McpHttpHandle } from './mcpHttp.js';
 export {
     JsonlStore,

package/src/mcp.ts

@@ -34,6 +34,38 @@ import { openBrowser } from './openBrowser.js';
 import { buildDashboardUrl } from './dashboardUrl.js';
 
 const SERVER_NAME = 'harness-fe';
+
+export interface McpServerOptions {
+    /**
+     * Name of the environment variable that gates experimental tools.
+     *
+     * **Omit it (the default) and experimental tools are fully on** — no env
+     * var needed, lowest mental burden. Only supply a name when you *don't*
+     * want them unconditionally on: the tools then show up only if that env
+     * var is set to a non-empty value at server-construction time.
+     */
+    experimentalEnvVar?: string;
+}
+
+/**
+ * Experimental-feature gate.
+ *
+ * Default (no `envVar`): **fully enabled**. Experimental tools are registered
+ * unconditionally, so a plain dev setup gets them with zero config.
+ *
+ * Gated (an `envVar` name supplied): enabled only when that env var is set on
+ * the machine running the daemon. *Presence* enables — any non-empty value
+ * (after trimming) counts as "on"; unset or empty means off. There's
+ * deliberately no required magic value, so `=1`, `=true`, `=yes` all work.
+ */
+export function experimentalEnabled(envVar?: string): boolean {
+    // No gate configured → fully on.
+    if (envVar == null || envVar.trim() === '') return true;
+    // Gated → on only when the named env var carries a non-empty value.
+    const raw = process.env[envVar];
+    return typeof raw === 'string' && raw.trim() !== '';
+}
+
 const tabIdParam = z
     .string()
     .optional()
@@ -43,7 +75,7 @@ const tabIdParam = z
  * Build an McpServer with every harness-fe tool registered for the given
  * bridge. Transport (stdio / HTTP) is attached separately.
  */
-export function createMcpServer(bridge: IBridge): McpServer {
+export function createMcpServer(bridge: IBridge, options: McpServerOptions = {}): McpServer {
     const server = new McpServer({
         name: SERVER_NAME,
         version: PROTOCOL_VERSION,
@@ -51,6 +83,12 @@ export function createMcpServer(bridge: IBridge): McpServer {
 
     registerTools(server, bridge);
 
+    // Experimental tools are on by default. They only get gated when the host
+    // supplies an env-var name to key off; see experimentalEnabled().
+    if (experimentalEnabled(options.experimentalEnvVar)) {
+        registerExperimentalTools(server, bridge);
+    }
+
     // Register store tools for both leader (direct store access) and follower
     // (proxied via RemoteBridge → mcp.call channel to the leader).
     const leaderStore = (bridge as Bridge).store;
@@ -64,8 +102,11 @@ export function createMcpServer(bridge: IBridge): McpServer {
     return server;
 }
 
-export async function startMcpStdioServer(bridge: IBridge): Promise<McpServer> {
-    const server = createMcpServer(bridge);
+export async function startMcpStdioServer(
+    bridge: IBridge,
+    options: McpServerOptions = {},
+): Promise<McpServer> {
+    const server = createMcpServer(bridge, options);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     return server;
@@ -786,6 +827,32 @@ function registerTools(server: McpServer, bridge: IBridge): void {
     );
 }
 
+// ─── Experimental tools (gated by HARNESS_FE_EXPERIMENTAL) ────────────────────
+
+/**
+ * Tools that are still in the testing phase. They are only registered when
+ * `experimentalEnabled()` is true, so default/production setups never see them
+ * in the tool list. When a feature graduates, move its `registerTool` call up
+ * into `registerTools` and drop it from here.
+ */
+function registerExperimentalTools(server: McpServer, bridge: IBridge): void {
+    // Probe tool: lets a developer confirm experimental mode is active on the
+    // daemon they're connected to. Also serves as the canonical example for how
+    // to add a gated tool. Safe to keep around — it touches nothing.
+    server.registerTool(
+        'experimental.ping',
+        {
+            description:
+                'Experimental-mode probe. Present whenever experimental tools are enabled (the default; ' +
+                'suppressed only when a gate env var is configured and unset on the daemon host). ' +
+                'Returns ok plus the protocol version — use it to confirm experimental tools are reachable.',
+            inputSchema: {},
+        },
+        async () => ok({ ok: true, experimental: true, protocolVersion: PROTOCOL_VERSION }),
+    );
+    void bridge;
+}
+
 // ─── Store tools (session history, timeline, memory) ──────────────────────────
 
 function registerStoreTools(server: McpServer, store: IStore, memoryStore: IMemoryStore, bridge: IBridge): void {

package/src/mcpHttp.ts

@@ -32,6 +32,11 @@ export interface McpHttpOptions {
      * disable resumability entirely.
      */
     eventStore?: EventStore | null;
+    /**
+     * Name of the environment variable that gates experimental tools.
+     * Forwarded to `createMcpServer`. Omit for fully-on (no gate).
+     */
+    experimentalEnvVar?: string;
 }
 
 export interface McpHttpHandle {
@@ -56,7 +61,7 @@ export async function startMcpHttpServer(
             ? undefined
             : opts.eventStore ?? new MemoryEventStore();
 
-    const server = createMcpServer(bridge);
+    const server = createMcpServer(bridge, { experimentalEnvVar: opts.experimentalEnvVar });
     const transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: stateful ? () => randomUUID() : undefined,
         eventStore,