@webhooks-cc/mcp 1.9.0 → 1.10.1

package/README.md

@@ -58,7 +58,7 @@ Get your API key at [webhooks.cc/account](https://webhooks.cc/account).
 
 ## What it exposes
 
-The server exposes `35` tools, `3` prompts, and `3` resource surfaces.
+The server exposes `44` tools, `3` prompts, and `3` resource surfaces.
 
 ### Endpoint tools
 
@@ -84,6 +84,27 @@ The server exposes `35` tools, `3` prompts, and `3` resource surfaces.
 - `verify_signature`
 - `clear_requests`
 
+### Email tools
+
+Every endpoint on an account receives email at `{slug}@mailhooks.cc` (and `{slug}+{tag}@mailhooks.cc`). These tools read it, with the one-time code and main link already picked out, unless the endpoint's owner turned that off:
+
+- `list_emails`
+- `get_email`
+- `wait_for_email`
+- `send_test_email`
+
+The request tools and resources return emails too (filter with `kind`), without the raw message or the HTML part and with the text cut at 8,000 characters; `get_email` returns the HTML.
+
+### Forwarding tools
+
+Forward every captured email to a URL as signed JSON (owner only):
+
+- `configure_forwarding`
+- `get_forwarding_secret` (returns the `whsec_` secret; with `rotate: true`, replaces it)
+- `test_forwarding`
+- `list_deliveries`
+- `redeliver_email`
+
 ### Send and test tools
 
 - `send_webhook`

package/dist/bin/mcp.js

@@ -120,6 +120,149 @@ function registerPrompts(server) {
 
 // src/resources.ts
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+
+// src/compact.ts
+var MAX_OUTPUT = 32768;
+var MAX_EMAIL_TEXT = 8e3;
+var MAX_EXTRACTS = 10;
+var MAX_LINK_TEXT = 200;
+var MAX_LINK_URL = 2e3;
+var MAX_LIST_ITEMS = 5;
+var EMAIL_LISTS = ["from", "to", "cc", "replyTo", "sender", "inReplyTo", "attachments"];
+var TEXT_FLOOR = 2e3;
+function jsonSize(value) {
+  return JSON.stringify(value, null, 2).length;
+}
+function sliceText(text, end) {
+  if (end <= 0) return "";
+  if (end >= text.length) return text;
+  const last = text.charCodeAt(end - 1);
+  return text.slice(0, last >= 55296 && last <= 56319 ? end - 1 : end);
+}
+function cutEmailText(text) {
+  if (text === null || text.length <= MAX_EMAIL_TEXT) return { text, cut: false };
+  return { text: sliceText(text, MAX_EMAIL_TEXT), cut: true };
+}
+function shrinkToFit(root, budget, steps) {
+  for (const step of steps) {
+    if (jsonSize(root) <= budget) return;
+    step();
+  }
+}
+function omitHeaders(holder) {
+  const headers = holder.headers;
+  if (headers === null || typeof headers !== "object") return;
+  const count = Object.keys(headers).length;
+  if (count === 0) return;
+  holder.headers = {};
+  holder.headersOmitted = `${count} headers left out to fit the output`;
+}
+function capExtracts(holder) {
+  if (Array.isArray(holder.codes) && holder.codes.length > MAX_EXTRACTS) {
+    holder.codes = holder.codes.slice(0, MAX_EXTRACTS);
+    holder.codesTruncated = true;
+  }
+  if (Array.isArray(holder.links)) {
+    if (holder.links.length > MAX_EXTRACTS) {
+      holder.links = holder.links.slice(0, MAX_EXTRACTS);
+      holder.linksTruncated = true;
+    }
+    holder.links = holder.links.map((link) => ({
+      ...link,
+      ...typeof link.url === "string" ? { url: sliceText(link.url, MAX_LINK_URL) } : {},
+      ...typeof link.text === "string" ? { text: sliceText(link.text, MAX_LINK_TEXT) } : {}
+    }));
+  }
+}
+function capLists(holder) {
+  for (const key of EMAIL_LISTS) {
+    const list = holder[key];
+    if (Array.isArray(list) && list.length > MAX_LIST_ITEMS) {
+      holder[key] = list.slice(0, MAX_LIST_ITEMS);
+      holder[`${key}Total`] = list.length;
+    }
+  }
+}
+function keepOnly(holder, keep) {
+  for (const key of Object.keys(holder)) {
+    if (!keep.includes(key)) delete holder[key];
+  }
+  holder.trimmed = "The email was too big for the output, so only these fields are shown.";
+}
+function cutStringToFit(root, holder, key, flag, budget, floor = 0) {
+  const value = holder[key];
+  if (typeof value !== "string" || value.length <= floor) return;
+  const flagged = holder[flag] === true;
+  holder[key] = "";
+  holder[flag] = true;
+  const room = budget - jsonSize(root) + 2;
+  let low = 0;
+  let high = value.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (JSON.stringify(sliceText(value, mid)).length <= room) low = mid;
+    else high = mid - 1;
+  }
+  const kept = sliceText(value, Math.max(low, floor));
+  holder[key] = kept;
+  if (kept.length === value.length && !flagged) delete holder[flag];
+}
+function keepFirst(holder, key) {
+  const list = holder[key];
+  if (!Array.isArray(list) || list.length <= 1) return;
+  holder[`${key}Total`] = holder[`${key}Total`] ?? list.length;
+  holder[key] = list.slice(0, 1);
+}
+var ESSENTIAL_EMAIL_FIELDS = [
+  "subject",
+  "from",
+  "fromTotal",
+  "tag",
+  "date",
+  "text",
+  "textTruncated",
+  "htmlSize"
+];
+function compactRequest(request) {
+  if (request.kind !== "email") return request;
+  const compact = { ...request };
+  delete compact.body;
+  delete compact.bodyRaw;
+  compact.rawMessageOmitted = "The raw message and the HTML part are left out; size is the message size in bytes. get_email returns the HTML.";
+  if (!request.email) return compact;
+  const { html, ...rest } = request.email;
+  const { text, cut } = cutEmailText(rest.text);
+  const restoreText = () => {
+    email.text = text;
+    if (cut) email.textTruncated = true;
+    else delete email.textTruncated;
+  };
+  const email = {
+    ...rest,
+    text,
+    ...cut ? { textTruncated: true } : {},
+    htmlSize: html?.length ?? 0
+  };
+  compact.email = email;
+  const root = { items: [compact], truncated: true, total: 1e3, returned: 1e3 };
+  const budget = MAX_OUTPUT - 128;
+  shrinkToFit(root, budget, [
+    () => omitHeaders(compact),
+    () => capLists(email),
+    () => cutStringToFit(root, email, "text", "textTruncated", budget, TEXT_FLOOR),
+    // Down to the essentials there may be room for more of the text again.
+    () => {
+      keepOnly(email, ESSENTIAL_EMAIL_FIELDS);
+      keepFirst(email, "from");
+      restoreText();
+      cutStringToFit(root, email, "text", "textTruncated", budget);
+    },
+    () => cutStringToFit(root, email, "subject", "subjectTruncated", budget)
+  ]);
+  return compact;
+}
+
+// src/resources.ts
 var ENDPOINTS_RESOURCE_URI = "webhooks://endpoints";
 var ENDPOINT_RECENT_TEMPLATE_URI = "webhooks://endpoint/{slug}/recent";
 var REQUEST_TEMPLATE_URI = "webhooks://request/{id}";
@@ -217,7 +360,7 @@ function registerResources(server, client) {
       ]);
       return jsonResource(uri.toString(), {
         endpoint,
-        requests
+        requests: requests.map(compactRequest)
       });
     }
   );
