@ductape/mcp 0.1.59 → 0.1.61

package/dist/index.js

@@ -723,47 +723,10 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   vector.count          [{ product, env, vector, namespace? }]
 
 ━━━ MODULE: features ━━━
-  features.create  [product_tag, data: {
-    tag: string,
-    name: string,
-    description?: string,
-
-    // INPUT SCHEMA (top-level): declares what fields this feature accepts when executed at runtime.
-    // These are the fields callers will pass to features.execute / features.dispatch.
-    // Construct this yourself — it is a schema declaration, not a runtime value.
-    input?: { fieldName: { type: string, required?: boolean } },
-
-    output?: object,
-    envs?: [{ slug: string, active?: boolean }],
-    steps: [
-      {
-        tag: string,              // unique step id
-        name?: string,
-        type: "action"|"database"|"graph"|"notification"|"storage"|"publish"|"feature"|"sleep"|"wait_signal",
-        app?: string,             // for type=action
-        event?: string,           // action/event tag
-        database?: string,        // for type=database
-        graph?: string,           // for type=graph
-        notification?: string,    // for type=notification
-        storage?: string,         // for type=storage
-        broker?: string,          // for type=publish
-        feature?: string,         // for type=feature (child feature)
-
-        // STEP INPUT: maps this feature's declared input fields (or prior step outputs) → the step's underlying action/event fields.
-        // ← CALL ductape_generate_payload (operation_family matching step type, method="run", targets={app/event/database/etc.})
-        //   to discover what fields the target accepts, then wire them with "$Input{fieldName}" or "$Step{stepTag}{field}" references.
-        input?: { "body:field": "$Input{fieldName}" | "$Step{stepTag}{field}" | literal },
-
-        condition?: string,       // e.g. "$Step{validate}{valid} == true"
-        dependsOn?: string[],
-        options?: { retries?: number, timeout?: number, allow_fail?: boolean, critical?: boolean }
-      }
-    ]
-  }]
-  features.update  [product_tag, feature_tag, data: { name?: string, description?: string, steps?: array, envs?: array }]
+  Feature definitions are code-first. Use features.define in application source; do not call
+  administrative create/update/delete methods through ductape_execute.
   features.fetch   [product_tag, feature_tag]
   features.fetchAll [product_tag]
