@webhooks-cc/mcp 1.13.0 → 1.15.0

package/dist/bin/mcp.js

@@ -418,28 +418,75 @@ var methodSchema = import_zod2.z.enum(HTTP_METHODS).default("POST").describe("HT
 var kindSchema = import_zod2.z.enum(["http", "email"]).optional().describe('Only HTTP requests ("http") or only captured emails ("email")');
 var EMAIL_SCAN_LIMIT = 100;
 var durationOrTimestampSchema = import_zod2.z.union([import_zod2.z.string(), import_zod2.z.number()]);
-var ruleConditionSchema = import_zod2.z.object({
-  field: import_zod2.z.enum(["method", "path", "header", "body_contains", "body_path", "query"]).describe("Request field to match against"),
-  op: import_zod2.z.enum(["eq", "contains", "starts_with", "matches", "exists"]).describe("Comparison operator"),
-  value: import_zod2.z.string().max(import_sdk.MAX_CONDITION_VALUE_LEN).optional().describe(
-    `Value to compare against (required unless op is "exists", max ${import_sdk.MAX_CONDITION_VALUE_LEN} chars)`
+var CONDITION_FIELD_NAMES = Object.keys(import_sdk.CONDITION_FIELDS);
+var CONDITION_OP_NAMES = import_sdk.CONDITION_OPS;
+function conditionSchema(use) {
+  const fields = use === "response" ? CONDITION_FIELD_NAMES.filter((field) => import_sdk.CONDITION_FIELDS[field].response) : CONDITION_FIELD_NAMES;
+  return import_zod2.z.object({
+    field: import_zod2.z.enum(fields).describe(
+      use === "response" ? "What to read: method, path, header (name), query (name), body (text), body_path (path into a JSON or form body), content_type, size" : "What to read: method, path, header (name), query (name), body, body_path (path), content_type, size, kind (http or email), email (name: subject, from, to, text or tag), spam_score, email_auth (name: spf, dkim or dmarc), signature (verified, failed or missing)"
+    ),
+    op: import_zod2.z.enum(CONDITION_OP_NAMES).describe(
+      "eq, neq, contains, not_contains, starts_with, ends_with, matches (glob: * one path segment, ** any, ? one character), regex (RE2, searched anywhere; (?i) ignores case), exists, not_exists, gt, gte, lt, lte (numbers)"
+    ),
+    value: import_zod2.z.string().max(import_sdk.MAX_CONDITION_VALUE_LEN).optional().describe(`What to compare with (not for exists and not_exists)`),
+    name: import_zod2.z.string().max(import_sdk.MAX_CONDITION_NAME_LEN).optional().describe("Header or query parameter name; the email part; spf, dkim or dmarc"),
+    path: import_zod2.z.string().max(import_sdk.MAX_CONDITION_PATH_LEN).optional().describe('Dot path for body_path, e.g. data.object.status or items.0.sku or a["odd.key"]')
+  }).superRefine((condition, ctx) => {
+    for (const issue of (0, import_sdk.conditionIssues)(condition, { use })) {
+      ctx.addIssue({ code: "custom", message: issue });
+    }
+  });
+}
+var ruleConditionSchema = conditionSchema("response");
+var destinationFields = {
+  name: import_zod2.z.string().max(100).nullable().optional().describe("A name for the list and the log"),
+  enabled: import_zod2.z.boolean().optional().describe("Send to it (default true)"),
+  http: import_zod2.z.boolean().optional().describe("Takes HTTP requests (default true)"),
+  email: import_zod2.z.boolean().optional().describe("Takes emails (default true)"),
+  filter: import_zod2.z.object({
+    logic: import_zod2.z.enum(["and", "or"]).optional().describe("and (default): every condition; or: any"),
+    conditions: import_zod2.z.array(conditionSchema("filter")).max(10)
+  }).nullable().optional().describe(
+    "Send only captures that match (null: everything it takes). Conditions like response rules plus kind, email (name: subject, from, to, text, tag), spam_score, email_auth (name: spf, dkim, dmarc) and signature (verified, failed, missing)"
   ),
-  name: import_zod2.z.string().max(import_sdk.MAX_CONDITION_NAME_LEN).optional().describe(
-    `Header name or query param name (required for header/query, max ${import_sdk.MAX_CONDITION_NAME_LEN} chars)`
+  format: import_zod2.z.enum([
+    "auto",
+    "as_received",
+    "json",
+    "template",
+    "chat",
+    "postmark",
+    "sendgrid",
+    "mailgun",
+    "cloudmailin"
+  ]).optional().describe(
+    "auto (pick from the URL), as_received (relay HTTP requests unchanged; emails as signed JSON), json (signed JSON envelope), template (your bodyTemplate, signed like json), chat (Slack or Discord message), or an inbound mail provider's shape for emails (postmark, sendgrid, mailgun, cloudmailin; HTTP requests then go as received), to test the inbound handler you wrote for that provider"
   ),
-  path: import_zod2.z.string().max(import_sdk.MAX_CONDITION_PATH_LEN).optional().describe(
-    `JSON dot-notation path (required for body_path, max ${import_sdk.MAX_CONDITION_PATH_LEN} chars)`
-  )
-}).refine((c) => c.op === "exists" || c.value !== void 0 && c.value.length > 0, {
-  message: 'value is required when op is not "exists"'
-}).refine(
-  (c) => !(c.field === "header" || c.field === "query") || c.name !== void 0 && c.name.length > 0,
-  { message: "name is required for header and query conditions" }
-).refine((c) => c.field !== "body_path" || c.path !== void 0 && c.path.length > 0, {
-  message: "path is required for body_path conditions"
-}).refine((c) => c.op !== "matches" || !c.value || c.value.length <= import_sdk.MAX_GLOB_PATTERN_LEN, {
-  message: `matches pattern must be ${import_sdk.MAX_GLOB_PATTERN_LEN} chars or less`
-});
+  mailgunSigningKey: import_zod2.z.string().max(200).nullable().optional().describe(
+    "For format mailgun: your Mailgun HTTP webhook signing key, so the form's signature verifies; null removes it. Write-only."
+  ),
+  bodyTemplate: import_zod2.z.unknown().optional().describe(
+    `For format template: any JSON value whose strings hold {{ placeholders }}, e.g. {"event": "{{ json.type }}", "amount": "{{ json.data.amount }}", "code": "{{ codes.0 }}"}. A string that is only a placeholder keeps the value's type; a missing field becomes null. HTTP requests read method, path, query.x, headers.x, body, json.path, id, receivedAt, signature; emails read the email.received fields (subject, from.address, to, text, codes, links, auth, spam, tag)`
+  ),
+  messageTemplate: import_zod2.z.string().max(4e3).nullable().optional().describe(
+    "For format chat: the message text with {{ placeholders }}; null sends the standard message"
+  ),
+  headers: import_zod2.z.array(
+    import_zod2.z.object({
+      name: import_zod2.z.string().describe("Header name, e.g. Authorization"),
+      value: import_zod2.z.string().nullable().describe("Value, or null to keep the stored one")
+    })
+  ).max(10).optional().describe("Your own headers for every delivery (not chat). Replaces the whole list"),
+  appendPath: import_zod2.z.boolean().optional().describe("Append the captured path to the URL (as_received)"),
+  retrySeconds: import_zod2.z.union([import_zod2.z.literal(0), import_zod2.z.literal(3600), import_zod2.z.literal(86400)]).optional().describe("Retry failed deliveries for 86400 (default), 3600 or 0 seconds"),
+  keepOrder: import_zod2.z.boolean().optional().describe("One delivery at a time, in capture order"),
+  sentField: import_zod2.z.string().max(128).nullable().optional().describe("JSON body field with the sender's own timestamp"),
+  throttleSeconds: import_zod2.z.number().int().min(0).max(3600).optional().describe(
+    "At most one delivery every N seconds; the rest are not sent (1 makes a heads-up channel)"
+  ),
+  delaySeconds: import_zod2.z.number().int().min(0).max(3600).optional().describe("Wait this long after the capture before sending, like a callback")
+};
 var responseRuleSchema = import_zod2.z.object({
   name: import_zod2.z.string().max(import_sdk.MAX_RULE_NAME_LEN).optional().describe(`Human-readable rule name (max ${import_sdk.MAX_RULE_NAME_LEN} chars)`),
   enabled: import_zod2.z.boolean().optional().default(true).describe("Whether this rule is active"),
@@ -450,8 +497,10 @@ var responseRuleSchema = import_zod2.z.object({
 var responseRulesSchema = import_zod2.z.array(responseRuleSchema).max(50).describe("Ordered conditional response rules (first match wins, max 50)");
 var mockResponseSchema = import_zod2.z.object({
   status: import_zod2.z.number().int().min(import_sdk.MOCK_RESPONSE_STATUS_MIN).max(import_sdk.MOCK_RESPONSE_STATUS_MAX).describe(`HTTP status code (${import_sdk.MOCK_RESPONSE_STATUS_MIN}-${import_sdk.MOCK_RESPONSE_STATUS_MAX})`),
-  body: import_zod2.z.string().default("").describe("Response body string (default: empty)"),
-  headers: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.string()).default({}).describe("Response headers (default: none)"),
+  body: import_zod2.z.string().default("").describe(
+    'Response body (default: empty). {{ placeholders }} are filled in from the request: {{ json.id }} (a JSON or form body field), {{ body }}, {{ headers.user-agent }}, {{ query.page }}, {{ method }}, {{ path }}, {{ id }}, {{ uuid }}, {{ now }}; filters: | default: "x", | json, | lower, | upper, | truncate: 80'
+  ),
+  headers: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.string()).default({}).describe("Response headers (default: none); values may use {{ placeholders }} too"),
   delay: import_zod2.z.number().int().min(import_sdk.MOCK_RESPONSE_DELAY_MIN).max(import_sdk.MOCK_RESPONSE_DELAY_MAX).optional().describe(
     `Response delay in milliseconds (${import_sdk.MOCK_RESPONSE_DELAY_MIN}-${import_sdk.MOCK_RESPONSE_DELAY_MAX}, default: none)`
   )
@@ -705,7 +754,9 @@ async function waitForMultipleRequests(client, endpointSlug, options) {
         };
       }
     }
-    await sleep(Math.max(10, pollIntervalMs));
+    await sleep(
+      Math.min(Math.max(10, pollIntervalMs), Math.max(0, timeoutMs - (Date.now() - startedAt)))
+    );
   }
   return {
     requests,
@@ -806,6 +857,8 @@ var ESSENTIAL_DETAIL_FIELDS = [
   "tag",
   "subject",
   "from",
+  "fields",
+  "replyText",
   "size",
   "test",
   "spam",
@@ -815,6 +868,11 @@ var ESSENTIAL_DETAIL_FIELDS = [
   "html",
   "htmlTruncated"
 ];
+function shrinkRendered(rendered, max) {
+  const body = typeof rendered.body === "string" ? rendered.body : "";
+  if (body.length <= max - 1024) return rendered;
+  return { ...rendered, body: body.slice(0, max - 1024), bodyTruncated: true };
+}
 function emailDetail(client, email, view, includeHtml) {
   const { data } = client.emails.toJson(email, {
     endpoint: view.endpoint,
@@ -856,7 +914,67 @@ function emailDetail(client, email, view, includeHtml) {
   ]);
   return detail;
 }
-function registerTools(server, client) {
+var LOCAL_ONLY_TOOLS = /* @__PURE__ */ new Set(["send_to", "replay_request"]);
+var TARGET_URL_TOOLS = /* @__PURE__ */ new Set(["render_email", "test_webhook_flow"]);
+var REMOTE_MAX_WAIT_MS = 5e4;
+var REMOTE_MIN_POLL_MS = 1e3;
+function durationMs(value) {
+  if (typeof value === "number") return Number.isFinite(value) && value >= 0 ? value : null;
+  if (typeof value !== "string") return null;
+  try {
+    const ms = (0, import_sdk.parseDuration)(value);
+    return Number.isFinite(ms) && ms >= 0 ? ms : null;
+  } catch {
+    return null;
+  }
+}
+function toolTarget(target, remote, handles) {
+  return {
+    tool(name, description, shape, handler) {
+      if (remote && LOCAL_ONLY_TOOLS.has(name)) return { remove() {
+      } };
+      const wrapped = remote ? async (args2) => {
+        const input = args2;
+        if (TARGET_URL_TOOLS.has(name) && input.targetUrl !== void 0) {
+          return {
+            ...textContent(
+              "targetUrl needs the local MCP server (npx -y @webhooks-cc/mcp): the hosted server cannot reach your machine. Leave it out here."
+            ),
+            isError: true
+          };
+        }
+        const bounded = { ...input };
+        if ("pollInterval" in shape && input.pollInterval === void 0) {
+          bounded.pollInterval = REMOTE_MIN_POLL_MS;
+        }
+        for (const [key, bound] of [
+          ["timeout", (ms) => Math.min(ms, REMOTE_MAX_WAIT_MS)],
+          [
+            "pollInterval",
+            (ms) => Math.min(Math.max(ms, REMOTE_MIN_POLL_MS), REMOTE_MAX_WAIT_MS)
+          ]
+        ]) {
+          if (bounded[key] === void 0) continue;
+          const ms = durationMs(bounded[key]);
+          if (ms === null) {
+            return {
+              ...textContent(`${key} must be a duration such as "30s" or milliseconds.`),
+              isError: true
+            };
+          }
+          bounded[key] = bound(ms);
+        }
+        return handler(bounded);
+      } : handler;
+      const handle = target.tool(name, description, shape, wrapped);
+      handles.push(handle);
+      return handle;
+    }
+  };
+}
+function registerTools(target, client, options = {}) {
+  const handles = [];
+  const server = toolTarget(target, options.remote === true, handles);
   server.tool(
     "create_endpoint",
     "Create a webhook endpoint. Returns the endpoint slug, URL, and metadata.",
@@ -977,7 +1095,7 @@ function registerTools(server, client) {
   );
   server.tool(
     "update_endpoint",
-    "Update an endpoint name, mock response, conditional response rules, signing configuration, or whether codes and links are picked out of its emails.",
+    "Update an endpoint name, mock response, conditional response rules, signing configuration, whether codes and links are picked out of its emails, or the named fields picked out of them.",
     {
       slug: import_zod2.z.string().describe("The endpoint slug to update"),
       name: import_zod2.z.string().optional().describe("New display name"),
@@ -991,7 +1109,17 @@ function registerTools(server, client) {
       signingHeader: import_zod2.z.string().nullable().optional().describe(
         "Custom signature header name (only for generic-hmac provider), or null to clear"
       ),
-      showEmailExtracts: import_zod2.z.boolean().optional().describe("Pick codes and links out of emails (dashboard and forwarded JSON). Owner only.")
+      showEmailExtracts: import_zod2.z.boolean().optional().describe("Pick codes and links out of emails (dashboard and forwarded JSON). Owner only."),
+      emailFields: import_zod2.z.array(
+        import_zod2.z.object({
+          name: import_zod2.z.string().describe("Letters, digits and _, starting with a letter: {{ fields.name }}"),
+          from: import_zod2.z.enum(["subject", "text", "html", "from", "to", "header"]).describe("What it reads; html is the HTML as text"),
+          header: import_zod2.z.string().optional().describe('The header name, for from "header"'),
+          pattern: import_zod2.z.string().describe("RE2 regular expression; the first group is the value (no lookarounds)")
+        })
+      ).max(20).nullable().optional().describe(
+        "Named fields picked out of every email: shown with it, `fields` in its JSON, read by forwarding templates and filters (email_field). Replaces the list; null or [] removes them. Owner only."
+      )
     },
     withErrorHandling(
       async ({
@@ -1003,7 +1131,8 @@ function registerTools(server, client) {
         signingProvider,
         signingSecret,
         signingHeader,
-        showEmailExtracts
+        showEmailExtracts,
+        emailFields
       }) => {
         const endpoint = await client.endpoints.update(slug, {
           name,
@@ -1013,12 +1142,33 @@ function registerTools(server, client) {
           signingProvider,
           signingSecret,
           signingHeader,
-          showEmailExtracts
+          showEmailExtracts,
+          emailFields
         });
         return jsonContent(endpoint);
       }
     )
   );
+  server.tool(
+    "preview_response",
+    "Dry run of an endpoint's responses: which response rule answers a captured request, and the response with its {{ placeholders }} filled in, exactly as the receiver would send it. Nothing is sent. Pass mockResponse or responseRules to try settings before saving them with update_endpoint.",
+    {
+      slug: import_zod2.z.string().describe("The endpoint slug"),
+      requestId: import_zod2.z.string().optional().describe(
+        "A captured request on the endpoint (default: the newest HTTP request, or a sample)"
+      ),
+      mockResponse: mockResponseSchema.nullable().optional().describe("Try this default response instead of the saved one (null: none)"),
+      responseRules: responseRulesSchema.nullable().optional().describe("Try these rules instead of the saved ones (null: none)")
+    },
+    withErrorHandling(async ({ slug, requestId, mockResponse, responseRules }) => {
+      const preview = await client.endpoints.previewResponse(slug, {
+        ...requestId ? { requestId } : {},
+        ...mockResponse !== void 0 ? { mockResponse } : {},
+        ...responseRules !== void 0 ? { responseRules } : {}
+      });
+      return jsonContent(preview);
+    })
+  );
   server.tool(
     "delete_endpoint",
     "Delete a webhook endpoint and all its captured requests.",
@@ -1234,6 +1384,39 @@ function registerTools(server, client) {
       });
     })
   );
+  server.tool(
+    "render_email",
+    "A captured email in the shape an inbound mail provider posts it (postmark, sendgrid, mailgun, cloudmailin), to test the inbound handler you wrote for that provider against real mail. Returns the method, headers and body; with targetUrl (your local handler), posts it there and returns the answer. A Mailgun form is signed when you pass the signing key your handler checks.",
+    {
+      requestId: import_zod2.z.string().describe("The captured email's request ID"),
+      format: import_zod2.z.enum(["postmark", "sendgrid", "mailgun", "cloudmailin", "json"]).describe("Whose shape; json is webhooks.cc's own email.received JSON (unsigned)"),
+      mailgunSigningKey: import_zod2.z.string().optional().describe("For mailgun: the signing key your handler verifies with (a test key)"),
+      targetUrl: httpUrlSchema.optional().describe("Post it here, e.g. http://localhost:3000/api/inbound/postmark")
+    },
+    withErrorHandling(async ({ requestId, format, mailgunSigningKey, targetUrl }) => {
+      const rendered = await client.emails.render(requestId, {
+        format,
+        ...mailgunSigningKey ? { mailgunSigningKey } : {}
+      });
+      if (!targetUrl) {
+        return jsonContent(
+          shrinkRendered(rendered, MAX_BODY_SIZE)
+        );
+      }
+      const response = await fetch(targetUrl, {
+        method: "POST",
+        headers: { "content-type": rendered.headers["content-type"] },
+        body: rendered.body,
+        redirect: "manual"
+      });
+      return jsonContent({
+        format,
+        status: response.status,
+        statusText: response.statusText,
+        body: await readBodyTruncated(response)
+      });
+    })
+  );
   server.tool(
     "compare_requests",
     "Compare two captured requests and show the structured differences.",
@@ -1473,7 +1656,7 @@ function registerTools(server, client) {
         verifySignature: shouldVerify,
         cleanup
       }) => {
-        const flow = client.flow().createEndpoint({ expiresIn: "1h" }).waitForCapture({ timeout: "30s" });
+        const flow = client.flow().createEndpoint({ expiresIn: "1h" }).waitForCapture({ timeout: "30s", pollInterval: "1s" });
         if (mockStatus !== void 0) {
           flow.setMock({
             status: mockStatus,
@@ -1598,10 +1781,14 @@ function registerTools(server, client) {
       includeHtml: import_zod2.z.boolean().default(false).describe("Include the HTML part (default: false)")
     },
     withErrorHandling(async ({ endpointSlug, tag, subject, from, timeout, since, includeHtml }) => {
-      const [email, view] = await Promise.all([
-        client.emails.waitFor(endpointSlug, { tag, subject, from, timeout, since }),
-        emailEndpointView(client, endpointSlug)
-      ]);
+      const view = await emailEndpointView(client, endpointSlug);
+      const email = await client.emails.waitFor(endpointSlug, {
+        tag,
+        subject,
+        from,
+        timeout,
+        since
+      });
       return jsonContent(emailDetail(client, email, view, includeHtml));
     })
   );
@@ -1617,9 +1804,79 @@ function registerTools(server, client) {
       return jsonContent({ ...result, address: client.emails.address(slug, tag) });
     })
   );
+  server.tool(
+    "list_destinations",
+    "List where an endpoint's captures go: its destinations (up to 10) with their URL, kinds, filter, format, templates and timing, and with summary: true their last 24 hours. Owner only.",
+    {
+      slug: import_zod2.z.string().describe("The endpoint slug"),
+      summary: import_zod2.z.boolean().default(true).describe("Add each destination's last 24 hours")
+    },
+    withErrorHandling(async ({ slug, summary }) => {
+      return jsonContent(await client.destinations.list(slug, { summary }));
+    })
+  );
+  server.tool(
+    "add_destination",
+    "Add a destination for an endpoint's captures: your server (as received or signed JSON), a Slack or Discord channel (chat, optionally your own messageTemplate, throttleSeconds 1 for a heads-up), or a JSON body you shape with bodyTemplate (for Zapier, n8n or your API). filter sends only matching captures; delaySeconds makes it a callback. Each destination gets its own signing secret. Check it with preview_destination before relying on it. Owner only.",
+    {
+      slug: import_zod2.z.string().describe("The endpoint slug"),
+      url: httpUrlSchema.describe("https URL on a public host name, or a Slack or Discord webhook"),
+      ...destinationFields
+    },
+    withErrorHandling(async ({ slug, ...input }) => {
+      return jsonContent(await client.destinations.create(slug, input));
+    })
+  );
+  server.tool(
+    "update_destination",
+    "Change a destination: any of its fields; only the ones you pass change. Owner only.",
+    {
+      slug: import_zod2.z.string().describe("The endpoint slug"),
+      destinationId: import_zod2.z.string().describe("The destination's id (from list_destinations)"),
+      url: httpUrlSchema.optional().describe("A new URL"),
+      ...destinationFields
+    },
+    withErrorHandling(async ({ slug, destinationId, ...input }) => {
+      return jsonContent(await client.destinations.update(slug, destinationId, input));
+    })
+  );
+  server.tool(
+    "remove_destination",
+    "Remove a destination. Deliveries still waiting for it are marked failed; its log stays. Owner only.",
+    {
+      slug: import_zod2.z.string().describe("The endpoint slug"),
+      destinationId: import_zod2.z.string().describe("The destination's id")
+    },
+    withErrorHandling(async ({ slug, destinationId }) => {
+      await client.destinations.delete(slug, destinationId);
+      return textContent(`Destination ${destinationId} removed.`);
+    })
+  );
+  server.tool(
+    "preview_destination",
+    "Dry run of a destination against a captured request: whether its filter lets the request through and the exact request it would send (method, URL, headers, body with placeholders filled in). Nothing is sent. Use destinationId for a saved destination, destination for unsaved fields (on top of the saved ones, or with a url on their own), or both.",
+    {
+      slug: import_zod2.z.string().describe("The endpoint slug"),
+      destinationId: import_zod2.z.string().optional().describe("A saved destination"),
+      destination: import_zod2.z.object({ url: httpUrlSchema.optional(), ...destinationFields }).optional().describe("Unsaved fields to try"),
+      requestId: import_zod2.z.string().optional().describe("A captured request (default: the newest of the kind it takes, or a sample)")
+    },
+    withErrorHandling(async ({ slug, destinationId, destination, requestId }) => {
+      if (!destinationId && !destination?.url) {
+        throw new Error("Pass destinationId, or a destination with a url");
+      }
+      return jsonContent(
+        await client.destinations.preview(slug, {
+          ...destinationId ? { destinationId } : {},
+          ...destination ? { destination } : {},
+          ...requestId ? { requestId } : {}
+        })
+      );
+    })
+  );
   server.tool(
     "configure_forwarding",
-    "Change an endpoint's forwarding: the URL, on or off, which kinds (HTTP requests, emails), the format, your own headers, and the advanced options. Only the arguments you pass change. Owner only. Saving the first URL creates the signing secret. A Slack or Discord webhook URL gets a chat message automatically.",
+    "Change an endpoint's primary forwarding destination (the one the endpoint's forward* fields stand for): the URL, on or off, which kinds, the format, your own headers, and the advanced options. Only the arguments you pass change. Owner only. For several destinations, filters, templates, throttling or delays, use add_destination and update_destination.",
     {
       slug: import_zod2.z.string().describe("The endpoint slug"),
       url: httpUrlSchema.nullable().optional().describe("https URL on a public host name, or null to remove it (forwarding must be off)"),
@@ -1644,8 +1901,8 @@ function registerTools(server, client) {
         "JSON body field with the sender's own timestamp, e.g. publishedAt or data.publishedAt; null clears it"
       )
     },
-    withErrorHandling(async ({ slug, ...options }) => {
-      const endpoint = await client.forwarding.configure(slug, options);
+    withErrorHandling(async ({ slug, ...options2 }) => {
+      const endpoint = await client.forwarding.configure(slug, options2);
       return jsonContent({
         slug: endpoint.slug,
         forwardEnabled: endpoint.forwardEnabled ?? false,
@@ -1667,23 +1924,32 @@ function registerTools(server, client) {
     "Read (or with rotate: true, replace) the whsec_ secret forwarded deliveries are signed with. Owner only. Treat the value as a credential: put it in the handler's environment, not in code.",
     {
       slug: import_zod2.z.string().describe("The endpoint slug"),
+      destinationId: import_zod2.z.string().optional().describe("A destination (default: the endpoint's primary destination)"),
       rotate: import_zod2.z.boolean().default(false).describe("Replace the secret; every delivery from now on uses the new one")
     },
-    withErrorHandling(async ({ slug, rotate }) => {
-      const secret = rotate ? await client.forwarding.rotateSecret(slug) : await client.forwarding.secret(slug);
+    withErrorHandling(async ({ slug, destinationId, rotate }) => {
+      const secret = destinationId ? rotate ? await client.destinations.rotateSecret(slug, destinationId) : await client.destinations.secret(slug, destinationId) : rotate ? await client.forwarding.rotateSecret(slug) : await client.forwarding.secret(slug);
       return jsonContent({ secret, rotated: rotate });
     })
   );
   server.tool(
     "test_forwarding",
-    "Send the endpoint's newest captured request of a kind (or a sample) to its forwarding URL once, exactly as a delivery would go out, and report the answer. Works with forwarding on or off; nothing is retried or logged.",
+    "Send the endpoint's newest captured request of a kind (or a sample, or requestId) to a destination once, exactly as a delivery would go out, and report the answer. Works whether it is on or off, and whatever its filter says; nothing is retried or logged.",
     {
       slug: import_zod2.z.string().describe("The endpoint slug"),
-      kind: import_zod2.z.enum(["http", "email"]).optional().describe(
-        "Which kind to send (default: http when HTTP requests are forwarded, else email)"
-      )
+      destinationId: import_zod2.z.string().optional().describe("A destination (default: the endpoint's primary destination)"),
+      kind: import_zod2.z.enum(["http", "email"]).optional().describe("Which kind to send (default: http when the destination takes HTTP requests)"),
+      requestId: import_zod2.z.string().optional().describe("With destinationId: a captured request to send")
     },
-    withErrorHandling(async ({ slug, kind }) => {
+    withErrorHandling(async ({ slug, destinationId, kind, requestId }) => {
+      if (destinationId) {
+        return jsonContent(
+          await client.destinations.test(slug, destinationId, {
+            ...kind ? { kind } : {},
+            ...requestId ? { requestId } : {}
+          })
+        );
+      }
       return jsonContent(await client.forwarding.test(slug, kind ? { kind } : {}));
     })
   );
@@ -1694,17 +1960,25 @@ function registerTools(server, client) {
       endpointSlug: import_zod2.z.string().optional().describe("List the endpoint's delivery log"),
       requestId: import_zod2.z.string().optional().describe("List every delivery and try of this request"),
       limit: import_zod2.z.number().int().min(1).max(100).default(20).describe("With endpointSlug: max rows"),
-      status: import_zod2.z.enum(["all", "pending", "failed"]).default("all").describe("With endpointSlug: all, pending (queued or retrying) or failed"),
+      status: import_zod2.z.enum(["all", "pending", "failed", "skipped"]).default("all").describe(
+        "With endpointSlug: all, pending (queued or retrying), failed or skipped (filtered out)"
+      ),
+      destinationId: import_zod2.z.string().optional().describe("With endpointSlug: only this destination"),
       before: import_zod2.z.string().optional().describe("With endpointSlug: a row's cursor, to list older rows")
     },
-    withErrorHandling(async ({ endpointSlug, requestId, limit, status, before }) => {
+    withErrorHandling(async ({ endpointSlug, requestId, limit, status, destinationId, before }) => {
       if (requestId === void 0 === (endpointSlug === void 0)) {
         throw new Error("Pass exactly one of endpointSlug or requestId");
       }
       if (requestId) return jsonContent(await client.forwarding.requestDeliveries(requestId));
       const [summary, deliveries] = await Promise.all([
         client.forwarding.summary(endpointSlug),
-        client.forwarding.deliveries(endpointSlug, { limit, status, before })
+        client.forwarding.deliveries(endpointSlug, {
+          limit,
+          status,
+          before,
+          ...destinationId ? { destinationId } : {}
+        })
       ]);
       return jsonContent({
         summary,
@@ -1715,17 +1989,19 @@ function registerTools(server, client) {
   );
   server.tool(
     "redeliver",
-    "Forward again with the endpoint's current settings: one captured request or email (requestId; it also sends one that was never forwarded), or every request whose latest delivery failed (endpointSlug, oldest first, up to 1,000 at a time). Owner only; fails while forwarding is off.",
+    "Forward again with the current settings: one captured request or email (requestId; to every destination that takes it, or with destinationId to that one whatever its filter says), or every request whose latest delivery failed (endpointSlug, optionally only destinationId, oldest first, up to 1,000 at a time per destination). Owner only.",
     {
       requestId: import_zod2.z.string().optional().describe("The request or email to send again"),
-      endpointSlug: import_zod2.z.string().optional().describe("Send every failed delivery of this endpoint again")
+      endpointSlug: import_zod2.z.string().optional().describe("Send every failed delivery of this endpoint again"),
+      destinationId: import_zod2.z.string().optional().describe("Only this destination")
     },
-    withErrorHandling(async ({ requestId, endpointSlug }) => {
+    withErrorHandling(async ({ requestId, endpointSlug, destinationId }) => {
       if (requestId === void 0 === (endpointSlug === void 0)) {
         throw new Error("Pass exactly one of requestId or endpointSlug");
       }
+      const options2 = destinationId ? { destinationId } : {};
       return jsonContent(
-        requestId ? await client.forwarding.redeliver(requestId) : await client.forwarding.redeliverFailed(endpointSlug)
+        requestId ? await client.forwarding.redeliver(requestId, options2) : await client.forwarding.redeliverFailed(endpointSlug, options2)
       );
     })
   );
@@ -1738,6 +2014,7 @@ function registerTools(server, client) {
       return jsonContent(description);
     })
   );
+  return handles;
 }
 
 // src/sandbox-tools.ts
@@ -1749,7 +2026,6 @@ var SANDBOX = {
 };
 var DEFAULT_WAIT_SECONDS = 45;
 var MAX_WAIT_SECONDS = 600;
-var TOKEN_REFRESH_MARGIN_MS = 6e4;
 var DOCS_URL = "https://webhooks.cc/docs/agents";
 var ACCOUNT_ONLY_OPTIONS = [
   "mockResponse",
@@ -1760,20 +2036,29 @@ var ACCOUNT_ONLY_OPTIONS = [
   "signingHeader"
 ];
 var AgentSession = class {
-  constructor(baseUrl, webhookUrl, clientName) {
+  constructor(baseUrl, webhookUrl, clientName, credentialsFile) {
     this.baseUrl = baseUrl;
     this.webhookUrl = webhookUrl;
     this.clientName = clientName;
+    this.credentialsFile = credentialsFile;
     this.sandbox = null;
-    this.claim = null;
-    this.connected = false;
+    this.connect = null;
+  }
+  sandboxOptions() {
+    return {
+      baseUrl: this.baseUrl,
+      webhookUrl: this.webhookUrl,
+      clientName: this.clientName,
+      credentialsFile: this.credentialsFile
+    };
   }
   /**
-   * The sandbox, registered on first use and again after it expired. Tool
-   * calls can run in parallel: this.sandbox is read again after every await,
-   * and a new sandbox is assigned with no await in between, so parallel
-   * calls share one registration. Calls waiting on a registration that fails
-   * get its error (a 429 asks them to wait); the next call starts again.
+   * The sandbox: the one saved by an earlier session when it is still live,
+   * else a new registration (and again after it expired). Tool calls can run
+   * in parallel: this.sandbox is read again after every await, and a new
+   * sandbox is assigned with no await in between, so parallel calls share
+   * one registration. Calls waiting on a registration that fails get its
+   * error (a 429 asks them to wait); the next call starts again.
    */
   async sandboxClient() {
     while (this.sandbox) {
@@ -1781,35 +2066,36 @@ var AgentSession = class {
       const sandbox = await pending;
       if (!this.expired(pending, sandbox)) return sandbox;
     }
-    const created = import_sdk2.WebhooksCC.sandbox({
-      baseUrl: this.baseUrl,
-      webhookUrl: this.webhookUrl,
-      clientName: this.clientName
-    });
+    const created = import_sdk2.WebhooksCC.sandbox(this.sandboxOptions());
     this.sandbox = created;
     created.catch(() => {
       if (this.sandbox === created) this.sandbox = null;
     });
     return created;
   }
-  /** The live sandbox, if one was registered; never registers one. */
+  /** The live sandbox, from this session or the credential file; never registers one. */
   async existingSandbox() {
     const pending = this.sandbox;
-    if (!pending) return null;
-    let sandbox;
-    try {
-      sandbox = await pending;
-    } catch {
-      return null;
+    if (pending) {
+      let sandbox;
+      try {
+        sandbox = await pending;
+      } catch {
+        return null;
+      }
+      return this.expired(pending, sandbox) ? null : sandbox;
     }
-    return this.expired(pending, sandbox) ? null : sandbox;
+    const resumed = await import_sdk2.SandboxClient.resume(this.sandboxOptions()).catch(() => null);
+    if (!resumed) return null;
+    if (!this.sandbox) this.sandbox = Promise.resolve(resumed);
+    return this.sandbox;
   }
   /** True when the sandbox is past its 24 hours; then it is dropped. */
   expired(pending, sandbox) {
     if (sandbox.expiresAt.getTime() > Date.now()) return false;
     if (this.sandbox === pending) this.sandbox = null;
-    if (this.claim?.kind === "sandbox" && this.claim.claimToken === sandbox.registration.claimToken) {
-      this.claim = null;
+    if (this.connect?.via === "sandbox" && this.connect.sandbox === sandbox) {
+      this.connect = null;
     }
     return true;
   }
@@ -1820,26 +2106,11 @@ var AgentSession = class {
     }
     return sandbox;
   }
-  forgetSandbox() {
+  reset() {
     this.sandbox = null;
+    this.connect = null;
   }
 };
-function claimedTokens(baseUrl, assertion, first) {
-  let current = first;
-  let pending = null;
-  return async (options) => {
-    if (!options?.forceRefresh && current.expiresAt.getTime() - Date.now() > TOKEN_REFRESH_MARGIN_MS) {
-      return current.accessToken;
-    }
-    if (!pending) {
-      pending = import_sdk2.WebhooksCC.agent.exchange({ baseUrl, assertion }).finally(() => {
-        pending = null;
-      });
-    }
-    current = await pending;
-    return current.accessToken;
-  };
-}
 function minutesLeft(until) {
   return Math.max(1, Math.round((until.getTime() - Date.now()) / 6e4));
 }
@@ -1847,16 +2118,53 @@ function onlyKind(requests, kind) {
   if (!kind) return requests;
   return requests.filter((request) => (request.kind ?? "http") === kind);
 }
+function savedTo(credentialsFile) {
+  return import_sdk2.AgentCredentialStore.resolve(credentialsFile)?.path ?? null;
+}
 function registerSandboxTools(server, options = {}) {
   const baseUrl = options.baseUrl ?? process.env.WHK_BASE_URL ?? "https://webhooks.cc";
+  const webhookUrl = options.webhookUrl ?? process.env.WHK_WEBHOOK_URL;
   const session = new AgentSession(
     baseUrl,
-    options.webhookUrl ?? process.env.WHK_WEBHOOK_URL,
-    options.clientName ?? "webhooks-cc-mcp"
+    webhookUrl,
+    options.clientName ?? "webhooks-cc-mcp",
+    options.credentialsFile
   );
-  const registered = [];
+  let handles = [];
+  let shown = 0;
+  const swap = (register) => {
+    const id = ++shown;
+    for (const handle of handles) handle.remove();
+    handles = register(id);
+  };
+  const showSandbox = () => swap(() => sandboxToolSet(server, session, showAccount));
+  const savedAccount = (id) => options.credentialsFile === false ? null : import_sdk2.WebhooksCC.fromSavedConnection({
+    baseUrl,
+    webhookUrl,
+    credentialsFile: options.credentialsFile,
+    // The human disconnected the agent: back to the sandbox, unless a
+    // newer connection is already on display.
+    onRevoked: () => queueMicrotask(() => {
+      if (shown === id) showSandbox();
+    })
+  });
+  function showAccount(client) {
+    swap((id) => registerTools(server, savedAccount(id) ?? client));
+    options.onConnected?.(client);
+  }
+  const saved = savedAccount(1);
+  if (saved) {
+    swap(() => registerTools(server, saved));
+    options.onConnected?.(saved);
+  } else {
+    showSandbox();
+  }
+}
+function sandboxToolSet(server, session, showAccount) {
+  const tools = [];
   const limits = `up to ${SANDBOX.maxEndpoints} endpoints at a time, ${SANDBOX.requestsPerEndpoint} captured requests each and ${SANDBOX.requests} in all, deleted ${SANDBOX.lifetimeHours} hours after the sandbox was created`;
-  registered.push(
+  const file = savedTo(session.credentialsFile);
+  tools.push(
     server.tool(
       "create_endpoint",
       `Create a temporary webhook capture endpoint in the agent sandbox (no account needed): ${limits}. The first call registers the sandbox, which takes a few seconds of proof of work. Mock responses, notifications and signature verification need an account: see connect_account.`,
@@ -1880,7 +2188,7 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "list_endpoints",
       "List this agent's sandbox endpoints. Empty until create_endpoint starts the sandbox.",
@@ -1894,7 +2202,7 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "get_endpoint",
       "Get one of this agent's sandbox endpoints by slug, with its sandbox limits and usage.",
@@ -1904,7 +2212,7 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "delete_endpoint",
       "Delete one of this agent's sandbox endpoints and its captured requests. Frees a slot; the sandbox's request budget is not refunded.",
@@ -1915,7 +2223,7 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "list_requests",
       "List recent requests captured by a sandbox endpoint, newest first.",
@@ -1927,7 +2235,7 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "get_request",
       "Get full details for a request captured by a sandbox endpoint.",
@@ -1938,7 +2246,7 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "wait_for_request",
       "Wait for a request to arrive at a sandbox endpoint.",
@@ -1950,7 +2258,7 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "generate_payload_schema",
       "Generate TypeScript interfaces, Zod schemas, Pydantic models, or JSON Schema from the bodies of requests captured by a sandbox endpoint. Several requests of one event teach which fields are optional or nullable.",
@@ -1962,62 +2270,59 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "connect_account",
       "Connect this agent to a human's webhooks.cc account, for the full tool set (mock responses, signatures, email, teams) and to keep the sandbox endpoints. Returns a link and a 6-digit code: show both to the human, who signs in or signs up with that email and enters the code. Then call wait_for_connection. Calling again gives a new code.",
       {
-        email: import_zod3.z.string().email({ message: "Invalid email address" }).describe("The human's email address; only someone signed in as it can connect")
+        email: import_zod3.z.string().email({ message: "Invalid email address" }).describe(
+          "The email the human signs in to webhooks.cc with (their GitHub or Google primary email if they sign in that way); only someone signed in as it can connect"
+        )
       },
       withErrorHandling(async ({ email }) => {
-        if (session.connected) {
-          return jsonContent({ connected: true, message: "Already connected to an account." });
-        }
         const normalized = email.trim().toLowerCase();
+        const previous = session.connect;
         const sandbox = await session.existingSandbox();
-        let claim;
+        let attempt;
+        let movesEndpoints = false;
         if (sandbox) {
-          claim = {
-            kind: "sandbox",
-            claimToken: sandbox.registration.claimToken,
-            email: normalized,
-            attempt: await sandbox.claim({ email: normalized }),
-            claimExpires: sandbox.expiresAt
-          };
-        } else if (session.claim?.kind === "service_auth" && session.claim.email === normalized && session.claim.claimExpires.getTime() > Date.now()) {
-          const attempt = await import_sdk2.WebhooksCC.agent.startClaim({
-            baseUrl,
-            claimToken: session.claim.claimToken
-          });
-          claim = { ...session.claim, attempt };
+          const claim = await sandbox.claim({ email: normalized });
+          session.connect = { via: "sandbox", sandbox, email: normalized, attempt: claim };
+          attempt = claim;
+          movesEndpoints = claim.movesEndpoints;
         } else {
-          const registration = await import_sdk2.WebhooksCC.agent.registerServiceAuth({
-            baseUrl,
-            email: normalized,
-            clientName: session.clientName
-          });
-          claim = {
-            kind: "service_auth",
-            claimToken: registration.claimToken,
+          let pending = null;
+          if (previous?.via === "connect" && previous.email === normalized) {
+            pending = await previous.pending.restart().catch((error) => {
+              if (error instanceof import_sdk2.AgentAuthError) return null;
+              throw error;
+            });
+          }
+          pending ?? (pending = await import_sdk2.WebhooksCC.connect({
+            baseUrl: session.baseUrl,
+            webhookUrl: session.webhookUrl,
             email: normalized,
-            attempt: registration.claim,
-            claimExpires: registration.claimTokenExpires
-          };
+            clientName: session.clientName,
+            credentialsFile: session.credentialsFile
+          }));
+          session.connect = { via: "connect", pending, email: normalized };
+          attempt = pending;
         }
-        session.claim = claim;
-        const { verificationUri, userCode, expiresAt } = claim.attempt;
+        const { verificationUri, userCode, expiresAt } = attempt;
         return jsonContent({
           verificationUri,
           userCode,
           expiresAt: expiresAt.toISOString(),
           tellTheHuman: `Open ${verificationUri}, sign in or sign up as ${normalized}, and enter the code ${userCode}.`,
           next: `Show the human that line, then call wait_for_connection. The code works for about ${minutesLeft(expiresAt)} minutes; connect_account gives a new one.`,
-          ...claim.kind === "sandbox" ? { endpoints: "The sandbox endpoints move into that account with what they captured." } : {}
+          ...sandbox ? {
+            endpoints: movesEndpoints ? "The sandbox endpoints move into that account with what they captured." : "The sandbox endpoints were made in an earlier session, so they stay in the sandbox until it expires; the account starts without them."
+          } : {}
         });
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "wait_for_connection",
       `Wait for the human to enter the code from connect_account. On success the full webhooks.cc tools for their account replace these sandbox tools. Returns after timeoutSeconds (default ${DEFAULT_WAIT_SECONDS}) if they have not finished yet; call it again to keep waiting.`,
@@ -2025,28 +2330,22 @@ function registerSandboxTools(server, options = {}) {
         timeoutSeconds: import_zod3.z.number().int().min(1).max(MAX_WAIT_SECONDS).optional().describe(`How long to wait, in seconds (default ${DEFAULT_WAIT_SECONDS})`)
       },
       withErrorHandling(async ({ timeoutSeconds }) => {
-        if (session.connected) {
-          return jsonContent({ connected: true, message: "Already connected to an account." });
-        }
-        const claim = session.claim;
-        if (!claim) {
+        const pending = session.connect;
+        if (!pending) {
           throw new Error("Nothing to wait for: call connect_account first.");
         }
-        let claimed;
+        const timeout = (timeoutSeconds ?? DEFAULT_WAIT_SECONDS) * 1e3;
+        const expiresAt = pending.via === "sandbox" ? pending.attempt.expiresAt : pending.pending.expiresAt;
+        let client;
         try {
-          claimed = await import_sdk2.WebhooksCC.agent.waitForClaim({
-            baseUrl,
-            claimToken: claim.claimToken,
-            interval: claim.attempt.interval,
-            timeout: (timeoutSeconds ?? DEFAULT_WAIT_SECONDS) * 1e3
-          });
+          client = pending.via === "sandbox" ? await pending.sandbox.waitForClaim({ timeout }) : await pending.pending.wait({ timeout });
         } catch (error) {
           if (!(error instanceof import_sdk2.AgentAuthError)) throw error;
           if (error.code === "timeout") {
             return jsonContent({
               connected: false,
               status: "waiting",
-              message: `Not connected yet. The code works until ${claim.attempt.expiresAt.toISOString()}; call wait_for_connection again.`
+              message: `Not connected yet. The code works until ${expiresAt.toISOString()}; call wait_for_connection again.`
             });
           }
           if (error.code === "expired_token") {
@@ -2065,34 +2364,25 @@ function registerSandboxTools(server, options = {}) {
           }
           throw error;
         }
-        const client = new import_sdk2.WebhooksCC({
-          baseUrl,
-          webhookUrl: session.webhookUrl,
-          getAccessToken: claimedTokens(baseUrl, claimed.identityAssertion, claimed.token)
-        });
-        session.connected = true;
-        session.claim = null;
-        session.forgetSandbox();
-        for (const tool of registered) tool.remove();
-        registerTools(server, client);
-        options.onConnected?.(client);
+        const movedEndpoints = pending.via === "sandbox" && pending.attempt.movesEndpoints;
+        session.reset();
+        showAccount(client);
         return jsonContent({
           connected: true,
-          email: claim.email,
-          scope: claimed.token.scope,
-          message: `Connected to the webhooks.cc account of ${claim.email}. The full tool set has replaced the sandbox tools (the tool list changed; if your client does not pick that up, ask the user to restart it).${claim.kind === "sandbox" ? " The sandbox endpoints are now that account's endpoints, with what they captured." : ""} This connection lasts while this MCP server runs; for a lasting setup, the human can create an API key under Account and set WHK_API_KEY.`
+          email: pending.email,
+          message: `Connected to the webhooks.cc account of ${pending.email}. The full tool set has replaced the sandbox tools (the tool list changed; if your client does not pick that up, ask the user to restart it).${movedEndpoints ? " The sandbox endpoints are now that account's endpoints, with what they captured." : ""} ${file ? `The connection is saved in ${file}, so later sessions, the whk CLI and the SDKs start connected; it lasts 90 days, and the human can remove it under Account, Connected agents.` : "This connection lasts while this MCP server runs; for a lasting setup, the human can create an API key under Account and set WHK_API_KEY."}`
         });
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "about_sandbox",
       "Explain what this agent can do without a webhooks.cc account, the sandbox limits, and how to connect an account. No network call.",
       {},
       withErrorHandling(async () => {
         return jsonContent({
-          mode: "sandbox (no WHK_API_KEY)",
+          mode: "sandbox (no WHK_API_KEY, no saved connection)",
           sandbox: {
             maxEndpoints: SANDBOX.maxEndpoints,
             requestsPerEndpoint: SANDBOX.requestsPerEndpoint,
@@ -2103,21 +2393,23 @@ function registerSandboxTools(server, options = {}) {
             notAvailable: "Mock responses, response rules, notifications, signature verification, email capture, forwarding, teams and sending webhooks."
           },
           connectAnAccount: [
-            "Call connect_account with the human's email and show them the link and code it returns.",
+            "Call connect_account with the email the human signs in to webhooks.cc with, and show them the link and code it returns.",
             "Call wait_for_connection until it reports connected; the full tools for their account then replace the sandbox tools.",
-            "Sandbox endpoints move into the account with their captured requests."
+            "Sandbox endpoints registered by this server process move into the account with their captured requests; a sandbox resumed from an earlier session stays in the sandbox (connect_account says which)."
           ],
+          savedIn: file ? `${file} (shared with the whk CLI and the SDKs): the sandbox and the connection survive restarts.` : "nowhere: this session only.",
           withAnApiKey: "Set WHK_API_KEY to a whcc_ key from the dashboard and restart for the full tools from the start.",
           docs: DOCS_URL,
-          protocol: `${baseUrl}/auth.md`
+          protocol: `${session.baseUrl}/auth.md`
         });
       })
     )
   );
+  return tools;
 }
 
 // src/index.ts
-var VERSION = true ? "1.13.0" : "0.0.0-dev";
+var VERSION = true ? "1.15.0" : "0.0.0-dev";
 function createServer(options = {}) {
   const apiKey = options.apiKey ?? process.env.WHK_API_KEY;
   const webhookUrl = options.webhookUrl ?? process.env.WHK_WEBHOOK_URL;
@@ -2128,7 +2420,7 @@ function createServer(options = {}) {
     { debouncedNotificationMethods: ["notifications/tools/list_changed"] }
   );
   if (!apiKey) {
-    registerSandboxTools(server, { baseUrl, webhookUrl });
+    registerSandboxTools(server, { baseUrl, webhookUrl, credentialsFile: options.credentialsFile });
     registerPrompts(server);
     return server;
   }
@@ -2157,13 +2449,16 @@ function mcpServerConfig(apiKey) {
   return {
     command: "npx",
     args: ["-y", "@webhooks-cc/mcp"],
-    env: { WHK_API_KEY: apiKey }
+    ...apiKey ? { env: { WHK_API_KEY: apiKey } } : {}
   };
 }
+function vscodeServerConfig(apiKey) {
+  return { type: "stdio", ...mcpServerConfig(apiKey) };
+}
 function resolveApiKey(flags) {
   return flags["api-key"] ?? process.env.WHK_API_KEY ?? null;
 }
-function mergeJsonConfig(filePath, serverName, serverConfig) {
+function mergeJsonConfig(filePath, serverName, serverConfig, key = "mcpServers") {
   let existing = {};
   if ((0, import_fs.existsSync)(filePath)) {
     try {
@@ -2174,9 +2469,9 @@ function mergeJsonConfig(filePath, serverName, serverConfig) {
       (0, import_fs.copyFileSync)(filePath, `${filePath}.bak`);
     }
   }
-  const mcpServers = existing.mcpServers ?? {};
-  mcpServers[serverName] = serverConfig;
-  existing.mcpServers = mcpServers;
+  const servers = existing[key] ?? {};
+  servers[serverName] = serverConfig;
+  existing[key] = servers;
   const dir = (0, import_path.dirname)(filePath);
   if (!(0, import_fs.existsSync)(dir)) (0, import_fs.mkdirSync)(dir, { recursive: true });
   (0, import_fs.writeFileSync)(filePath, JSON.stringify(existing, null, 2) + "\n");
@@ -2213,8 +2508,7 @@ function setupClaudeCode(apiKey) {
         "--transport",
         "stdio",
         "webhooks-cc",
-        "-e",
-        `WHK_API_KEY=${apiKey}`,
+        ...apiKey ? ["-e", `WHK_API_KEY=${apiKey}`] : [],
         "--",
         "npx",
         "-y",
@@ -2229,7 +2523,7 @@ function setupClaudeCode(apiKey) {
     console.error("Install it: npm install -g @anthropic-ai/claude-code");
     console.error("\nManual alternative \u2014 run this command:");
     console.error(
-      `  claude mcp add -s user --transport stdio webhooks-cc -e WHK_API_KEY=<your-key> -- npx -y @webhooks-cc/mcp`
+      `  claude mcp add -s user --transport stdio webhooks-cc${apiKey ? " -e WHK_API_KEY=<your-key>" : ""} -- npx -y @webhooks-cc/mcp`
     );
     process.exit(1);
   }
@@ -2248,7 +2542,7 @@ function setupCursor(apiKey) {
 }
 function setupVSCode(apiKey) {
   const configPath = (0, import_path.join)(process.cwd(), ".vscode", "mcp.json");
-  mergeJsonConfig(configPath, "webhooks-cc", mcpServerConfig(apiKey));
+  mergeJsonConfig(configPath, "webhooks-cc", vscodeServerConfig(apiKey), "servers");
   console.log(`Done! Config written to ${configPath}`);
   console.log("Reload VS Code window for changes to take effect.");
 }
@@ -2260,8 +2554,7 @@ function setupCodex(apiKey) {
         "mcp",
         "add",
         "webhooks-cc",
-        "-e",
-        `WHK_API_KEY=${apiKey}`,
+        ...apiKey ? ["-e", `WHK_API_KEY=${apiKey}`] : [],
         "--",
         "npx",
         "-y",
@@ -2274,13 +2567,13 @@ function setupCodex(apiKey) {
     console.error("\nFailed to run 'codex mcp add'. Is OpenAI Codex CLI installed?");
     console.error("\nManual alternative \u2014 add to ~/.codex/config.toml:");
     console.error(`
-[mcp.webhooks-cc]
+[mcp_servers.webhooks-cc]
 command = "npx"
 args = ["-y", "@webhooks-cc/mcp"]
-
-[mcp.webhooks-cc.env]
+${apiKey ? `
+[mcp_servers.webhooks-cc.env]
 WHK_API_KEY = "<your-key>"
-`);
+` : ""}`);
     process.exit(1);
   }
 }
@@ -2297,6 +2590,9 @@ function printUsage() {
 Usage:
   npx @webhooks-cc/mcp setup <tool> [--api-key <key>]
 
+Without a key the server starts in the keyless agent sandbox; your agent can
+connect your account later (connect_account), and the connection is saved.
+
 Tools:
   claude-code      Claude Code CLI (runs 'claude mcp add')
   claude-desktop   Claude Desktop app
@@ -2306,9 +2602,10 @@ Tools:
   windsurf         Windsurf editor
 
 Options:
-  --api-key <key>  Your webhooks.cc API key (or set WHK_API_KEY env var)
+  --api-key <key>  Your webhooks.cc API key (or set WHK_API_KEY env var); optional
 
 Examples:
+  npx @webhooks-cc/mcp setup claude-code
   npx @webhooks-cc/mcp setup claude-code --api-key whcc_abc123
   WHK_API_KEY=whcc_abc123 npx @webhooks-cc/mcp setup cursor
   npx @webhooks-cc/mcp setup vscode --api-key whcc_abc123
@@ -2336,14 +2633,13 @@ function runSetup(args2) {
     process.exit(tool ? 1 : 0);
   }
   const apiKey = resolveApiKey(flags);
-  if (!apiKey) {
-    console.error("Error: API key required. Pass --api-key or set WHK_API_KEY env var.");
-    console.error("Get your API key at https://webhooks.cc/account/api-keys\n");
-    process.exit(1);
-  }
-  validateApiKeyFormat(apiKey);
+  if (apiKey) validateApiKeyFormat(apiKey);
   console.log(`Setting up webhooks-cc MCP server for ${tool}...
 `);
+  if (!apiKey) {
+    console.log("No API key: the server starts in the keyless agent sandbox. Your agent can");
+    console.log("connect your account later with connect_account; the connection is saved.\n");
+  }
   switch (tool) {
     case "claude-code":
       setupClaudeCode(apiKey);
@@ -2381,17 +2677,25 @@ Usage:
   npx @webhooks-cc/mcp --help             Show this help
 
 Environment:
-  WHK_API_KEY        Your webhooks.cc API key (required)
+  WHK_API_KEY        Your webhooks.cc API key (optional; without it the server
+                     starts connected to the account your agent was connected
+                     to before, or in the keyless agent sandbox)
+  WHK_AGENT_FILE     Where the sandbox and the connection are saved (default:
+                     ~/.config/whk/agent.json, shared with the whk CLI and SDKs)
   WHK_WEBHOOK_URL    Custom webhook receiver URL (optional)
   WHK_BASE_URL       Custom API base URL (optional)
 
 Setup:
-  npx @webhooks-cc/mcp setup claude-code --api-key whcc_...
-  npx @webhooks-cc/mcp setup cursor --api-key whcc_...
-  npx @webhooks-cc/mcp setup vscode --api-key whcc_...
-  npx @webhooks-cc/mcp setup codex --api-key whcc_...
-  npx @webhooks-cc/mcp setup windsurf --api-key whcc_...
-  npx @webhooks-cc/mcp setup claude-desktop --api-key whcc_...
+  npx @webhooks-cc/mcp setup claude-code
+  npx @webhooks-cc/mcp setup cursor
+  npx @webhooks-cc/mcp setup vscode
+  npx @webhooks-cc/mcp setup codex
+  npx @webhooks-cc/mcp setup windsurf
+  npx @webhooks-cc/mcp setup claude-desktop
+  (add --api-key whcc_... to start with your account's tools)
+
+Hosted agents (claude.ai, ChatGPT): add https://webhooks.cc/mcp as a remote
+MCP server instead; you approve it once in your browser.
 
 Get your API key at https://webhooks.cc/account/api-keys
 `);