@webhooks-cc/mcp 1.10.1 → 1.11.0

package/dist/index.js

@@ -24,11 +24,12 @@ __export(index_exports, {
   registerAgentRegistrationTools: () => registerAgentRegistrationTools,
   registerPrompts: () => registerPrompts,
   registerResources: () => registerResources,
+  registerSandboxTools: () => registerSandboxTools,
   registerTools: () => registerTools
 });
 module.exports = __toCommonJS(index_exports);
 var import_mcp2 = require("@modelcontextprotocol/sdk/server/mcp.js");
-var import_sdk2 = require("@webhooks-cc/sdk");
+var import_sdk3 = require("@webhooks-cc/sdk");
 
 // src/prompts.ts
 var import_zod = require("zod");
@@ -405,6 +406,10 @@ function registerResources(server, client) {
   );
 }
 
+// src/sandbox-tools.ts
+var import_zod3 = require("zod");
+var import_sdk2 = require("@webhooks-cc/sdk");
+
 // src/tools.ts
 var import_zod2 = require("zod");
 var import_sdk = require("@webhooks-cc/sdk");
@@ -464,6 +469,44 @@ var mockResponseSchema = import_zod2.z.object({
     `Response delay in milliseconds (${import_sdk.MOCK_RESPONSE_DELAY_MIN}-${import_sdk.MOCK_RESPONSE_DELAY_MAX}, default: none)`
   )
 });
+var createEndpointShape = {
+  name: import_zod2.z.string().optional().describe("Display name for the endpoint"),
+  ephemeral: import_zod2.z.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: import_zod2.z.string().url().optional().describe(
+    "URL to POST a JSON summary to after each captured request (e.g. Slack/Discord webhook)"
+  ),
+  signingProvider: import_zod2.z.string().optional().describe(
+    "Signing provider for automatic signature verification (e.g. stripe, github, shopify)"
+  ),
+  signingSecret: import_zod2.z.string().optional().describe(
+    "Signing secret (encrypted server-side, never returned). Required when signingProvider is set."
+  ),
+  signingHeader: import_zod2.z.string().optional().describe("Custom signature header name. Only used with generic-hmac provider.")
+};
+var listEndpointsShape = {
+  team: import_zod2.z.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: import_zod2.z.string().describe("The endpoint slug") };
+var deleteEndpointShape = { slug: import_zod2.z.string().describe("The endpoint slug to delete") };
+var listRequestsShape = {
+  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"),
+  kind: kindSchema
+};
+var getRequestShape = { requestId: import_zod2.z.string().describe("The request ID") };
+var waitForRequestShape = {
+  endpointSlug: import_zod2.z.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 }] };
 }
