@ductape/mcp 0.2.21 → 0.2.23

package/dist/index.js

@@ -90,12 +90,15 @@ There are THREE categories of operations. Use the right tool for each:
        These require an access key and CANNOT be done via ductape_execute (publishable key only).
        → Use ductape_cli instead. Examples:
            ductape_cli("products list")
-           ductape_cli("products create --name \\"My Product\\" --tag my-product")
+           ductape_cli("products create -f product.json")   # body: { name, tag?, envs?: [...] } — no --name/--tag flags exist, only -f <file.json> or interactive TTY
            ductape_cli("cloud connections list")
            ductape_cli("link --product my-product --env dev")
        If the CLI is not installed, ductape_cli will return install instructions automatically.
-       NOTE: App actions are configured in the Workbench UI — there is no CLI command for them.
        Environments DO have CLI commands: ductape_cli("products environments list/get/create/update ...").
+       App actions (endpoints) also have CLI commands: ductape_cli("apps actions list/get/create/update/delete
+       --app <app_tag> ..."). When the user wants to integrate a new endpoint, call
+       ductape_integrate_endpoint first — it returns the full ordered flow (choose/create the app,
+       define the action, connect the app to the product) before any code should be written.
 
        RESOLVING "No linked project" ERRORS:
        Some commands (declarative sync below, db migrate/schema, products environments *) need a
@@ -194,16 +197,27 @@ There are THREE categories of operations. Use the right tool for each:
   1. ASSET CREATION / UPDATE  (create, update, add, register… for ANY asset type)
        ALL creation and update operations require an access key and CANNOT go through ductape_execute.
        → Use ductape_cli for every create/update operation. Examples:
-           ductape_cli("apps create --name \\"Email Service\\" --description \\"Transactional email\\"")
+           ductape_cli("apps create -f app.json")   # no --name/--description flags exist, only -f <file.json> or interactive TTY. body: { app_name, description, tag, envs?: [{ env_name, slug, description, base_url, active }] } — tag is REQUIRED.
            ductape_cli("apps list")
            ductape_cli("resources storage list")
            ductape_cli("resources database create -f db-config.json")
        This applies to: products, apps, and resources (databases, storage, caches, etc.),
        cloud connections, and secrets. Environments have their own CLI commands (see below);
-       App actions and auths are configured in the Workbench UI. Quotas, fallbacks, jobs, and
+       app actions have their own CLI commands too — ductape_cli("apps actions create --app <tag>
+       --action-file action.json") (NOT -f — that flag is claimed by the parent "apps" command, so
+       Commander resolves it against the ancestor and this subcommand never sees it; same fix as
+       "products environments create/update" uses --env-file for the identical reason). Body: {
+       tag, name, resource, method, request_type, description?, params?, query?, headers?, body?,
+       response? }, where resource is a path RELATIVE to each of the app's environment base_urls
+       (e.g. "/v1/users/{id}"), not a full URL, and request_type is REQUIRED — one of
+       "application/json" | "application/x-www-form-urlencoded" | "multipart/form-data" | "SOAP" |
+       "html" (not the short names "json"/"xml"/"form"). Auths are still configured
+       in the Workbench UI. Quotas, fallbacks, jobs, and
        healthchecks are administrative resources managed with ductape_cli("resources <type> ...").
        Features have no CLI create command because their definitions are code-first through
-       features.define.
+       features.define. They DO have a CLI persistence command — ductape_cli("features sync") —
+       which runs the project's own "features:sync" npm script to register ductape/features/
+       definitions against the live product; see the DEPLOYING features.define CALLS section below.
 
        ⚠ MULTI-ENV REQUIREMENT — applies to ALL product assets (storage, database, cache,
        messageBroker, graph, vector, and any other resource with an envs array):
@@ -468,8 +482,26 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   app.init      [app_tag]
 
 ━━━ MODULE: actions (app actions) ━━━
-  actions.create  [app_tag, data: { tag: string, name: string, resource: string, method: "GET"|"POST"|"PUT"|"PATCH"|"DELETE", description?: string, body?: object, params?: object, query?: object, headers?: object, response?: { name?: string, status_code: number, success: boolean, body: object, response_format: "json"|"xml"|"form" } }]
-  actions.update  [app_tag, action_tag, data: { resource?: string, method?: "GET"|"POST"|"PUT"|"PATCH"|"DELETE", description?: string, request_type?: "json"|"xml"|"form", body?: object, query?: object, params?: object, headers?: object, response?: { name?: string, success: boolean, body: object, response_format: "json"|"xml"|"form", status_code: number } }]
+  These are admin ops — go through ductape_cli, not ductape_execute:
+    ductape_cli("apps actions create --app <app_tag> --action-file action.json")
+    ductape_cli("apps actions update --app <app_tag> --action <action_tag> --action-file action.json")
+    ductape_cli("apps actions list --app <app_tag> --json")
+    ductape_cli("apps actions get --app <app_tag> --action <action_tag> --json")
+    ductape_cli("apps actions delete --app <app_tag> --action <action_tag>")
+  NOTE: the flag is --action-file, NOT -f/--file — that flag belongs to the parent "apps" command
+  (used by "apps create"/"apps update"), and Commander resolves a flag shared by an ancestor and a
+  descendant against the ancestor, so -f here would silently never reach this subcommand. Verified
+  live: passing -f prints "required option '-f, --file <path>' not specified" even though it was
+  supplied; --action-file is the fix (same pattern already used by "products environments
+  create/update" with --env-file for the identical collision).
+  resource is a path RELATIVE to each of the app's environment base_urls (e.g. "/v1/users/{id}"),
+  never a full URL — Ductape joins base_url + resource per environment at call time.
+  request_type is REQUIRED (verified live) — one of "application/json" |
+  "application/x-www-form-urlencoded" | "multipart/form-data" | "SOAP" | "html". response.status_code
+  is a STRING enum of standard HTTP status codes (e.g. "200", not the number 200) and
+  response.response_format uses the SAME enum as request_type above (not "json"/"xml"/"form").
+  actions.create  [app_tag, data: { tag: string, name: string, resource: string, method: "GET"|"POST"|"PUT"|"PATCH"|"DELETE", request_type: "application/json"|"application/x-www-form-urlencoded"|"multipart/form-data"|"SOAP"|"html", description?: string, body?: object, params?: object, query?: object, headers?: object, response?: { name?: string, status_code: string, success: boolean, body: object, response_format: "application/json"|"application/x-www-form-urlencoded"|"multipart/form-data"|"SOAP"|"html" } }]
+  actions.update  [app_tag, action_tag, data: { resource?: string, method?: "GET"|"POST"|"PUT"|"PATCH"|"DELETE", description?: string, request_type?: "application/json"|"application/x-www-form-urlencoded"|"multipart/form-data"|"SOAP"|"html", body?: object, query?: object, params?: object, headers?: object, response?: { name?: string, success: boolean, body: object, response_format: "application/json"|"application/x-www-form-urlencoded"|"multipart/form-data"|"SOAP"|"html", status_code: string } }]
   actions.fetch   [app_tag, action_tag]
   actions.list    [app_tag]
   actions.run     [{ product, env, app, action, input: { "body:fieldName": value, ... } }]  ← CALL ductape_generate_payload FIRST (operation_family="action", method="run", targets={app, action})
@@ -1110,6 +1142,11 @@ const marketplaceConnectInputSchema = z.object({
 const marketplaceInspectInputSchema = z.object({
     app_tag: z.string().min(1).describe('Exact public app tag returned by ductape_marketplace_discover.'),
 });
+const integrateEndpointInputSchema = z.object({
+    product_tag: z.string().min(1).optional().describe('Target product tag, if already known. Omit if the user has not said which product this is for yet.'),
+    app_tag: z.string().min(1).optional().describe('Existing app tag, if the user already said which app this endpoint belongs to. Omit when creating ' +
+        'a new app, or when the app has not been chosen yet — the returned flow starts by asking.'),
+});
 function toPrettyJson(value) {
     return JSON.stringify(value ?? {}, null, 2);
 }
@@ -1679,6 +1716,15 @@ PRIMITIVES-FIRST CAPABILITY EXTRACTION — REQUIRED FOR EVERY MIGRATION SLICE
     5. For each Function, record pure/WASM-candidate versus framework-dependent classification.
     6. Call ductape_function_setup and implement verified local plus remote availability.
 
+  Persist migrated Features the same way as newly designed ones: define every Feature under
+  ductape/features/ (e.g. ductape/features/src/my-feature.ts), never inline in the app's normal
+  startup path. Register only local function/operation handlers (ductape.sdk.functions.register(...))
+  at boot — no network call. Persist Feature definitions to the live product with
+  "ductape features sync" (ductape_cli("features sync")), which runs the project's own
+  "features:sync" npm script — never automatically on app boot, the same way a migrated database
+  schema is applied via "ductape db migrate" rather than at startup. See "DEPLOYING features.define
+  CALLS" below for the full convention and required "features:sync" script shape.
+
   Never create a Function that merely hides database, session, Events, storage, notification, graph,
   vector, quota, fallback, healthcheck, cache, secret, or connected-App work that the Feature can
   express directly. Never fragment an original atomic transaction just to maximize primitive count.
@@ -1742,6 +1788,17 @@ ENVIRONMENTS
   Report matched, missing, extra, and ambiguous normalized aliases. Never guess an ambiguous mapping.
   Environment mutation is administrative CLI work and must never be routed through ductape_execute.
 
+  INACTIVE ENVIRONMENTS (e.g. an auto-created "snd"): whether an inactive environment needs a real
+  physical provider resource behind it, or can stay a placeholder with no live infrastructure, is
+  not settled platform behavior — do not assume either way. Resource-create payloads that require
+  complete environment coverage (see above) still need an entry for every environment returned by
+  "products environments list", active or not; whether that entry must point at a real backing
+  resource for an inactive env is a product-owner decision to surface explicitly, not infer.
+  Separately: "products environments update <product> <slug>" with {"active":false} may report
+  "updated": true without the change actually persisting — confirmed via independent read-back,
+  not just replication lag. If deactivating an environment is important, verify with a follow-up
+  "products environments get" rather than trusting the update response.
+
 PRODUCT AND ASSET BOOTSTRAP
   Product creation is idempotent: fetch by tag, create only when absent, then link the destination.
   Use ductape_cli for products, apps, resources, cloud connections, secrets, apply, and migrations.
@@ -1798,6 +1855,8 @@ COMPONENT DECISIONS
   Pinecone/Qdrant/Weaviate/OpenSearch → Vector; JWT/session middleware → Sessions.
   Named reusable product capabilities with a stable managed-execution boundary → code-first Features,
   including synchronous multi-step capabilities and durable/scheduled/signal-driven orchestration.
+  Define Features under ductape/features/ and persist them via "ductape features sync", never at
+  app boot — see PRIMITIVES-FIRST CAPABILITY EXTRACTION above.
   Retries, health checks, fallbacks, quotas, circuit breakers → Resilience.
   Keep low-level deterministic rules as ordinary domain functions when they do not form a useful
   independent capability boundary. Wrap or compose them into Features when the combined operation
@@ -1841,8 +1900,10 @@ AI EDITING STANDARD
   rules in code, while allowing a coherent synchronous capability composed from those rules to be a Feature.
   Immediate work propagates the full session; durable work uses approved actor metadata or system context.
   Consumers are idempotent, retry ownership is singular and bounded, and external effects are not duplicated.
-  After each slice: format, build, test, rescan, reconcile assets through ductape_cli, smoke-test in snd,
-  and report unresolved findings. A clean scanner result alone never proves a correct migration.
+  After each slice: format, build, test, rescan, persist any migrated Feature definitions via
+  ductape_cli("features sync") (never automatically on app boot), reconcile assets through
+  ductape_cli, smoke-test in snd, and report unresolved findings. A clean scanner result alone
+  never proves a correct migration.
 
 CONTEXTUAL FILE REVIEW PROTOCOL
   Use review_queue as a coverage aid. Review relevant files individually, starting with repository
@@ -2695,6 +2756,18 @@ CONNECT A DISCOVERED APP THROUGH MCP:
   Never guess environment mappings or action tags. Connecting mutates product configuration;
   obtain user approval when the user has not already requested the connection.
 
+  CONFIRMED LIMITATION (2026-08-17): both ductape_marketplace_connect and the equivalent
+  ductape_cli("products apps connect --product <tag> --app <app-tag> --env-map ...") reject any
+  app that is not marked public in the marketplace, with error
+  App "<tag>" is not public in the marketplace. This includes apps a user creates themselves under
+  their own tag (e.g. a private "ductape:paystack") — private/workspace-owned apps CANNOT be
+  connected to a product through MCP or CLI at all, only through Workbench, even though
+  ductape_marketplace_inspect can still read a private app's full action catalogue (inspect and
+  connect have different visibility rules). If you hit this, do not keep retrying — tell the user
+  the app must be connected via Workbench, and once they confirm it's connected, verify with
+  ductape_cli("products apps list --product <product_tag> --json") rather than attempting the
+  connect call again.
+
 ONLY after all five steps can any code call:
   ctx.api.run({ app: '<app_tag>', action: '<action_tag>', input: { ... } })   ← in a feature handler
   actions.run([{ product, env, app: '<app_tag>', action: '<action_tag>', input }])   ← at runtime
@@ -2712,8 +2785,12 @@ If a feature step needs to call an external service and no App is registered for
 An app is a versioned API integration definition. It contains environments (base URLs), actions
 (individual endpoint specs), auth schemes, webhooks, variables, and constants.
 
-Create an app (admin — ductape_cli):
-  ductape_cli("apps create --name \\"Email Service\\" --description \\"Transactional email\\"")
+Call ductape_integrate_endpoint for the full ordered flow (choose/create the app, define the
+action, connect it to the product) before writing the ctx.api.run call below.
+
+Create an app (admin — ductape_cli; no --name/--description flags exist, only -f <file.json> or
+interactive TTY):
+  ductape_cli("apps create -f app.json")   # body: { app_name, description, tag, envs?: [...] } — tag is REQUIRED
   ductape_cli("app.init", ["app_tag"])       → loads app into builder state
 
 Import from a file:
@@ -2794,15 +2871,27 @@ Connecting an app to a product (after creation):
   NOTE: All product.* module methods require the access key and CANNOT use ductape_execute.
   Use ductape_cli for all product-level operations.
 
-  FULL FLOW to make an app callable from a product:
-  1. Create the app:     ductape_cli("apps create --name \\"Service Name\\" --description \\"...\\"")
-  2. Add environments:   Workbench
-  3. Configure auth:     Workbench
-  4. Define actions:     Workbench
+  FULL FLOW to make an app callable from a product — call ductape_integrate_endpoint for the
+  ordered version of this with exact ask-the-user points; summary (all verified live):
+  1. Create the app:     ductape_cli("apps create -f app.json")
+                         body: { app_name, description, tag, envs: [{ env_name, slug, description,
+                         base_url, active }, ...] } — tag is REQUIRED; every active env needs a base_url.
+                         No --name/--description flags exist, only -f <file.json> or interactive TTY.
+  2. Add environments:   Part of step 1's envs array, or later via ductape_cli("apps update --tag
+                         <app_tag> --proxy -f app.json") with an updated envs array.
+  3. Configure auth:     Workbench (no CLI command).
+  4. Define actions:     ductape_cli("apps actions create --app <app_tag> --action-file action.json")
+                         body: { tag, name, resource, method, request_type, description?, params?,
+                         query?, headers?, body?, response? } — request_type is REQUIRED, one of
+                         "application/json" | "application/x-www-form-urlencoded" |
+                         "multipart/form-data" | "SOAP" | "html" (not "json"/"xml"/"form"); resource
+                         is relative to each env's base_url, never a full URL.
                          OR import: ductape_cli("apps import <file.json> -t postman|openapi")
-  5. Connect to product: Requires the product_id.
-                         There is no CLI command for this step — the SDK product.apps.add method requires
-                         an access key which only the backend can provide. Connect via Workbench.
+  5. Connect to product: ductape_cli("products apps connect --product <product_tag> --app <app_tag>
+                         --env-map <app_env>:<product_env> [repeat --env-map per environment] --json")
+                         Requires the app to be public in the marketplace OR owned by the same
+                         workspace as the product. Does the full connect + environment-mapping
+                         sequence in one call.
   6. Verify:             ductape_cli("products apps list --product <product_tag> --json")
                          ductape_cli("products apps actions list --product <product_tag> --app <app_tag> --json")
 `.trim(),
@@ -3079,6 +3168,23 @@ TAG AND SMTP RULES
   emails.smtp.secure is a boolean and cannot be a $Secret{...} string.
   Credential strings such as auth.user and auth.pass may use $Secret{...}.
 
+  notifications messages create/update/get had NO --product override before CLI 0.3.17 — it
+  silently resolved the product from whatever is linked in the current working directory, with
+  no way to override. Confirmed root cause of a real multi-hour misdiagnosis: it kept resolving
+  to a different product than intended, and the resulting "Notification X not found" error never
+  named which product it actually checked. If seeing this on an older CLI, verify which project
+  is linked in cwd before assuming the notification component itself is missing.
+
+  SendGrid field names (confirmed against the live Joi validator, not just this doc — cross-check
+  the SDK source when in doubt): { provider: "sendgrid", sendgrid: { apiKey: "$Secret{...}",
+  sender_email: "$Secret{...}" } }. The field is sender_email, not sender — "sender" is silently
+  rejected with a required-field error naming sender_email specifically, not a helpful diff.
+
+  Nexmo/Vonage SMS field names: { provider: "nexmo", apiKey: "$Secret{...}",
+  apiSecret: "$Secret{...}", sender: "YourSenderId" }. The credential fields are apiKey/apiSecret
+  — NOT accountSid (that is a Twilio-only field name and is rejected with "not allowed" if used
+  for nexmo).
+
 Send at runtime (one channel at a time):
   → CALL ductape_generate_payload FIRST (operation_family="notification", method="email.send")
   notifications.email.send    [{ product, env, notification, input: { recipients, subject?, template? } }]
@@ -3130,6 +3236,16 @@ FIREBASE THROUGH A GCP CLOUD CONNECTION
   intent; creating a notification does not prove Google-side FCM permission. Runtime delivery
   requires fcm.googleapis.com and roles/firebasecloudmessaging.admin, so validate the connection
   and perform a delivery test.
+
+  CONFIRMED CONTRADICTION (2026-08-17): despite the "never put the private key in the file"
+  guidance above, resources notifications create with authMode: "cloud_connection" currently
+  rejects the payload progressively demanding envs[].push_notifications.credentials.project_id,
+  then .private_key_id, then .client_email, then finally the raw .private_key itself — the full
+  manual service-account shape, defeating the documented purpose of cloud_connection mode. Do NOT
+  fabricate a placeholder private_key to satisfy this — that field is genuinely sensitive and a
+  fake value risks being mistaken for real credential material later. If you hit this, drop the
+  push_notifications block and register email/SMS only until this is fixed, and tell the user
+  explicitly rather than working around it with fake data.
 Notification tag and message tag are ALWAYS passed together as "notification_tag:message_tag".
 `.trim(),
     resilience: `
@@ -3660,6 +3776,55 @@ STEP 6 — WRITE the feature into the project codebase
   - Write rollback handlers inline as the third argument to ctx.step()
   - Return a plain object as the feature's output
 
+━━━ DEPLOYING features.define CALLS — DO NOT run them on every app boot ━━━
+
+  features.define() has a network-bound RECORDING PHASE (see FEATURE RECORDING SEMANTICS below) that
+  calls the live Ductape API to compile and register the Feature's step graph. This is administrative
+  configuration work, not a request-serving concern — treat it exactly like a database migration:
+  defined in source, but APPLIED via an explicit, separate command, never automatically on every
+  process start.
+
+  Calling features.define() from inside a framework's normal startup lifecycle hook (NestJS
+  onModuleInit, Express app bootstrap, a Lambda cold-start path, etc.) makes ordinary app startup
+  depend on Ductape API reachability and latency for every single boot/restart/replica — including
+  local dev restarts, autoscaling events, and health-check-triggered restarts. A slow or unreachable
+  Ductape API then blocks the app from ever starting to serve requests, even for routes that have
+  nothing to do with the affected Feature.
+
+  REQUIRED CONVENTION — this is what "ductape features sync" (CLI) expects:
+    1. Put every Feature definition under ductape/features/ (e.g. ductape/features/src/my-feature.ts),
+       each calling ductape.feature.define({ ... }) from a registerXFeature(ductape) export. This
+       mirrors ductape/database/migrations/ — a fixed, discoverable location for Ductape-managed
+       source, regardless of the surrounding project structure.
+    2. In the app's normal startup path, register ONLY local function/operation handlers
+       (ductape.sdk.functions.register(...)) — no network call, safe on every boot. Never call
+       features.define(...) here.
+    3. Add a "features:sync" script to package.json. It owns booting just enough of the app to
+       construct real dependencies (in NestJS, use NestFactory.createApplicationContext(module) —
+       same DI container, no HTTP listener) and calling every registerXFeature(...) once, then
+       exiting. Ductape cannot run this step for you generically — a Feature handler is real
+       application code that typically depends on the app's own services, unlike a migration file,
+       which is declarative data the Ductape backend can apply directly.
+    4. Persist Features by running "ductape features sync" (or ductape_cli("features sync")), which
+       finds the linked project and runs its "features:sync" script — never automatically on boot.
+       Pass an optional filter argument to scope it: "ductape features sync payments".
+
+  A NestJS service with both concerns split looks like:
+    async onModuleInit() {
+      this.ductape.sdk.functions.register({ ...myFunctions, operations: { ... /* local handlers */ } });
+    }
+    async syncFeatures(): Promise<void> {
+      await registerMyFeature(this.ductape.sdk);   // the features.define(...) call
+    }
+  The project's own "features:sync" script resolves each service with a syncFeatures() method via a
+  headless application context and calls it — mirroring how a migration runner applies pending
+  migrations explicitly. "ductape features sync" is a thin, framework-agnostic front door onto that
+  script; it does not itself execute application code.
+
+  This applies to any framework, not just NestJS — the only requirement is that whatever construct
+  the app boots FOR REQUESTS never itself calls features.define(); the project's own "features:sync"
+  script does, invoked only through the explicit CLI command.
+
 STEP 7 — HANDLE conditionals, loops, and branching (when applicable)
   Branch on step result (early return in handler):
     → Add branchOverrides: { stepTag: { field: value } } so all branches are recorded
@@ -4888,7 +5053,14 @@ EMBEDDING EXECUTION — CURRENT CODE-FIRST CONTRACT:
         generated.embeddings.some(v => v.length !== EXPECTED_VECTOR_DIMENSIONS)) {
       throw new Error('EMBEDDING_DIMENSION_MISMATCH');
     }
-  Register a real local handler at application bootstrap or configure a signed HTTPS/events transport.
+  Register a real local handler at application bootstrap or configure gRPC-mTLS, Events, or signed HTTPS.
+  Remote resolution order is gRPC-mTLS, Events, then signed HTTPS. A gRPC transport is
+  { type:'grpc', endpoint:'host:443', service:'ductape.functions.v1.PortableFunctions',
+    method:'Invoke', authentication:'mtls', tls:{ ca_env, cert_env, key_env } }.
+  Never write PEM, certificates, private keys, tokens, or access keys into function JSON. Set
+  DUCTAPE_FUNCTION_GRPC_ENDPOINT and referenced TLS variables in the application runtime. The gRPC
+  adapter must pool channels. Only UNAVAILABLE/deadline failures may fall back; auth, correlation,
+  schema, and application failures must not execute again over another transport.
   Input and output JSON schemas are validated at runtime. Missing implementation fails with
   FUNCTION_UNAVAILABLE; schema mismatch fails with FUNCTION_SCHEMA_VALIDATION_FAILED; timeout fails
   with FUNCTION_TIMEOUT. Never substitute sample/random/recording-time embeddings. The Feature's
@@ -5042,6 +5214,113 @@ const portableFunctionSetupHandler = async (args) => {
                     ],
                 }, null, 2) }] };
 };
+// This tool only derives a step-by-step plan from its arguments and read-only lookups the calling
+// agent performs itself via other tools. It runs no CLI command and writes nothing.
+const integrateEndpointHandler = async (args) => {
+    const hasApp = Boolean(args.app_tag);
+    const hasProduct = Boolean(args.product_tag);
+    const stages = [];
+    if (!hasApp) {
+        stages.push({
+            stage: 0,
+            title: 'Choose the app',
+            ask_user: 'Should this endpoint be added to an existing app, or do you want to create a new app for it?',
+            if_existing_app: [
+                'Get the exact app tag. If unsure, call ductape_cli("apps list --json"), or ' +
+                    'ductape_marketplace_discover/ductape_marketplace_inspect if it might be a public marketplace app.',
+                'Re-call this tool with that app_tag once known — the returned flow will skip straight to stage 2.',
+            ],
+            if_new_app: 'Continue to stage 1.',
+        });
+    }
+    if (!hasApp) {
+        stages.push({
+            stage: 1,
+            title: 'Create the app (new app path only — skip if using an existing app)',
+            ask_user: [
+                'App name and a short description.',
+                'What environments does this app need (e.g. dev, staging, production), and what is the base ' +
+                    'URL for each? At least one environment is required. Every ACTIVE environment must have a ' +
+                    'base_url before the action in stage 2 can be called against it.',
+            ],
+            then: [
+                'Write a JSON body: { app_name, description, tag, envs: [{ env_name, slug, description, ' +
+                    'base_url, active: true }, ...] }. tag is REQUIRED — derive a slug from app_name if the ' +
+                    'user has not given one explicitly.',
+                'Run: ductape_cli("apps create -f <path-to-body.json> --json")',
+                'The app tag is what you supplied, not something the response generates — use it as app_tag ' +
+                    'in every later stage.',
+            ],
+        });
+    }
+    stages.push({
+        stage: 2,
+        title: 'Define the action (the endpoint itself)',
+        app_tag: args.app_tag ?? '<app tag from stage 1, or the existing app tag>',
+        ask_user: [
+            'The HTTP method (GET/POST/PUT/PATCH/DELETE).',
+            'The endpoint PATH relative to the app\'s base_url — e.g. "/v1/users/{id}", never a full URL. ' +
+                'Ductape joins base_url + resource per environment at call time, so the same action works ' +
+                'across every environment automatically.',
+            'Only what is relevant to this specific endpoint: query params, headers, request body shape ' +
+                '(for POST/PUT/PATCH), and the expected response shape (status_code, success flag, a body ' +
+                'sample). Do not invent fields the user has not described or that are not in the API docs.',
+        ],
+        then: [
+            'If the exact body shape is uncertain, call ductape_schema first.',
+            'Write a JSON body: { tag, name, resource, method, request_type, description?, params?, ' +
+                'query?, headers?, body?, response? }. request_type is REQUIRED — one of "application/json" ' +
+                '| "application/x-www-form-urlencoded" | "multipart/form-data" | "SOAP" | "html" (not ' +
+                '"json"/"xml"/"form"). If response is included, response.status_code and ' +
+                'response.response_format use that same set of values, and status_code is a STRING (e.g. ' +
+                '"200", not the number 200).',
+            'Run: ductape_cli("apps actions create --app <app_tag> --action-file <path-to-action.json> ' +
+                '--json") — the flag is --action-file, not -f (that flag belongs to the parent "apps" ' +
+                'command and Commander resolves it there, so -f would silently be ignored here).',
+        ],
+    });
+    stages.push({
+        stage: 3,
+        title: 'Connect the app to the product',
+        skip_if: 'The app is already connected to the target product — check with ' +
+            'ductape_cli("products apps list --product <product_tag> --json") before asking the user anything here.',
+        product_tag: args.product_tag ?? '<ask the user, if not already established from context>',
+        then: [
+            hasProduct
+                ? `Product already known: ${args.product_tag}.`
+                : 'Ask the user which product this belongs to, unless already obvious from context.',
+            'Get the product\'s environments: ductape_cli("products environments list <product_tag> --json")',
+            'Map each product environment to one of the app\'s environments (usually 1:1 by name) — ask the ' +
+                'user rather than guessing if it is not obvious.',
+            'Run: ductape_cli("products apps connect --product <product_tag> --app <app_tag> --env-map ' +
+                '<app_env>:<product_env> [repeat --env-map per environment] --json"). If the app is a public ' +
+                'marketplace app, ductape_marketplace_connect does the same thing in one call.',
+        ],
+    });
+    stages.push({
+        stage: 4,
+        title: 'Only now write integration code',
+        instructions: [
+            'Do not write any code that calls this endpoint before stages 0-3 are complete — the action and ' +
+                'the product connection must exist first, or the generated code will reference a tag that ' +
+                'does not exist yet.',
+            'Call ductape_generate_payload (operation_family="action", method="run" or "dispatch", ' +
+                'targets={app, action}) first, then ductape_generate_snippet or ductape_execute to call it.',
+        ],
+    });
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    ok: true,
+                    flow: 'integrate_endpoint',
+                    note: 'Follow these stages in order. Each stage tells you what to ask the user and which ' +
+                        'ductape_cli command to run. Stages already satisfied by the arguments you passed are omitted.',
+                    stages,
+                }, null, 2),
+            }],
+    };
+};
 const eventsTopicSetupHandler = async (args) => {
     const tag = `${args.broker_tag}:${args.topic_tag}`;
     const relativePath = `ductape/events/${args.topic_tag}.topic.json`;
@@ -5096,9 +5375,11 @@ const cliInputSchema = z.object({
         'Note: environments have their own CLI commands (products environments list/get/create/update, ' +
         'no linked project required — the product tag is always an explicit argument). Quotas, ' +
         'fallbacks, jobs, and healthchecks use resources commands. App actions and auths are ' +
-        'configured in the Workbench UI. Features have no CLI ' +
-        'creation command: define them in application code with features.define so application ' +
-        'boot/runtime registration makes them available.\n\n' +
+        'configured in the Workbench UI. Features have no CLI creation command: define them in ' +
+        'application code with features.define under ductape/features/. Persist them with ' +
+        '"features sync" (runs the project\'s own "features:sync" npm script) — never call ' +
+        'features.define from the app\'s normal startup path, since that blocks every boot on ' +
+        'Ductape API reachability. See ductape_docs for the full convention.\n\n' +
         'The CLI uses the user\'s local logged-in session (ductape login) — no key is required.'),
 });
 async function loadMcpSdk() {
@@ -5374,6 +5655,26 @@ async function main() {
                     return p;
                 });
             }
+            // Most non-setup publishable-key runtime calls require params[0] to carry a "session" field
+            // (confirmed 2026-08-18 against live backend logs: the proxy's own error is "When using
+            // publishable key, params must include a session (session token from backend)." — the HTTP
+            // response to the client only ever says the much vaguer "Authentication failed", so this
+            // failure mode is otherwise very hard to diagnose from the client side alone). Fail fast
+            // locally with a specific message instead of making a doomed network call.
+            const sessionRequiredModules = new Set([
+                'actions', 'features', 'databases', 'graph', 'vector', 'storage',
+                'notifications', 'messageBrokers', 'events', 'quotas', 'fallback', 'health',
+            ]);
+            const sessionExemptMethods = new Set(['consume', 'status', 'check', 'fetch', 'list']);
+            const requiresSession = sessionRequiredModules.has(proxyModule) && !sessionExemptMethods.has(args.method.toLowerCase());
+            const paramsHaveSession = params.some((p) => p && typeof p === 'object' && !Array.isArray(p) && 'session' in p);
+            if (requiresSession && !paramsHaveSession) {
+                throw new Error(`"${args.module}.${args.method}" is a runtime operation and requires a "session" field in ` +
+                    'params[0] — none was provided. ductape_execute cannot supply a session on your behalf. ' +
+                    'Call ductape_generate_payload for this operation to see the exact param shape, obtain a ' +
+                    'real session token (e.g. via sessions.start against this product/env — not a placeholder ' +
+                    'string), and include it as params[0].session before retrying.');
+            }
             let result;
             try {
                 result = await executeViaProxy(key, proxyModule, args.method, params);
@@ -5381,8 +5682,17 @@ async function main() {
             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.');
+                    const sessionHint = !paramsHaveSession
+                        ? ' No "session" field was present in params — most non-setup publishable-key runtime ' +
+                            'calls require one (a real token from sessions.start, not a placeholder). This is the ' +
+                            'most common cause of an opaque "Authentication failed" response; call ' +
+                            'ductape_generate_payload first to see whether this operation expects a session field, ' +
+                            'then obtain a real session token before retrying.'
+                        : ' A "session" field was present, so a missing session is likely not the cause here — ' +
+                            'check that the publishable key itself belongs to the same workspace/product, and that ' +
+                            'any module/action restrictions on the key (Workbench → Tokens → Publishable Key) ' +
+                            'permit this operation.';
+                    throw new Error(`Runtime authentication was rejected (backend said: "${message}").` + sessionHint);
                 }
                 throw error;
             }
@@ -5559,7 +5869,15 @@ async function main() {
                 'Two-step rule for runtime operations:\n' +
                 '  1. Call ductape_generate_payload first to get the canonical payload template.\n' +
                 '     This reveals the exact "input" field keys — they are product/env/operation-specific.\n' +
-                '  2. Fill in the values from the template, then call ductape_execute.',
+                '  2. Fill in the values from the template, then call ductape_execute.\n\n' +
+                'Session requirement: most non-setup operations on actions, features, databases, graph, ' +
+                'vector, storage, notifications, message brokers/events, quotas, fallback, and health ' +
+                'require a real session token in params[0].session (from sessions.start against the same ' +
+                'product/env — never a placeholder string). This tool checks for that locally and fails ' +
+                'fast with a specific error before calling the backend if it is missing for an operation ' +
+                'that needs one. The backend itself only reports a generic "Authentication failed" for ' +
+                'this case, so a missing session and a genuinely bad key look identical unless you read ' +
+                'this local check first.',
             inputSchema: executeInputSchema,
         }, executeHandler);
         server.registerTool('ductape_generate_payload', {
@@ -5687,6 +6005,15 @@ async function main() {
                 command: `products apps connect --product ${shellArgument(args.product_tag)} --app ${shellArgument(args.app_tag)}${mappings} --json`,
             });
         });
+        server.registerTool('ductape_integrate_endpoint', {
+            title: 'Integrate a New Endpoint',
+            description: 'Call this FIRST whenever the user wants to integrate a new API endpoint — before writing any ' +
+                'code. Returns the ordered flow: choose an existing app or create a new one, define the ' +
+                'action (endpoint) on it, connect the app to the target product, and only then write code. ' +
+                'Read-only — it runs no CLI command itself and performs the steps only when you follow up with ' +
+                'the ductape_cli calls it names.',
+            inputSchema: integrateEndpointInputSchema,
+        }, integrateEndpointHandler);
         server.registerTool('ductape_cli', {
             title: 'Ductape CLI',
             description: 'Run a Ductape CLI command for administrative operations.\n\n' +
@@ -5805,6 +6132,7 @@ async function main() {
         server.tool('ductape_function_setup', portableFunctionSetupInputSchema.shape, portableFunctionSetupAnnotations, portableFunctionSetupHandler);
         server.tool('ductape_redis_setup', redisSetupInputSchema.shape, redisSetupHandler);
         server.tool('ductape_migration_plan', migrationInputSchema.shape, migrationHandler);
+        server.tool('ductape_integrate_endpoint', integrateEndpointInputSchema.shape, integrateEndpointHandler);
         server.tool('ductape_cli', cliInputSchema.shape, cliHandler);
     }
     else {

package/docs/TOOLS.md

@@ -2,6 +2,42 @@
 
 The Ductape MCP server exposes proxy, CLI, discovery, documentation, migration, and portable-function setup tools.
 
+## Tool: `ductape_integrate_endpoint`
+
+Call this first whenever the user wants to integrate a new API endpoint, before writing any code.
+It is read-only guidance — it runs no CLI command itself and returns the ordered flow to follow:
+
+1. **Choose the app** — ask first: existing app, or create a new one? Do not assume "new" just
+   because the API seems unfamiliar — check `ductape_cli("apps list --json")` and let the user
+   decide. If new: `ductape_cli("apps create -f app.json")`, body `{ app_name, description, tag,
+   envs: [...] }` (`tag` is REQUIRED — no `--name`/`--description` flags exist, only `-f
+   <file.json>` or interactive TTY), collecting an environment + base URL for each environment the
+   app needs; every active environment needs a `base_url` before its action can be called.
+2. **Define the action** — the HTTP method and the endpoint's path *relative to the app's base_url*
+   (e.g. `/v1/users/{id}`, never a full URL — Ductape joins `base_url + resource` per environment at
+   call time), plus only the params/headers/body/response fields relevant to that endpoint. Then
+   `ductape_cli("apps actions create --app <tag> --action-file action.json")` — the flag is
+   `--action-file`, **not** `-f`/`--file` (that flag belongs to the parent `apps` command; Commander
+   resolves a flag shared by an ancestor and a descendant against the ancestor, so `-f` here is
+   silently ignored — same fix `products environments create/update` uses `--env-file` for).
+   `request_type` is REQUIRED on the body — one of `"application/json"` |
+   `"application/x-www-form-urlencoded"` | `"multipart/form-data"` | `"SOAP"` | `"html"` (not the
+   short names `"json"`/`"xml"`/`"form"`); if `response` is included, `response.status_code` is a
+   **string** (e.g. `"200"`) and `response.response_format` uses that same value set.
+3. **Connect the app to the product** — skip if already connected. Otherwise map each product
+   environment to an app environment and run
+   `ductape_cli("products apps connect --product <tag> --app <tag> --env-map <app_env>:<product_env> ...")`.
+4. **Only then write integration code** — `ductape_generate_payload` → `ductape_generate_snippet` /
+   `ductape_execute`, calling `actions.run` or `actions.dispatch`.
+
+Optional arguments `product_tag` and `app_tag` let the tool skip stages already answered (e.g. pass
+`app_tag` once the user has said which existing app this belongs to, and the returned flow starts at
+stage 2 instead of asking again) — but never infer `app_tag` on the tool's behalf without the user
+having actually said so; when in doubt, omit it and let stage 1 ask.
+
+All of the above was verified against a live workspace: created a `jsonplaceholder` app with `prd`/
+`snd` environments, added a `GET /todos/1` action, and connected it to a real product end to end.
+
 ## Tools: `ductape_events_topic_setup` and `ductape_events_validate_project`
 
 `ductape_events_topic_setup` is a read-only generator for one canonical topic asset. It returns the

package/package.json

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