@@ -235,7 +378,7 @@ function registerResources(server, client) {
     async (uri, variables) => {
       const id = variableToString(variables.id, "id");
       const request = await client.requests.get(id);
-      return jsonResource(uri.toString(), request);
+      return jsonResource(uri.toString(), compactRequest(request));
     }
   );
 }
@@ -243,7 +386,7 @@ function registerResources(server, client) {
 // src/tools.ts
 var import_zod2 = require("zod");
 var import_sdk = require("@webhooks-cc/sdk");
-var MAX_BODY_SIZE = 32768;
+var MAX_BODY_SIZE = MAX_OUTPUT;
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
 var TIME_SEPARATOR = " \u2014 ";
 var httpUrlSchema = import_zod2.z.string().url().refine(
@@ -258,6 +401,8 @@ var httpUrlSchema = import_zod2.z.string().url().refine(
   { message: "Only http and https URLs are supported" }
 );
 var methodSchema = import_zod2.z.enum(HTTP_METHODS).default("POST").describe("HTTP method (default: POST)");
+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"),
@@ -337,6 +482,24 @@ function serializeJson(value, limit = MAX_BODY_SIZE) {
   return full.slice(0, limit) + `
 ... [truncated, ${full.length} chars total]`;
 }
+function fitArrayField(value, key) {
+  const items = value[key];
+  if (!Array.isArray(items) || jsonSize(value) <= MAX_BODY_SIZE) return value;
+  const cut = (count) => ({
+    ...value,
+    [key]: items.slice(0, count),
+    truncated: true,
+    returned: count
+  });
+  let low = 0;
+  let high = items.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (jsonSize(cut(mid)) <= MAX_BODY_SIZE) low = mid;
+    else high = mid - 1;
+  }
+  return cut(low);
+}
 function jsonContent(value) {
   return textContent(serializeJson(value));
 }
@@ -485,6 +648,99 @@ async function summarizeResponse(response) {
     body: await readBodyTruncated(response)
   };
 }
