@webhooks-cc/mcp 1.10.1 → 1.12.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
 // src/index.ts
 import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { WebhooksCC as WebhooksCC2 } from "@webhooks-cc/sdk";
+import { WebhooksCC as WebhooksCC3 } from "@webhooks-cc/sdk";
 
 // src/prompts.ts
 import { z } from "zod";
@@ -377,6 +377,13 @@ function registerResources(server, client) {
   );
 }
 
+// src/sandbox-tools.ts
+import { z as z3 } from "zod";
+import {
+  AgentAuthError,
+  WebhooksCC as WebhooksCC2
+} from "@webhooks-cc/sdk";
+
 // src/tools.ts
 import { z as z2 } from "zod";
 import {
@@ -399,7 +406,6 @@ import {
   UnauthorizedError,
   VERIFY_PROVIDERS,
   verifySignature,
-  WebhooksCC,
   WebhooksCCError,
   extractCode,
   extractLink
@@ -460,6 +466,44 @@ var mockResponseSchema = z2.object({
     `Response delay in milliseconds (${MOCK_RESPONSE_DELAY_MIN}-${MOCK_RESPONSE_DELAY_MAX}, default: none)`
   )
 });
+var createEndpointShape = {
+  name: z2.string().optional().describe("Display name for the endpoint"),
+  ephemeral: z2.boolean().optional().describe("Create a temporary endpoint that auto-expires"),
+  expiresIn: durationOrTimestampSchema.optional().describe('Auto-expire after this duration, for example "12h"'),
+  mockResponse: mockResponseSchema.optional().describe("Optional mock response to return when the endpoint receives a request"),
+  responseRules: responseRulesSchema.optional().describe(
+    "Conditional response rules. Each rule has conditions and a response. First matching rule wins."
+  ),
+  notificationUrl: z2.string().url().optional().describe(
+    "URL to POST a JSON summary to after each captured request (e.g. Slack/Discord webhook)"
+  ),
+  signingProvider: z2.string().optional().describe(
+    "Signing provider for automatic signature verification (e.g. stripe, github, shopify)"
+  ),
+  signingSecret: z2.string().optional().describe(
+    "Signing secret (encrypted server-side, never returned). Required when signingProvider is set."
+  ),
+  signingHeader: z2.string().optional().describe("Custom signature header name. Only used with generic-hmac provider.")
+};
+var listEndpointsShape = {
+  team: z2.string().min(1).optional().describe(
+    "Team id or name (case-insensitive). Keeps endpoints shared with you from that team and endpoints you own that are shared with it."
+  )
+};
+var getEndpointShape = { slug: z2.string().describe("The endpoint slug") };
+var deleteEndpointShape = { slug: z2.string().describe("The endpoint slug to delete") };
+var listRequestsShape = {
+  endpointSlug: z2.string().describe("The endpoint slug"),
+  limit: z2.number().int().min(1).max(100).default(25).describe("Max requests to return"),
+  since: z2.number().optional().describe("Only return requests after this timestamp in ms"),
+  kind: kindSchema
+};
+var getRequestShape = { requestId: z2.string().describe("The request ID") };
+var waitForRequestShape = {
+  endpointSlug: z2.string().describe("The endpoint slug to monitor"),
+  timeout: durationOrTimestampSchema.default("30s").describe('How long to wait, for example "30s"'),
+  pollInterval: durationOrTimestampSchema.optional().describe('Interval between polls, for example "500ms" or "1s"')
+};
 function textContent(text) {
   return { content: [{ type: "text", text }] };
 }
@@ -763,25 +807,7 @@ function registerTools(server, client) {
   server.tool(
     "create_endpoint",
     "Create a webhook endpoint. Returns the endpoint slug, URL, and metadata.",
-    {
-      name: z2.string().optional().describe("Display name for the endpoint"),
-      ephemeral: z2.boolean().optional().describe("Create a temporary endpoint that auto-expires"),
-      expiresIn: durationOrTimestampSchema.optional().describe('Auto-expire after this duration, for example "12h"'),
-      mockResponse: mockResponseSchema.optional().describe("Optional mock response to return when the endpoint receives a request"),
-      responseRules: responseRulesSchema.optional().describe(
-        "Conditional response rules. Each rule has conditions and a response. First matching rule wins."
-      ),
-      notificationUrl: z2.string().url().optional().describe(
-        "URL to POST a JSON summary to after each captured request (e.g. Slack/Discord webhook)"
-      ),
-      signingProvider: z2.string().optional().describe(
-        "Signing provider for automatic signature verification (e.g. stripe, github, shopify)"
-      ),
-      signingSecret: z2.string().optional().describe(
-        "Signing secret (encrypted server-side, never returned). Required when signingProvider is set."
-      ),
-      signingHeader: z2.string().optional().describe("Custom signature header name. Only used with generic-hmac provider.")
-    },
+    createEndpointShape,
     withErrorHandling(
       async ({
         name,
@@ -834,11 +860,7 @@ function registerTools(server, client) {
   server.tool(
     "list_endpoints",
     "List webhook endpoints: those you own (with sharedWith) and those shared with you through teams (with fromTeam). Optionally keep only one team's endpoints.",
-    {
-      team: z2.string().min(1).optional().describe(
-        "Team id or name (case-insensitive). Keeps endpoints shared with you from that team and endpoints you own that are shared with it."
-      )
-    },
+    listEndpointsShape,
     withErrorHandling(async ({ team }) => {
       const endpoints = await client.endpoints.list({ team });
       return jsonContent(endpoints);
@@ -894,7 +916,7 @@ function registerTools(server, client) {
   server.tool(
     "get_endpoint",
     "Get details for a specific webhook endpoint by slug.",
-    { slug: z2.string().describe("The endpoint slug") },
+    getEndpointShape,
     withErrorHandling(async ({ slug }) => {
       const endpoint = await client.endpoints.get(slug);
       return jsonContent(endpoint);
@@ -947,7 +969,7 @@ function registerTools(server, client) {
   server.tool(
     "delete_endpoint",
     "Delete a webhook endpoint and all its captured requests.",
-    { slug: z2.string().describe("The endpoint slug to delete") },
+    deleteEndpointShape,
     withErrorHandling(async ({ slug }) => {
       await client.endpoints.delete(slug);
       return textContent(`Endpoint "${slug}" deleted.`);
@@ -1051,12 +1073,7 @@ function registerTools(server, client) {
   server.tool(
     "list_requests",
     "List recent captured requests for an endpoint, HTTP requests and emails together (filter with kind). For emails, list_emails is shorter.",
-    {
-      endpointSlug: z2.string().describe("The endpoint slug"),
-      limit: z2.number().int().min(1).max(100).default(25).describe("Max requests to return"),
-      since: z2.number().optional().describe("Only return requests after this timestamp in ms"),
-      kind: kindSchema
-    },
+    listRequestsShape,
     withErrorHandling(async ({ endpointSlug, limit, since, kind }) => {
       const requests = await client.requests.list(endpointSlug, { limit, since, kind });
       return jsonContent(requests.map(compactRequest));
@@ -1110,7 +1127,7 @@ function registerTools(server, client) {
   server.tool(
     "get_request",
     "Get full details for a specific captured request by ID.",
-    { requestId: z2.string().describe("The request ID") },
+    getRequestShape,
     withErrorHandling(async ({ requestId }) => {
       const request = await client.requests.get(requestId);
       return jsonContent(compactRequest(request));
@@ -1119,11 +1136,7 @@ function registerTools(server, client) {
   server.tool(
     "wait_for_request",
     "Wait for a request to arrive at an endpoint.",
-    {
-      endpointSlug: z2.string().describe("The endpoint slug to monitor"),
-      timeout: durationOrTimestampSchema.default("30s").describe('How long to wait, for example "30s"'),
-      pollInterval: durationOrTimestampSchema.optional().describe('Interval between polls, for example "500ms" or "1s"')
-    },
+    waitForRequestShape,
     withErrorHandling(async ({ endpointSlug, timeout, pollInterval }) => {
       const request = await client.requests.waitFor(endpointSlug, { timeout, pollInterval });
       return jsonContent(compactRequest(request));
@@ -1544,25 +1557,52 @@ function registerTools(server, client) {
   );
   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.",
+    "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.",
     {
       slug: z2.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: z2.boolean().optional().describe("Turn forwarding on (needs a URL) or off (fails deliveries still waiting)")
+      enabled: z2.boolean().optional().describe("Turn forwarding on (needs a URL) or off (fails deliveries still waiting)"),
+      http: z2.boolean().optional().describe("Forward HTTP requests"),
+      email: z2.boolean().optional().describe("Forward emails"),
+      format: z2.enum(["auto", "as_received", "json", "chat"]).optional().describe(
+        "auto (pick from the URL), as_received (relay HTTP requests unchanged; emails as signed JSON), json (signed JSON envelope for both kinds) or chat (Slack or Discord message)"
+      ),
+      headers: z2.array(
+        z2.object({
+          name: z2.string().describe("Header name, e.g. Authorization"),
+          value: z2.string().nullable().describe("Header value, or null to keep the value stored under this name")
+        })
+      ).max(10).optional().describe(
+        "Your own headers for every delivery (not chat). Replaces the whole list; [] removes them"
+      ),
+      appendPath: z2.boolean().optional().describe("Add the path after the slug to the URL for relayed requests (default true)"),
+      retrySeconds: z2.union([z2.literal(0), z2.literal(3600), z2.literal(86400)]).optional().describe("Retry failed deliveries for 86400 (default), 3600 or 0 seconds"),
+      keepOrder: z2.boolean().optional().describe("One delivery at a time, in capture order (default false)"),
+      sentField: z2.string().max(128).nullable().optional().describe(
+        "JSON body field with the sender's own timestamp, e.g. publishedAt or data.publishedAt; null clears it"
+      )
     },
-    withErrorHandling(async ({ slug, url, enabled }) => {
-      const endpoint = await client.forwarding.configure(slug, { url, enabled });
+    withErrorHandling(async ({ slug, ...options }) => {
+      const endpoint = await client.forwarding.configure(slug, options);
       return jsonContent({
         slug: endpoint.slug,
         forwardEnabled: endpoint.forwardEnabled ?? false,
         forwardUrl: endpoint.forwardUrl ?? null,
-        hasForwardSecret: endpoint.hasForwardSecret ?? false
+        hasForwardSecret: endpoint.hasForwardSecret ?? false,
+        forwardHttp: endpoint.forwardHttp ?? false,
+        forwardEmail: endpoint.forwardEmail ?? false,
+        forwardFormat: endpoint.forwardFormat ?? "auto",
+        forwardHeaders: endpoint.forwardHeaders ?? [],
+        forwardAppendPath: endpoint.forwardAppendPath ?? true,
+        forwardRetrySeconds: endpoint.forwardRetrySeconds ?? 86400,
+        forwardKeepOrder: endpoint.forwardKeepOrder ?? false,
+        forwardSentField: endpoint.forwardSentField ?? null
       });
     })
   );
   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.",
+    "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: z2.string().describe("The endpoint slug"),
       rotate: z2.boolean().default(false).describe("Replace the secret; every delivery from now on uses the new one")
@@ -1574,35 +1614,57 @@ function registerTools(server, client) {
   );
   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: z2.string().describe("The endpoint slug") },
-    withErrorHandling(async ({ slug }) => {
-      return jsonContent(await client.forwarding.test(slug));
+    "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.",
+    {
+      slug: z2.string().describe("The endpoint slug"),
+      kind: z2.enum(["http", "email"]).optional().describe(
+        "Which kind to send (default: http when HTTP requests are forwarded, else email)"
+      )
+    },
+    withErrorHandling(async ({ slug, kind }) => {
+      return jsonContent(await client.forwarding.test(slug, kind ? { kind } : {}));
     })
   );
   server.tool(
     "list_deliveries",
-    "List forwarding deliveries: an endpoint's latest (endpointSlug), or every try of one email (requestId).",
+    "List forwarding deliveries: an endpoint's delivery log with its counts (endpointSlug), or every delivery and try of one captured request or email (requestId). Rows carry senderAt when the request had the sender's own timestamp, so receivedAt - senderAt is the time to reach webhooks.cc.",
     {
-      endpointSlug: z2.string().optional().describe("List the endpoint's latest deliveries"),
-      requestId: z2.string().optional().describe("List every delivery and try of this email"),
-      limit: z2.number().int().min(1).max(20).default(5).describe("With endpointSlug: max deliveries")
+      endpointSlug: z2.string().optional().describe("List the endpoint's delivery log"),
+      requestId: z2.string().optional().describe("List every delivery and try of this request"),
+      limit: z2.number().int().min(1).max(100).default(20).describe("With endpointSlug: max rows"),
+      status: z2.enum(["all", "pending", "failed"]).default("all").describe("With endpointSlug: all, pending (queued or retrying) or failed"),
+      before: z2.string().optional().describe("With endpointSlug: a row's cursor, to list older rows")
     },
-    withErrorHandling(async ({ endpointSlug, requestId, limit }) => {
+    withErrorHandling(async ({ endpointSlug, requestId, limit, status, before }) => {
       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 })
-      );
+      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 })
+      ]);
+      return jsonContent({
+        summary,
+        deliveries,
+        nextCursor: deliveries.length === limit ? deliveries[deliveries.length - 1]?.cursor ?? null : null
+      });
     })
   );
   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: z2.string().describe("The email's request ID") },
-    withErrorHandling(async ({ requestId }) => {
-      return jsonContent(await client.forwarding.redeliver(requestId));
+    "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.",
+    {
+      requestId: z2.string().optional().describe("The request or email to send again"),
+      endpointSlug: z2.string().optional().describe("Send every failed delivery of this endpoint again")
+    },
+    withErrorHandling(async ({ requestId, endpointSlug }) => {
+      if (requestId === void 0 === (endpointSlug === void 0)) {
+        throw new Error("Pass exactly one of requestId or endpointSlug");
+      }
+      return jsonContent(
+        requestId ? await client.forwarding.redeliver(requestId) : await client.forwarding.redeliverFailed(endpointSlug)
+      );
     })
   );
   server.tool(
@@ -1614,127 +1676,392 @@ function registerTools(server, client) {
       return jsonContent(description);
     })
   );
-  registerAgentRegistrationTools(server);
 }
-function resolveBaseUrl() {
-  return process.env.WHK_BASE_URL ?? "https://webhooks.cc";
-}
-function registerAgentRegistrationTools(server) {
-  const baseUrl = resolveBaseUrl();
-  server.tool(
-    "how_to_register",
-    "Explain how an agent self-registers for a webhooks.cc API credential (auth.md). Call this FIRST when you have no API key. Returns the three registration flows and the auth.md documentation URL. No authentication required.",
-    {},
-    withErrorHandling(async () => {
-      return jsonContent({
-        ...WebhooksCC.describeRegistration(baseUrl),
-        next_steps: [
-          "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."
-        ]
+
+// src/sandbox-tools.ts
+var SANDBOX = {
+  maxEndpoints: 3,
+  requestsPerEndpoint: 25,
+  requests: 100,
+  lifetimeHours: 24
+};
+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",
+  "responseRules",
+  "notificationUrl",
+  "signingProvider",
+  "signingSecret",
+  "signingHeader"
+];
+var AgentSession = class {
+  constructor(baseUrl, webhookUrl, clientName) {
+    this.baseUrl = baseUrl;
+    this.webhookUrl = webhookUrl;
+    this.clientName = clientName;
+    this.sandbox = null;
+    this.claim = null;
+    this.connected = false;
+  }
+  /**
+   * 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.
+   */
+  async sandboxClient() {
+    while (this.sandbox) {
+      const pending = this.sandbox;
+      const sandbox = await pending;
+      if (!this.expired(pending, sandbox)) return sandbox;
+    }
+    const created = WebhooksCC2.sandbox({
+      baseUrl: this.baseUrl,
+      webhookUrl: this.webhookUrl,
+      clientName: this.clientName
+    });
+    this.sandbox = created;
+    created.catch(() => {
+      if (this.sandbox === created) this.sandbox = null;
+    });
+    return created;
+  }
+  /** The live sandbox, if one was registered; never registers one. */
+  async existingSandbox() {
+    const pending = this.sandbox;
+    if (!pending) return null;
+    let sandbox;
+    try {
+      sandbox = await pending;
+    } catch {
+      return null;
+    }
+    return this.expired(pending, sandbox) ? null : 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;
+    }
+    return true;
+  }
+  async requireSandbox() {
+    const sandbox = await this.existingSandbox();
+    if (!sandbox) {
+      throw new Error("No sandbox yet: create_endpoint starts one.");
+    }
+    return sandbox;
+  }
+  forgetSandbox() {
+    this.sandbox = 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 = WebhooksCC2.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));
+}
+function onlyKind(requests, kind) {
+  if (!kind) return requests;
+  return requests.filter((request) => (request.kind ?? "http") === kind);
+}
+function registerSandboxTools(server, options = {}) {
+  const baseUrl = options.baseUrl ?? process.env.WHK_BASE_URL ?? "https://webhooks.cc";
+  const session = new AgentSession(
+    baseUrl,
+    options.webhookUrl ?? process.env.WHK_WEBHOOK_URL,
+    options.clientName ?? "webhooks-cc-mcp"
   );
-  server.tool(
-    "register_agent",
-    "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: z2.string().optional().describe("A human-readable name for this agent, recorded on the issued key")
-    },
-    withErrorHandling(async ({ clientName }) => {
-      const reg = await WebhooksCC.register.anonymous({ baseUrl, clientName });
-      return jsonContent({
-        credential: reg.credential,
-        scopes: reg.scopes,
-        claim: {
-          userCode: reg.userCode,
-          claimUrl: reg.claimUrl,
-          claimToken: reg.claimToken,
-          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: "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."
-      });
-    })
+  const registered = [];
+  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(
+    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.`,
+      createEndpointShape,
+      withErrorHandling(async (args) => {
+        const accountOnly = ACCOUNT_ONLY_OPTIONS.filter((key) => args[key] !== void 0);
+        if (accountOnly.length > 0) {
+          throw new Error(
+            `${accountOnly.join(", ")} need an account; sandbox endpoints only capture and answer 200. Call connect_account to connect one.`
+          );
+        }
+        const sandbox = await session.sandboxClient();
+        const endpoint = await sandbox.endpoints.create();
+        const ignored = args.name !== void 0 || args.expiresIn !== void 0;
+        return jsonContent(
+          ignored ? {
+            ...endpoint,
+            note: "Sandbox endpoints have no name and expire with the sandbox."
+          } : endpoint
+        );
+      })
+    )
   );
-  server.tool(
-    "check_claim",
-    "Check whether an anonymous registration's API key has been claimed by a human yet. Poll this after register_agent until status is 'claimed'. No authentication required.",
-    {
-      claimToken: z2.string().describe("The claimToken returned by register_agent")
-    },
-    withErrorHandling(async ({ claimToken }) => {
-      const poll = await WebhooksCC.register.pollClaim(claimToken, { baseUrl });
-      return jsonContent(poll);
-    })
+  registered.push(
+    server.tool(
+      "list_endpoints",
+      "List this agent's sandbox endpoints. Empty until create_endpoint starts the sandbox.",
+      listEndpointsShape,
+      withErrorHandling(async ({ team }) => {
+        if (team !== void 0) {
+          throw new Error("Teams need an account. Call connect_account to connect one.");
+        }
+        const sandbox = await session.existingSandbox();
+        return jsonContent(sandbox ? await sandbox.endpoints.list() : []);
+      })
+    )
   );
-  server.tool(
-    "register_agent_with_email",
-    "Self-register via the verified_email auth.md flow: webhooks.cc emails a one-time code to the address. The credential is WITHHELD until the code is confirmed with verify_agent_otp. Returns a claimToken to pass to verify_agent_otp. No authentication required.",
-    {
-      email: z2.string().email({ message: "Invalid email address" }).describe("The email address to verify and bind the credential to"),
-      clientName: z2.string().optional().describe("A human-readable name for this agent, recorded on the issued key")
-    },
-    withErrorHandling(async ({ email, clientName }) => {
-      const challenge = await WebhooksCC.register.withEmail(email, { baseUrl, clientName });
-      return jsonContent({
-        claimToken: challenge.claimToken,
-        expiresAt: challenge.claimTokenExpires,
-        postClaimScopes: challenge.postClaimScopes,
-        next_step: `A one-time code was emailed to ${email}. Ask the human for it, then call verify_agent_otp with this claimToken and the code.`
-      });
-    })
+  registered.push(
+    server.tool(
+      "get_endpoint",
+      "Get one of this agent's sandbox endpoints by slug, with its sandbox limits and usage.",
+      getEndpointShape,
+      withErrorHandling(async ({ slug }) => {
+        return jsonContent(await (await session.requireSandbox()).endpoints.get(slug));
+      })
+    )
   );
-  server.tool(
-    "verify_agent_otp",
-    "Complete the verified_email flow: submit the emailed OTP with the claimToken from register_agent_with_email. On success returns the whcc_ API key (bound to the verified email). Set WHK_API_KEY to it. No authentication required.",
-    {
-      claimToken: z2.string().describe("The claimToken returned by register_agent_with_email"),
-      otp: z2.string().describe("The one-time code the human received by email")
-    },
-    withErrorHandling(async ({ claimToken, otp }) => {
-      const issued = await WebhooksCC.register.confirmEmailOtp({ claimToken, otp }, { baseUrl });
-      return jsonContent({
-        credential: issued.credential,
-        scopes: issued.scopes,
-        usage: "Set WHK_API_KEY to `credential` to use the authenticated tools."
-      });
-    })
+  registered.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.",
+      deleteEndpointShape,
+      withErrorHandling(async ({ slug }) => {
+        await (await session.requireSandbox()).endpoints.delete(slug);
+        return jsonContent({ deleted: slug });
+      })
+    )
   );
-  server.tool(
-    "register_agent_with_idjag",
-    "Self-register via the identity_assertion (ID-JAG) auth.md flow: present a verified identity-assertion JWT (urn:ietf:params:oauth:token-type:id-jag) from a trusted provider. The credential is returned synchronously \u2014 no human claim step. No webhooks.cc authentication required, but only works if webhooks.cc trusts your provider.",
-    {
-      assertion: z2.string().describe("The ID-JAG assertion JWT (typ oauth-id-jag+jwt) from a trusted provider")
-    },
-    withErrorHandling(async ({ assertion }) => {
-      const issued = await WebhooksCC.register.withIdJag(assertion, { baseUrl });
-      return jsonContent({
-        credential: issued.credential,
-        scopes: issued.scopes,
-        usage: "Set WHK_API_KEY to `credential` to use the authenticated tools."
-      });
-    })
+  registered.push(
+    server.tool(
+      "list_requests",
+      "List recent requests captured by a sandbox endpoint, newest first.",
+      listRequestsShape,
+      withErrorHandling(async ({ endpointSlug, limit, since, kind }) => {
+        const sandbox = await session.requireSandbox();
+        const requests = await sandbox.requests.list(endpointSlug, { limit, since });
+        return jsonContent(onlyKind(requests, kind).map(compactRequest));
+      })
+    )
+  );
+  registered.push(
+    server.tool(
+      "get_request",
+      "Get full details for a request captured by a sandbox endpoint.",
+      getRequestShape,
+      withErrorHandling(async ({ requestId }) => {
+        const sandbox = await session.requireSandbox();
+        return jsonContent(compactRequest(await sandbox.requests.get(requestId)));
+      })
+    )
+  );
+  registered.push(
+    server.tool(
+      "wait_for_request",
+      "Wait for a request to arrive at a sandbox endpoint.",
+      waitForRequestShape,
+      withErrorHandling(async ({ endpointSlug, timeout, pollInterval }) => {
+        const sandbox = await session.requireSandbox();
+        const request = await sandbox.requests.waitFor(endpointSlug, { timeout, pollInterval });
+        return jsonContent(compactRequest(request));
+      })
+    )
+  );
+  registered.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: z3.string().email({ message: "Invalid email address" }).describe("The human's email address; 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 sandbox = await session.existingSandbox();
+        let claim;
+        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 WebhooksCC2.agent.startClaim({
+            baseUrl,
+            claimToken: session.claim.claimToken
+          });
+          claim = { ...session.claim, attempt };
+        } else {
+          const registration = await WebhooksCC2.agent.registerServiceAuth({
+            baseUrl,
+            email: normalized,
+            clientName: session.clientName
+          });
+          claim = {
+            kind: "service_auth",
+            claimToken: registration.claimToken,
+            email: normalized,
+            attempt: registration.claim,
+            claimExpires: registration.claimTokenExpires
+          };
+        }
+        session.claim = claim;
+        const { verificationUri, userCode, expiresAt } = claim.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." } : {}
+        });
+      })
+    )
+  );
+  registered.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.`,
+      {
+        timeoutSeconds: z3.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) {
+          throw new Error("Nothing to wait for: call connect_account first.");
+        }
+        let claimed;
+        try {
+          claimed = await WebhooksCC2.agent.waitForClaim({
+            baseUrl,
+            claimToken: claim.claimToken,
+            interval: claim.attempt.interval,
+            timeout: (timeoutSeconds ?? DEFAULT_WAIT_SECONDS) * 1e3
+          });
+        } catch (error) {
+          if (!(error instanceof 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.`
+            });
+          }
+          if (error.code === "expired_token") {
+            return jsonContent({
+              connected: false,
+              status: "expired",
+              message: "The code expired. Call connect_account for a new one."
+            });
+          }
+          if (error.code === "access_denied") {
+            return jsonContent({
+              connected: false,
+              status: "declined",
+              message: "The human declined. Call connect_account again only if they ask you to."
+            });
+          }
+          throw error;
+        }
+        const client = new WebhooksCC2({
+          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);
+        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.`
+        });
+      })
+    )
+  );
+  registered.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)",
+          sandbox: {
+            maxEndpoints: SANDBOX.maxEndpoints,
+            requestsPerEndpoint: SANDBOX.requestsPerEndpoint,
+            requestsInAll: SANDBOX.requests,
+            lifetimeHours: SANDBOX.lifetimeHours,
+            startsWith: "create_endpoint (registers the sandbox; a few seconds of proof of work)",
+            captures: "Endpoints answer every request with 200; only this agent can read what they capture.",
+            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 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."
+          ],
+          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`
+        });
+      })
+    )
   );
 }
+function registerAgentRegistrationTools(server) {
+  registerSandboxTools(server);
+}
 
 // src/index.ts
-var VERSION = true ? "1.10.1" : "0.0.0-dev";
+var VERSION = true ? "1.12.0" : "0.0.0-dev";
 function createServer(options = {}) {
   const apiKey = options.apiKey ?? process.env.WHK_API_KEY;
-  const server = new McpServer2({
-    name: "webhooks-cc",
-    version: VERSION
-  });
+  const webhookUrl = options.webhookUrl ?? process.env.WHK_WEBHOOK_URL;
+  const baseUrl = options.baseUrl ?? process.env.WHK_BASE_URL;
+  const server = new McpServer2(
+    { name: "webhooks-cc", version: VERSION },
+    // Connecting an account swaps every tool at once: one list_changed, not dozens.
+    { debouncedNotificationMethods: ["notifications/tools/list_changed"] }
+  );
   if (!apiKey) {
-    registerAgentRegistrationTools(server);
+    registerSandboxTools(server, { baseUrl, webhookUrl });
+    registerPrompts(server);
     return server;
   }
-  const client = new WebhooksCC2({
-    apiKey,
-    webhookUrl: options.webhookUrl ?? process.env.WHK_WEBHOOK_URL,
-    baseUrl: options.baseUrl ?? process.env.WHK_BASE_URL
-  });
+  const client = new WebhooksCC3({ apiKey, webhookUrl, baseUrl });
   registerTools(server, client);
   registerPrompts(server);
   registerResources(server, client);
@@ -1745,5 +2072,6 @@ export {
   registerAgentRegistrationTools,
   registerPrompts,
   registerResources,
+  registerSandboxTools,
   registerTools
 };