-  features.delete  [product_tag, feature_tag]
 
   features.define  [{
     product?: string,
@@ -977,12 +940,13 @@ const payloadGenerateInputSchema = z.object({
         'For quotas/fallbacks: { tag: "resource_tag" }. ' +
         'For storage: { storage: "storage_tag" }. ' +
         'For messaging: { broker: "broker_tag", topic?: "topic_tag" }.'),
-    include_session: z.boolean().optional().default(true).describe('Include a session placeholder inside the generated input object. ' +
+    include_session: z.boolean().optional().describe('Include a session placeholder inside the generated input object. ' +
+        'Defaults to false for execution_context="system" and true otherwise. ' +
         'The placeholder is named "<session_tag_token>" to indicate it expects the runtime JWT, not the tag name.'),
     execution_context: z.enum(['user', 'delegated', 'system']).optional().default('user').describe('Actor intent for this runtime operation. "user" means an active request initiated by the authenticated user; ' +
         '"delegated" means work acting on behalf of a user with a short-lived delegated identity or application-owned ' +
         'immutable actor context; "system" means intentionally unattributed background work. This drives session warnings.'),
-    include_cache: z.boolean().optional().default(true).describe('Include the cache tag inside the generated input object so the caller knows which cache to reference for this query.'),
+    include_cache: z.boolean().optional().describe('Include a cache tag inside the generated payload. Defaults to false; set true only when the runtime call should use cache explicitly.'),
     schema_mode: z.enum(['strict', 'best_effort']).optional().default('best_effort').describe('"strict" — fail if any required field cannot be resolved. ' +
         '"best_effort" — fill what is known, leave unknowns as null/placeholder. Use best_effort when exploring.'),
     input_hint: z.record(z.any()).optional().describe('Optional. Partial input values you already know. These are merged into the generated payload template ' +
@@ -1084,7 +1048,7 @@ function addSessionAwarenessMetadata(generated, args) {
     const acceptsSession = operationAcceptsSession(args.operation_family, args.method);
     const executionContext = args.execution_context ?? 'user';
     const payloadHasSession = Boolean(generated?.payload?.session || generated?.payload?.input?.session);
-    const sessionRequested = args.include_session !== false;
+    const sessionRequested = args.include_session ?? executionContext !== 'system';
     const warnings = [];
     if (acceptsSession && executionContext !== 'system' && (!sessionRequested || !payloadHasSession)) {
         warnings.push(`Session attribution is missing for a ${executionContext}-context operation. ` +
@@ -1178,7 +1142,12 @@ const ADMIN_SUBCOMMANDS = [
 ];
 function checkCli() {
     try {
-        const out = execSync('ductape --version', { encoding: 'utf8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        const out = execSync('ductape --version', {
+            encoding: 'utf8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: cliEnvironment(),
+        }).trim();
         return { available: true, version: out || 'unknown' };
     }
     catch {
@@ -1194,6 +1163,7 @@ function checkLoginState() {
             encoding: 'utf8',
             timeout: 10000,
             stdio: ['pipe', 'pipe', 'pipe'],
+            env: cliEnvironment(),
         });
         authState = 'ok';
         return 'ok';
@@ -1209,7 +1179,12 @@ function syncWorkspace() {
     if (!target)
         return;
     try {
-        execSync(`ductape workspaces use "${target}"`, { encoding: 'utf8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'] });
+        execSync(`ductape workspaces use "${target}"`, {
+            encoding: 'utf8',
+            timeout: 10000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: cliEnvironment(),
+        });
     }
     catch {
         // best-effort; if it fails the user will see workspace-mismatch errors on subsequent commands
@@ -1236,6 +1211,7 @@ function runCli(command) {
             // instead of this wrapper killing the CLI first and reducing it to "(no data)".
             timeout: 90000,
             stdio: ['pipe', 'pipe', 'pipe'],
+            env: cliEnvironment(),
         });
         return { success: true, output: output.trim() };
     }
@@ -1279,6 +1255,16 @@ function runCli(command) {
         return { success: false, output: msg };
     }
 }
+/**
+ * MCP is publishable-key-only. The standalone CLI may manage its own access-key
+ * credentials, but an access key present in the MCP host environment is never
+ * forwarded into CLI subprocesses.
+ */
+function cliEnvironment() {
+    const environment = { ...process.env };
+    delete environment.DUCTAPE_ACCESS_KEY;
+    return environment;
+}
 const docsInputSchema = z.object({
     topic: z.string().describe('Feature topic to look up. Supported: ' +
         'transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
@@ -3870,7 +3856,8 @@ async function main() {
             }
             const key = args.publishable_key || process.env.DUCTAPE_PUBLISHABLE_KEY;
             if (!key) {
-                throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
+                throw new Error('Runtime authentication is missing. Set DUCTAPE_PUBLISHABLE_KEY in the MCP server environment ' +
+                    'or pass publishable_key to ductape_execute. The MCP server never accepts access keys.');
             }
             // The TS SDK uses ductape.events.* for broker operations; the backend proxy uses messageBrokers.
             const proxyModule = args.module === 'events' ? 'messageBrokers' : args.module;
@@ -3893,7 +3880,18 @@ async function main() {
                     return p;
                 });
             }
-            const result = await executeViaProxy(key, proxyModule, args.method, params);
+            let result;
+            try {
+                result = await executeViaProxy(key, proxyModule, args.method, params);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (/authentication failed|unauthorized|invalid.*key/i.test(message)) {
+                    throw new Error('The DUCTAPE_PUBLISHABLE_KEY was rejected by the runtime proxy. ' +
+                        'Use a publishable key for the same workspace/product. The MCP server never accepts or forwards access keys.');
+                }
+                throw error;
+            }
             return { content: [{ type: 'text', text: JSON.stringify(result ?? null, null, 2) }] };
         }
         catch (err) {
@@ -3914,7 +3912,8 @@ async function main() {
             if (!key) {
                 throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
             }
-            const result = addSessionAwarenessMetadata(await generateExecutablePayload({ ...args, publishable_key: key }), args);
+            const includeSession = args.include_session ?? args.execution_context !== 'system';
+            const result = addSessionAwarenessMetadata(await generateExecutablePayload({ ...args, include_session: includeSession, publishable_key: key }), args);
             let text = JSON.stringify(result ?? null, null, 2);
             if (args.operation_family === 'database') {
                 const meta = result?.meta ?? {};
@@ -3941,7 +3940,8 @@ async function main() {
                 throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
             }
             ensureSupportedSnippetOperation(args.operation_family, args.method);
-            const generated = addSessionAwarenessMetadata(await generateExecutablePayload({ ...args, publishable_key: key }), args);
+            const includeSession = args.include_session ?? args.execution_context !== 'system';
+            const generated = addSessionAwarenessMetadata(await generateExecutablePayload({ ...args, include_session: includeSession, publishable_key: key }), args);
             const payload = generated?.payload ?? {};
             const snippet = buildSnippet(args.language, payload, args.operation_family, args.method);
             return {

package/dist/proxy-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy-client.d.ts","sourceRoot":"","sources":["../src/proxy-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,YAAY,4BAA4B,CAAC;AAEtD,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,KAAK,GACL,WAAW,GACX,OAAO,GACP,UAAU,GACV,eAAe,GACf,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,SAAS,GACT,UAAU,GACV,MAAM,GACN,MAAM,GACN,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,SAAS,CAAC;AAUd;;GAEG;AACH,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAC/C,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,CAAC,CAAC,CAuBZ;AAED,MAAM,WAAW,iCAAiC;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACpD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,kCAAkC;IACjD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AASD,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYvE;AA4BD,wBAAsB,yBAAyB,CAAC,CAAC,GAAG,kCAAkC,EACpF,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,CAAC,CAAC,CA8BZ"}
+{"version":3,"file":"proxy-client.d.ts","sourceRoot":"","sources":["../src/proxy-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,YAAY,4BAA4B,CAAC;AAEtD,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,KAAK,GACL,WAAW,GACX,OAAO,GACP,UAAU,GACV,eAAe,GACf,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,SAAS,GACT,UAAU,GACV,MAAM,GACN,MAAM,GACN,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,SAAS,CAAC;AAUd;;GAEG;AACH,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAC/C,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,CAAC,CAAC,CAuBZ;AAED,MAAM,WAAW,iCAAiC;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACpD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,kCAAkC;IACjD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AASD,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYvE;AA4BD,wBAAsB,yBAAyB,CAAC,CAAC,GAAG,kCAAkC,EACpF,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,CAAC,CAAC,CAiCZ"}

package/dist/proxy-client.js

@@ -14,7 +14,7 @@ export async function executeViaProxy(publishable_key, module, method, params =
         },
         body: JSON.stringify({
             publishable_key,
-            module,
+            module: module === 'features' ? 'feature' : module,
             method,
             params,
         }),
@@ -73,6 +73,9 @@ export async function generateExecutablePayload(request) {
     const { execution_context: _executionContext, ...backendRequest } = request;
     const normalizedRequest = {
         ...backendRequest,
+        operation_family: backendRequest.operation_family.toLowerCase() === 'features'
+            ? 'feature'
+            : backendRequest.operation_family,
         targets: backendRequest.targets
             ? normalizeTargets(backendRequest.targets)
             : backendRequest.targets,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.1.59",
+  "version": "0.1.61",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",

package/scripts/check-frontend-analytics-guidance.mjs

@@ -6,6 +6,17 @@ import { dirname, resolve } from 'node:path';
 const here = dirname(fileURLToPath(import.meta.url));
 const source = readFileSync(resolve(here, '../src/index.ts'), 'utf8');
 
+assert.doesNotMatch(
+  source,
+  /(?:const|let|var)\s+\w+\s*=\s*process\.env\.DUCTAPE_ACCESS_KEY/,
+  'MCP server must never read DUCTAPE_ACCESS_KEY',
+);
+assert.match(
+  source,
+  /delete environment\.DUCTAPE_ACCESS_KEY/,
+  'MCP CLI subprocess environment must strip DUCTAPE_ACCESS_KEY',
+);
+
 const checks = [
   ['dedicated docs topic', /'frontend-analytics': `/],
   ['anonymous analytics without an invented session', /Before login:[\s\S]*do not invent a session/i],

package/src/index.ts

@@ -734,47 +734,10 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   vector.count          [{ product, env, vector, namespace? }]
 
 ━━━ MODULE: features ━━━
-  features.create  [product_tag, data: {
-    tag: string,
-    name: string,
-    description?: string,
-
-    // INPUT SCHEMA (top-level): declares what fields this feature accepts when executed at runtime.
-    // These are the fields callers will pass to features.execute / features.dispatch.
-    // Construct this yourself — it is a schema declaration, not a runtime value.
-    input?: { fieldName: { type: string, required?: boolean } },
-
-    output?: object,
-    envs?: [{ slug: string, active?: boolean }],
-    steps: [
-      {
-        tag: string,              // unique step id
-        name?: string,
-        type: "action"|"database"|"graph"|"notification"|"storage"|"publish"|"feature"|"sleep"|"wait_signal",
-        app?: string,             // for type=action
-        event?: string,           // action/event tag
-        database?: string,        // for type=database
-        graph?: string,           // for type=graph
-        notification?: string,    // for type=notification
-        storage?: string,         // for type=storage
-        broker?: string,          // for type=publish
-        feature?: string,         // for type=feature (child feature)
-
-        // STEP INPUT: maps this feature's declared input fields (or prior step outputs) → the step's underlying action/event fields.
-        // ← CALL ductape_generate_payload (operation_family matching step type, method="run", targets={app/event/database/etc.})
-        //   to discover what fields the target accepts, then wire them with "$Input{fieldName}" or "$Step{stepTag}{field}" references.
-        input?: { "body:field": "$Input{fieldName}" | "$Step{stepTag}{field}" | literal },
-
-        condition?: string,       // e.g. "$Step{validate}{valid} == true"
-        dependsOn?: string[],
-        options?: { retries?: number, timeout?: number, allow_fail?: boolean, critical?: boolean }
-      }
-    ]
-  }]
-  features.update  [product_tag, feature_tag, data: { name?: string, description?: string, steps?: array, envs?: array }]
+  Feature definitions are code-first. Use features.define in application source; do not call
+  administrative create/update/delete methods through ductape_execute.
   features.fetch   [product_tag, feature_tag]
   features.fetchAll [product_tag]
-  features.delete  [product_tag, feature_tag]
 
   features.define  [{
     product?: string,
@@ -1000,8 +963,9 @@ const payloadGenerateInputSchema = z.object({
     'For storage: { storage: "storage_tag" }. ' +
     'For messaging: { broker: "broker_tag", topic?: "topic_tag" }.'
   ),
-  include_session: z.boolean().optional().default(true).describe(
+  include_session: z.boolean().optional().describe(
     'Include a session placeholder inside the generated input object. ' +
+    'Defaults to false for execution_context="system" and true otherwise. ' +
     'The placeholder is named "<session_tag_token>" to indicate it expects the runtime JWT, not the tag name.'
   ),
   execution_context: z.enum(['user', 'delegated', 'system']).optional().default('user').describe(
@@ -1009,8 +973,8 @@ const payloadGenerateInputSchema = z.object({
     '"delegated" means work acting on behalf of a user with a short-lived delegated identity or application-owned ' +
     'immutable actor context; "system" means intentionally unattributed background work. This drives session warnings.'
   ),
-  include_cache: z.boolean().optional().default(true).describe(
-    'Include the cache tag inside the generated input object so the caller knows which cache to reference for this query.'
+  include_cache: z.boolean().optional().describe(
+    'Include a cache tag inside the generated payload. Defaults to false; set true only when the runtime call should use cache explicitly.'
   ),
   schema_mode: z.enum(['strict', 'best_effort']).optional().default('best_effort').describe(
     '"strict" — fail if any required field cannot be resolved. ' +
@@ -1119,7 +1083,7 @@ function addSessionAwarenessMetadata(
   const acceptsSession = operationAcceptsSession(args.operation_family, args.method);
   const executionContext = args.execution_context ?? 'user';
   const payloadHasSession = Boolean(generated?.payload?.session || generated?.payload?.input?.session);
-  const sessionRequested = args.include_session !== false;
+  const sessionRequested = args.include_session ?? executionContext !== 'system';
   const warnings: string[] = [];
 
   if (acceptsSession && executionContext !== 'system' && (!sessionRequested || !payloadHasSession)) {
@@ -1240,7 +1204,12 @@ const ADMIN_SUBCOMMANDS = [
 
 function checkCli(): { available: boolean; version?: string } {
   try {
-    const out = execSync('ductape --version', { encoding: 'utf8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    const out = execSync('ductape --version', {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: cliEnvironment(),
+    }).trim();
     return { available: true, version: out || 'unknown' };
   } catch {
     return { available: false };
@@ -1256,6 +1225,7 @@ function checkLoginState(): 'ok' | 'none' {
       encoding: 'utf8',
       timeout: 10000,
       stdio: ['pipe', 'pipe', 'pipe'],
+      env: cliEnvironment(),
     });
     authState = 'ok';
     return 'ok';
@@ -1270,7 +1240,12 @@ function syncWorkspace(): void {
   workspaceSynced = true; // mark done regardless so we don't retry on every call
   if (!target) return;
   try {
-    execSync(`ductape workspaces use "${target}"`, { encoding: 'utf8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'] });
+    execSync(`ductape workspaces use "${target}"`, {
+      encoding: 'utf8',
+      timeout: 10000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: cliEnvironment(),
+    });
   } catch {
     // best-effort; if it fails the user will see workspace-mismatch errors on subsequent commands
   }
@@ -1297,6 +1272,7 @@ function runCli(command: string): { success: boolean; output: string } {
       // instead of this wrapper killing the CLI first and reducing it to "(no data)".
       timeout: 90000,
       stdio: ['pipe', 'pipe', 'pipe'],
+      env: cliEnvironment(),
     });
     return { success: true, output: output.trim() };
   } catch (err: any) {
@@ -1340,6 +1316,17 @@ function runCli(command: string): { success: boolean; output: string } {
   }
 }
 
+/**
+ * MCP is publishable-key-only. The standalone CLI may manage its own access-key
+ * credentials, but an access key present in the MCP host environment is never
+ * forwarded into CLI subprocesses.
+ */
+function cliEnvironment(): NodeJS.ProcessEnv {
+  const environment = { ...process.env };
+  delete environment.DUCTAPE_ACCESS_KEY;
+  return environment;
+}
+
 const docsInputSchema = z.object({
   topic: z.string().describe(
     'Feature topic to look up. Supported: ' +
@@ -3985,7 +3972,10 @@ async function main() {
       }
       const key = args.publishable_key || process.env.DUCTAPE_PUBLISHABLE_KEY;
       if (!key) {
-        throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
+        throw new Error(
+          'Runtime authentication is missing. Set DUCTAPE_PUBLISHABLE_KEY in the MCP server environment ' +
+          'or pass publishable_key to ductape_execute. The MCP server never accepts access keys.',
+        );
       }
       // The TS SDK uses ductape.events.* for broker operations; the backend proxy uses messageBrokers.
       const proxyModule: SDKModule = args.module === 'events' ? 'messageBrokers' : args.module;
@@ -4010,7 +4000,19 @@ async function main() {
         });
       }
 
-      const result = await executeViaProxy(key, proxyModule, args.method, params);
+      let result: unknown;
+      try {
+        result = await executeViaProxy(key, proxyModule, args.method, params);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (/authentication failed|unauthorized|invalid.*key/i.test(message)) {
+          throw new Error(
+            'The DUCTAPE_PUBLISHABLE_KEY was rejected by the runtime proxy. ' +
+            'Use a publishable key for the same workspace/product. The MCP server never accepts or forwards access keys.',
+          );
+        }
+        throw error;
+      }
       return { content: [{ type: 'text', text: JSON.stringify(result ?? null, null, 2) }] };
     } catch (err) {
       let message = err instanceof Error ? err.message : String(err);
@@ -4033,8 +4035,9 @@ async function main() {
       if (!key) {
         throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
       }
+      const includeSession = args.include_session ?? args.execution_context !== 'system';
       const result = addSessionAwarenessMetadata(
-        await generateExecutablePayload({ ...args, publishable_key: key }),
+        await generateExecutablePayload({ ...args, include_session: includeSession, publishable_key: key }),
         args,
       );
 
@@ -4068,8 +4071,9 @@ async function main() {
         throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
       }
       ensureSupportedSnippetOperation(args.operation_family, args.method);
+      const includeSession = args.include_session ?? args.execution_context !== 'system';
       const generated = addSessionAwarenessMetadata(
-        await generateExecutablePayload({ ...args, publishable_key: key }),
+        await generateExecutablePayload({ ...args, include_session: includeSession, publishable_key: key }),
         args,
       );
       const payload = (generated as any)?.payload ?? {};

package/src/proxy-client.ts

@@ -52,7 +52,7 @@ export async function executeViaProxy<T = unknown>(
     },
     body: JSON.stringify({
       publishable_key,
-      module,
+      module: module === 'features' ? 'feature' : module,
       method,
       params,
     }),
@@ -143,6 +143,9 @@ export async function generateExecutablePayload<T = IGenerateExecutablePayloadRe
   const { execution_context: _executionContext, ...backendRequest } = request;
   const normalizedRequest = {
     ...backendRequest,
+    operation_family: backendRequest.operation_family.toLowerCase() === 'features'
+      ? 'feature'
+      : backendRequest.operation_family,
     targets: backendRequest.targets
       ? normalizeTargets(backendRequest.targets as Record<string, unknown>)
       : backendRequest.targets,