+async function emailEndpointView(client, slug) {
+  const endpoint = await client.endpoints.get(slug);
+  return {
+    endpoint: { slug: endpoint.slug, name: endpoint.name ?? null },
+    includeExtracts: endpoint.showEmailExtracts !== false
+  };
+}
+function emailSlugFromAddress(address) {
+  const local = address.slice(0, Math.max(0, address.lastIndexOf("@")));
+  return local.split("+")[0].toLowerCase();
+}
+var MAX_SUMMARY_LINK = 8e3;
+function boundedLink(link, max) {
+  if (link == null || link.length <= max) return { link: link ?? null };
+  return {
+    link: null,
+    linkOmitted: `The main link is ${link.length} characters long, too long for the output`
+  };
+}
+var MAX_SUMMARY_FIELD = 1e3;
+function summarizeEmail(email, includeExtracts) {
+  const from = email.email.from[0];
+  const sender = from ? from.name ? `${from.name} <${from.address ?? ""}>` : from.address : null;
+  const subject = email.email.subject;
+  return {
+    id: email.id,
+    receivedAt: new Date(email.receivedAt).toISOString(),
+    address: email.path,
+    tag: email.email.tag,
+    subject: subject === null ? null : sliceText(subject, MAX_SUMMARY_FIELD),
+    from: sender == null ? null : sliceText(sender, MAX_SUMMARY_FIELD),
+    ...includeExtracts ? { code: (0, import_sdk.extractCode)(email), ...boundedLink((0, import_sdk.extractLink)(email), MAX_SUMMARY_LINK) } : {},
+    attachments: email.email.attachments.length
+  };
+}
+var ESSENTIAL_DETAIL_FIELDS = [
+  "code",
+  "link",
+  "id",
+  "endpoint",
+  "receivedAt",
+  "address",
+  "tag",
+  "subject",
+  "from",
+  "size",
+  "test",
+  "text",
+  "textTruncated",
+  "htmlSize",
+  "html",
+  "htmlTruncated"
+];
+function emailDetail(client, email, view, includeHtml) {
+  const { data } = client.emails.toJson(email, {
+    endpoint: view.endpoint,
+    includeExtracts: view.includeExtracts
+  });
+  const { html, text: fullText, ...rest } = data;
+  const { text, cut } = cutEmailText(fullText ?? null);
+  const restoreText = () => {
+    detail.text = text;
+    if (cut) detail.textTruncated = true;
+    else delete detail.textTruncated;
+  };
+  const detail = {
+    ...view.includeExtracts ? { code: (0, import_sdk.extractCode)(email), link: (0, import_sdk.extractLink)(email) } : {},
+    ...rest,
+    text,
+    ...cut ? { textTruncated: true } : {},
+    htmlSize: html?.length ?? 0,
+    ...includeHtml && html !== null ? { html } : {}
+  };
+  shrinkToFit(detail, MAX_BODY_SIZE, [
+    () => omitHeaders(detail),
+    () => capExtracts(detail),
+    () => capLists(detail),
+    () => cutStringToFit(detail, detail, "html", "htmlTruncated", MAX_BODY_SIZE),
+    () => cutStringToFit(detail, detail, "text", "textTruncated", MAX_BODY_SIZE, TEXT_FLOOR),
+    // Down to the essentials (and without a main link too long to use) there
+    // may be room for more of the text again.
+    () => {
+      keepOnly(detail, ESSENTIAL_DETAIL_FIELDS);
+      if (view.includeExtracts) {
+        Object.assign(detail, boundedLink(detail.link, MAX_BODY_SIZE / 2));
+      }
+      restoreText();
+      cutStringToFit(detail, detail, "text", "textTruncated", MAX_BODY_SIZE);
+    },
+    () => cutStringToFit(detail, detail, "subject", "subjectTruncated", MAX_BODY_SIZE)
+  ]);
+  return detail;
+}
 function registerTools(server, client) {
   server.tool(
     "create_endpoint",
@@ -628,7 +884,7 @@ function registerTools(server, client) {
   );
   server.tool(
     "update_endpoint",
-    "Update an endpoint name, mock response, conditional response rules, or signing configuration.",
+    "Update an endpoint name, mock response, conditional response rules, signing configuration, or whether codes and links are picked out of its emails.",
     {
       slug: import_zod2.z.string().describe("The endpoint slug to update"),
       name: import_zod2.z.string().optional().describe("New display name"),
@@ -641,7 +897,8 @@ function registerTools(server, client) {
       signingSecret: import_zod2.z.string().nullable().optional().describe("New signing secret (encrypted server-side). Pass null to clear."),
       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.")
     },
     withErrorHandling(
       async ({
@@ -652,7 +909,8 @@ function registerTools(server, client) {
         notificationUrl,
         signingProvider,
         signingSecret,
-        signingHeader
+        signingHeader,
+        showEmailExtracts
       }) => {
         const endpoint = await client.endpoints.update(slug, {
           name,
@@ -661,7 +919,8 @@ function registerTools(server, client) {
           notificationUrl,
           signingProvider,
           signingSecret,
-          signingHeader
+          signingHeader,
+          showEmailExtracts
         });
         return jsonContent(endpoint);
       }
@@ -773,15 +1032,16 @@ function registerTools(server, client) {
   );
   server.tool(
     "list_requests",
-    "List recent captured requests for an endpoint.",
+    "List recent captured requests for an endpoint, HTTP requests and emails together (filter with kind). For emails, list_emails is shorter.",
     {
       endpointSlug: import_zod2.z.string().describe("The endpoint slug"),
       limit: import_zod2.z.number().int().min(1).max(100).default(25).describe("Max requests to return"),
-      since: import_zod2.z.number().optional().describe("Only return requests after this timestamp in ms")
+      since: import_zod2.z.number().optional().describe("Only return requests after this timestamp in ms"),
+      kind: kindSchema
     },
-    withErrorHandling(async ({ endpointSlug, limit, since }) => {
-      const requests = await client.requests.list(endpointSlug, { limit, since });
-      return jsonContent(requests);
+    withErrorHandling(async ({ endpointSlug, limit, since, kind }) => {
+      const requests = await client.requests.list(endpointSlug, { limit, since, kind });
+      return jsonContent(requests.map(compactRequest));
     })
   );
   server.tool(
@@ -790,6 +1050,7 @@ function registerTools(server, client) {
     {
       slug: import_zod2.z.string().optional().describe("Filter to a specific endpoint slug"),
       method: import_zod2.z.string().optional().describe("Filter by HTTP method"),
+      kind: kindSchema,
       q: import_zod2.z.string().optional().describe("Free-text search across path, body, and headers"),
       from: durationOrTimestampSchema.optional().describe('Start time as a timestamp or duration like "1h" or "7d"'),
       to: durationOrTimestampSchema.optional().describe('End time as a timestamp or duration like "1h" or "7d"'),
@@ -797,10 +1058,11 @@ function registerTools(server, client) {
       offset: import_zod2.z.number().int().min(0).max(1e4).default(0).describe("Result offset"),
       order: import_zod2.z.enum(["asc", "desc"]).default("desc").describe("Sort order by received time")
     },
-    withErrorHandling(async ({ slug, method, q, from, to, limit, offset, order }) => {
+    withErrorHandling(async ({ slug, method, kind, q, from, to, limit, offset, order }) => {
       const results = await client.requests.search({
         slug,
         method,
+        kind,
         q,
         from,
         to,
@@ -808,7 +1070,7 @@ function registerTools(server, client) {
         offset,
         order
       });
-      return jsonContent(results);
+      return jsonContent(results.map(compactRequest));
     })
   );
   server.tool(
@@ -817,12 +1079,13 @@ function registerTools(server, client) {
     {
       slug: import_zod2.z.string().optional().describe("Filter to a specific endpoint slug"),
       method: import_zod2.z.string().optional().describe("Filter by HTTP method"),
+      kind: kindSchema,
       q: import_zod2.z.string().optional().describe("Free-text search across path, body, and headers"),
       from: durationOrTimestampSchema.optional().describe('Start time as a timestamp or duration like "1h" or "7d"'),
       to: durationOrTimestampSchema.optional().describe('End time as a timestamp or duration like "1h" or "7d"')
     },
-    withErrorHandling(async ({ slug, method, q, from, to }) => {
-      const count = await client.requests.count({ slug, method, q, from, to });
+    withErrorHandling(async ({ slug, method, kind, q, from, to }) => {
+      const count = await client.requests.count({ slug, method, kind, q, from, to });
       return jsonContent({ count });
     })
   );
@@ -832,7 +1095,7 @@ function registerTools(server, client) {
     { requestId: import_zod2.z.string().describe("The request ID") },
     withErrorHandling(async ({ requestId }) => {
       const request = await client.requests.get(requestId);
-      return jsonContent(request);
+      return jsonContent(compactRequest(request));
     })
   );
   server.tool(
@@ -845,7 +1108,7 @@ function registerTools(server, client) {
     },
     withErrorHandling(async ({ endpointSlug, timeout, pollInterval }) => {
       const request = await client.requests.waitFor(endpointSlug, { timeout, pollInterval });
-      return jsonContent(request);
+      return jsonContent(compactRequest(request));
     })
   );
   server.tool(
@@ -865,7 +1128,9 @@ function registerTools(server, client) {
         pollInterval,
         method
       });
-      return jsonContent(result);
+      return jsonContent(
+        fitArrayField({ ...result, requests: result.requests.map(compactRequest) }, "requests")
+      );
     })
   );
   server.tool(
@@ -1174,6 +1439,154 @@ function registerTools(server, client) {
       }
     )
   );
+  server.tool(
+    "list_emails",
+    "List the emails an endpoint received at its mailhooks.cc address, newest first: subject, sender, tag, and the one-time code and main link found in each.",
+    {
+      endpointSlug: import_zod2.z.string().describe("The endpoint slug"),
+      limit: import_zod2.z.number().int().min(1).max(100).default(25).describe(
+        `Max emails to return. With tag, subject or from, the newest ${EMAIL_SCAN_LIMIT} emails are searched.`
+      ),
+      since: import_zod2.z.number().optional().describe("Only emails received after this timestamp in ms"),
+      tag: import_zod2.z.string().optional().describe("Only emails sent to {slug}+{tag}@mailhooks.cc (exact, case-sensitive)"),
+      subject: import_zod2.z.string().optional().describe("Only emails whose subject contains this text"),
+      from: import_zod2.z.string().optional().describe("Only emails from this address (case-insensitive)")
+    },
+    withErrorHandling(async ({ endpointSlug, limit, since, tag, subject, from }) => {
+      const filtered = tag !== void 0 || subject !== void 0 || from !== void 0;
+      const scan = filtered ? Math.max(limit, EMAIL_SCAN_LIMIT) : limit;
+      const [emails, view] = await Promise.all([
+        client.emails.list(endpointSlug, { limit: scan, since, tag, subject, from }),
+        emailEndpointView(client, endpointSlug)
+      ]);
+      return jsonContent(
+        emails.slice(0, limit).map((email) => summarizeEmail(email, view.includeExtracts))
+      );
+    })
+  );
+  server.tool(
+    "get_email",
+    "Get one captured email: by requestId, or the newest at an endpoint (optionally with a tag). Returns the parsed message with its one-time code and main link.",
+    {
+      requestId: import_zod2.z.string().optional().describe("The email's request ID"),
+      endpointSlug: import_zod2.z.string().optional().describe("Get the newest email at this endpoint instead (with requestId unset)"),
+      tag: import_zod2.z.string().optional().describe("With endpointSlug: only emails sent to this +tag"),
+      includeHtml: import_zod2.z.boolean().default(false).describe("Include the HTML part (default: false, only its size)")
+    },
+    withErrorHandling(async ({ requestId, endpointSlug, tag, includeHtml }) => {
+      if (requestId === void 0 === (endpointSlug === void 0)) {
+        throw new Error("Pass exactly one of requestId or endpointSlug");
+      }
+      const email = requestId ? await client.emails.get(requestId) : await client.emails.latest(endpointSlug, { tag });
+      if (!email) {
+        throw new import_sdk.NotFoundError(
+          `No email at ${endpointSlug}${tag ? ` with tag "${tag}"` : ""} yet. Send one with send_test_email, or wait with wait_for_email.`
+        );
+      }
+      const view = await emailEndpointView(
+        client,
+        endpointSlug ?? emailSlugFromAddress(email.path)
+      );
+      return jsonContent(emailDetail(client, email, view, includeHtml));
+    })
+  );
+  server.tool(
+    "wait_for_email",
+    "Wait for an email to arrive at an endpoint (for example after triggering a signup), then return it with its one-time code and main link. Use a tag per run to find your own email.",
+    {
+      endpointSlug: import_zod2.z.string().describe("The endpoint slug"),
+      tag: import_zod2.z.string().optional().describe("Only emails sent to {slug}+{tag}@mailhooks.cc"),
+      subject: import_zod2.z.string().optional().describe("Only emails whose subject contains this text"),
+      from: import_zod2.z.string().optional().describe("Only emails from this address (case-insensitive)"),
+      timeout: durationOrTimestampSchema.default("30s").describe(
+        `How long to wait (default "30s"). Keep it under your MCP client's request timeout, often 60 seconds.`
+      ),
+      since: import_zod2.z.number().optional().describe("Only emails received after this timestamp in ms (default: five minutes ago)"),
+      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)
+      ]);
+      return jsonContent(emailDetail(client, email, view, includeHtml));
+    })
+  );
+  server.tool(
+    "send_test_email",
+    "Deliver a sample email (with a 6-digit code and a link) to an endpoint, optionally to a +tag address. It counts as one request and skips SMTP, so sender checks do not run on it.",
+    {
+      slug: import_zod2.z.string().describe("The endpoint slug"),
+      tag: import_zod2.z.string().optional().describe("Deliver to {slug}+{tag}@mailhooks.cc")
+    },
+    withErrorHandling(async ({ slug, tag }) => {
+      const result = await client.emails.sendTest(slug, { tag });
+      return jsonContent({ ...result, address: client.emails.address(slug, tag) });
+    })
+  );
+  server.tool(
+    "configure_forwarding",
+    "Set the URL captured emails are forwarded to (as signed JSON) and turn forwarding on or off. Owner only. Saving the first URL creates the signing secret.",
+    {
+      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)"),
+      enabled: import_zod2.z.boolean().optional().describe("Turn forwarding on (needs a URL) or off (fails deliveries still waiting)")
+    },
+    withErrorHandling(async ({ slug, url, enabled }) => {
+      const endpoint = await client.forwarding.configure(slug, { url, enabled });
+      return jsonContent({
+        slug: endpoint.slug,
+        forwardEnabled: endpoint.forwardEnabled ?? false,
+        forwardUrl: endpoint.forwardUrl ?? null,
+        hasForwardSecret: endpoint.hasForwardSecret ?? false
+      });
+    })
+  );
+  server.tool(
+    "get_forwarding_secret",
+    "Read (or with rotate: true, replace) the whsec_ secret forwarded emails 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"),
+      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);
+      return jsonContent({ secret, rotated: rotate });
+    })
+  );
+  server.tool(
+    "test_forwarding",
+    "Post the endpoint's newest email (or a sample) to its forwarding URL once and report what the server answered. Works with forwarding on or off; nothing is retried or logged.",
+    { slug: import_zod2.z.string().describe("The endpoint slug") },
+    withErrorHandling(async ({ slug }) => {
+      return jsonContent(await client.forwarding.test(slug));
+    })
+  );
+  server.tool(
+    "list_deliveries",
+    "List forwarding deliveries: an endpoint's latest (endpointSlug), or every try of one email (requestId).",
+    {
+      endpointSlug: import_zod2.z.string().optional().describe("List the endpoint's latest deliveries"),
+      requestId: import_zod2.z.string().optional().describe("List every delivery and try of this email"),
+      limit: import_zod2.z.number().int().min(1).max(20).default(5).describe("With endpointSlug: max deliveries")
+    },
+    withErrorHandling(async ({ endpointSlug, requestId, limit }) => {
+      if (requestId === void 0 === (endpointSlug === void 0)) {
+        throw new Error("Pass exactly one of endpointSlug or requestId");
+      }
+      return jsonContent(
+        requestId ? await client.forwarding.emailDeliveries(requestId) : await client.forwarding.deliveries(endpointSlug, { limit })
+      );
+    })
+  );
+  server.tool(
+    "redeliver_email",
+    "Forward a captured email again with the endpoint's current URL and secret. Owner only; fails while forwarding is off.",
+    { requestId: import_zod2.z.string().describe("The email's request ID") },
+    withErrorHandling(async ({ requestId }) => {
+      return jsonContent(await client.forwarding.redeliver(requestId));
+    })
+  );
   server.tool(
     "describe",
     "Describe all available SDK operations, parameters, and types.",
@@ -1198,7 +1611,7 @@ function registerAgentRegistrationTools(server) {
       return jsonContent({
         ...import_sdk.WebhooksCC.describeRegistration(baseUrl),
         next_steps: [
-          "Easiest: call register_agent (anonymous) to get a key immediately, then have a human run claim_agent with the returned userCode while logged in to webhooks.cc.",
+          "Easiest: call register_agent (anonymous) to get a key immediately, then ask a human to open the returned claimUrl while signed in to webhooks.cc and enter the userCode. Poll check_claim until it says claimed.",
           "Or set WHK_API_KEY to an existing whcc_ key and use the authenticated tools."
         ]
       });
@@ -1206,7 +1619,7 @@ function registerAgentRegistrationTools(server) {
   );
   server.tool(
     "register_agent",
-    "Self-register for a webhooks.cc API credential via the anonymous auth.md flow. Returns a whcc_ API key that works immediately in a bounded sandbox, plus a short userCode and claimUrl a human uses to bind the key to their account. No authentication required. After registering, set WHK_API_KEY to the returned credential.",
+    "Self-register for a webhooks.cc API credential via the anonymous auth.md flow. Returns a whcc_ API key, plus a short userCode and claimUrl a human uses to bind the key to their account. Until a human claims it, the key only works with the sandbox API (/api/agent/sandbox/endpoints), not with these tools, and it is deleted about 15 minutes after registration. No authentication required.",
     {
       clientName: import_zod2.z.string().optional().describe("A human-readable name for this agent, recorded on the issued key")
     },
@@ -1222,7 +1635,7 @@ function registerAgentRegistrationTools(server) {
           expiresAt: reg.claimTokenExpires,
           instructions: `Ask a human to open ${reg.claimUrl} while logged in to webhooks.cc and either enter the code ${reg.userCode} or open ${reg.claimUrl}?token=${reg.claimToken}. Then call check_claim with the claimToken.`
         },
-        usage: "Set WHK_API_KEY to `credential` to use the authenticated tools. Before it is claimed the key can create ephemeral endpoints and read its own captured requests in the sandbox."
+        usage: "Until a human claims it, the key only works with the sandbox API at /api/agent/sandbox/endpoints (create temporary endpoints, read their requests), and it is deleted about 15 minutes after registration. Once check_claim says claimed, set WHK_API_KEY to `credential` and restart the MCP server to use the authenticated tools."
       });
     })
   );
@@ -1288,7 +1701,7 @@ function registerAgentRegistrationTools(server) {
 }
 
 // src/index.ts
-var VERSION = true ? "1.9.0" : "0.0.0-dev";
+var VERSION = true ? "1.10.1" : "0.0.0-dev";
 function createServer(options = {}) {
   const apiKey = options.apiKey ?? process.env.WHK_API_KEY;
   const server = new import_mcp2.McpServer({