@@ -767,25 +810,7 @@ function registerTools(server, client) {
   server.tool(
     "create_endpoint",
     "Create a webhook endpoint. Returns the endpoint slug, URL, and metadata.",
-    {
-      name: import_zod2.z.string().optional().describe("Display name for the endpoint"),
-      ephemeral: import_zod2.z.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: import_zod2.z.string().url().optional().describe(
-        "URL to POST a JSON summary to after each captured request (e.g. Slack/Discord webhook)"
-      ),
-      signingProvider: import_zod2.z.string().optional().describe(
-        "Signing provider for automatic signature verification (e.g. stripe, github, shopify)"
-      ),
-      signingSecret: import_zod2.z.string().optional().describe(
-        "Signing secret (encrypted server-side, never returned). Required when signingProvider is set."
-      ),
-      signingHeader: import_zod2.z.string().optional().describe("Custom signature header name. Only used with generic-hmac provider.")
-    },
+    createEndpointShape,
     withErrorHandling(
       async ({
         name,
@@ -838,11 +863,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: import_zod2.z.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);
@@ -898,7 +919,7 @@ function registerTools(server, client) {
   server.tool(
     "get_endpoint",
     "Get details for a specific webhook endpoint by slug.",
-    { slug: import_zod2.z.string().describe("The endpoint slug") },
+    getEndpointShape,
     withErrorHandling(async ({ slug }) => {
       const endpoint = await client.endpoints.get(slug);
       return jsonContent(endpoint);
@@ -951,7 +972,7 @@ function registerTools(server, client) {
   server.tool(
     "delete_endpoint",
     "Delete a webhook endpoint and all its captured requests.",
-    { slug: import_zod2.z.string().describe("The endpoint slug to delete") },
+    deleteEndpointShape,
     withErrorHandling(async ({ slug }) => {
       await client.endpoints.delete(slug);
       return textContent(`Endpoint "${slug}" deleted.`);
@@ -1055,12 +1076,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: 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"),
-      kind: kindSchema
-    },
+    listRequestsShape,
     withErrorHandling(async ({ endpointSlug, limit, since, kind }) => {
       const requests = await client.requests.list(endpointSlug, { limit, since, kind });
       return jsonContent(requests.map(compactRequest));
@@ -1114,7 +1130,7 @@ function registerTools(server, client) {
   server.tool(
     "get_request",
     "Get full details for a specific captured request by ID.",
-    { requestId: import_zod2.z.string().describe("The request ID") },
+    getRequestShape,
     withErrorHandling(async ({ requestId }) => {
       const request = await client.requests.get(requestId);
       return jsonContent(compactRequest(request));
@@ -1123,11 +1139,7 @@ function registerTools(server, client) {
   server.tool(
     "wait_for_request",
     "Wait for a request to arrive at an endpoint.",
-    {
-      endpointSlug: import_zod2.z.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));
@@ -1618,127 +1630,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({
-        ...import_sdk.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 = import_sdk2.WebhooksCC.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 = 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));
+}
+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: import_zod2.z.string().optional().describe("A human-readable name for this agent, recorded on the issued key")
-    },
-    withErrorHandling(async ({ clientName }) => {
-      const reg = await import_sdk.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: import_zod2.z.string().describe("The claimToken returned by register_agent")
-    },
-    withErrorHandling(async ({ claimToken }) => {
-      const poll = await import_sdk.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: import_zod2.z.string().email({ message: "Invalid email address" }).describe("The email address to verify and bind the credential to"),
-      clientName: import_zod2.z.string().optional().describe("A human-readable name for this agent, recorded on the issued key")
-    },
-    withErrorHandling(async ({ email, clientName }) => {
-      const challenge = await import_sdk.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: import_zod2.z.string().describe("The claimToken returned by register_agent_with_email"),
-      otp: import_zod2.z.string().describe("The one-time code the human received by email")
-    },
-    withErrorHandling(async ({ claimToken, otp }) => {
-      const issued = await import_sdk.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: import_zod2.z.string().describe("The ID-JAG assertion JWT (typ oauth-id-jag+jwt) from a trusted provider")
-    },
-    withErrorHandling(async ({ assertion }) => {
-      const issued = await import_sdk.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: import_zod3.z.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 import_sdk2.WebhooksCC.agent.startClaim({
+            baseUrl,
+            claimToken: session.claim.claimToken
+          });
+          claim = { ...session.claim, attempt };
+        } else {
+          const registration = await import_sdk2.WebhooksCC.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: 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) {
+          throw new Error("Nothing to wait for: call connect_account first.");
+        }
+        let claimed;
+        try {
+          claimed = await import_sdk2.WebhooksCC.agent.waitForClaim({
+            baseUrl,
+            claimToken: claim.claimToken,
+            interval: claim.attempt.interval,
+            timeout: (timeoutSeconds ?? DEFAULT_WAIT_SECONDS) * 1e3
+          });
+        } 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.`
+            });
+          }
+          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 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);
+        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.11.0" : "0.0.0-dev";
 function createServer(options = {}) {
   const apiKey = options.apiKey ?? process.env.WHK_API_KEY;
-  const server = new import_mcp2.McpServer({
-    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 import_mcp2.McpServer(
+    { 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 import_sdk2.WebhooksCC({
-    apiKey,
-    webhookUrl: options.webhookUrl ?? process.env.WHK_WEBHOOK_URL,
-    baseUrl: options.baseUrl ?? process.env.WHK_BASE_URL
-  });
+  const client = new import_sdk3.WebhooksCC({ apiKey, webhookUrl, baseUrl });
   registerTools(server, client);
   registerPrompts(server);
   registerResources(server, client);
@@ -1750,5 +2027,6 @@ function createServer(options = {}) {
   registerAgentRegistrationTools,
   registerPrompts,
   registerResources,
+  registerSandboxTools,
   registerTools
 });