@webhooks-cc/mcp 1.14.0 → 1.15.0

package/dist/bin/mcp.js

@@ -754,7 +754,9 @@ async function waitForMultipleRequests(client, endpointSlug, options) {
         };
       }
     }
-    await sleep(Math.max(10, pollIntervalMs));
+    await sleep(
+      Math.min(Math.max(10, pollIntervalMs), Math.max(0, timeoutMs - (Date.now() - startedAt)))
+    );
   }
   return {
     requests,
@@ -912,7 +914,67 @@ function emailDetail(client, email, view, includeHtml) {
   ]);
   return detail;
 }
-function registerTools(server, client) {
+var LOCAL_ONLY_TOOLS = /* @__PURE__ */ new Set(["send_to", "replay_request"]);
+var TARGET_URL_TOOLS = /* @__PURE__ */ new Set(["render_email", "test_webhook_flow"]);
+var REMOTE_MAX_WAIT_MS = 5e4;
+var REMOTE_MIN_POLL_MS = 1e3;
+function durationMs(value) {
+  if (typeof value === "number") return Number.isFinite(value) && value >= 0 ? value : null;
+  if (typeof value !== "string") return null;
+  try {
+    const ms = (0, import_sdk.parseDuration)(value);
+    return Number.isFinite(ms) && ms >= 0 ? ms : null;
+  } catch {
+    return null;
+  }
+}
+function toolTarget(target, remote, handles) {
+  return {
+    tool(name, description, shape, handler) {
+      if (remote && LOCAL_ONLY_TOOLS.has(name)) return { remove() {
+      } };
+      const wrapped = remote ? async (args2) => {
+        const input = args2;
+        if (TARGET_URL_TOOLS.has(name) && input.targetUrl !== void 0) {
+          return {
+            ...textContent(
+              "targetUrl needs the local MCP server (npx -y @webhooks-cc/mcp): the hosted server cannot reach your machine. Leave it out here."
+            ),
+            isError: true
+          };
+        }
+        const bounded = { ...input };
+        if ("pollInterval" in shape && input.pollInterval === void 0) {
+          bounded.pollInterval = REMOTE_MIN_POLL_MS;
+        }
+        for (const [key, bound] of [
+          ["timeout", (ms) => Math.min(ms, REMOTE_MAX_WAIT_MS)],
+          [
+            "pollInterval",
+            (ms) => Math.min(Math.max(ms, REMOTE_MIN_POLL_MS), REMOTE_MAX_WAIT_MS)
+          ]
+        ]) {
+          if (bounded[key] === void 0) continue;
+          const ms = durationMs(bounded[key]);
+          if (ms === null) {
+            return {
+              ...textContent(`${key} must be a duration such as "30s" or milliseconds.`),
+              isError: true
+            };
+          }
+          bounded[key] = bound(ms);
+        }
+        return handler(bounded);
+      } : handler;
+      const handle = target.tool(name, description, shape, wrapped);
+      handles.push(handle);
+      return handle;
+    }
+  };
+}
+function registerTools(target, client, options = {}) {
+  const handles = [];
+  const server = toolTarget(target, options.remote === true, handles);
   server.tool(
     "create_endpoint",
     "Create a webhook endpoint. Returns the endpoint slug, URL, and metadata.",
@@ -1594,7 +1656,7 @@ function registerTools(server, client) {
         verifySignature: shouldVerify,
         cleanup
       }) => {
-        const flow = client.flow().createEndpoint({ expiresIn: "1h" }).waitForCapture({ timeout: "30s" });
+        const flow = client.flow().createEndpoint({ expiresIn: "1h" }).waitForCapture({ timeout: "30s", pollInterval: "1s" });
         if (mockStatus !== void 0) {
           flow.setMock({
             status: mockStatus,
@@ -1719,10 +1781,14 @@ function registerTools(server, client) {
       includeHtml: import_zod2.z.boolean().default(false).describe("Include the HTML part (default: false)")
     },
     withErrorHandling(async ({ endpointSlug, tag, subject, from, timeout, since, includeHtml }) => {
-      const [email, view] = await Promise.all([
-        client.emails.waitFor(endpointSlug, { tag, subject, from, timeout, since }),
-        emailEndpointView(client, endpointSlug)
-      ]);
+      const view = await emailEndpointView(client, endpointSlug);
+      const email = await client.emails.waitFor(endpointSlug, {
+        tag,
+        subject,
+        from,
+        timeout,
+        since
+      });
       return jsonContent(emailDetail(client, email, view, includeHtml));
     })
   );
@@ -1835,8 +1901,8 @@ function registerTools(server, client) {
         "JSON body field with the sender's own timestamp, e.g. publishedAt or data.publishedAt; null clears it"
       )
     },
-    withErrorHandling(async ({ slug, ...options }) => {
-      const endpoint = await client.forwarding.configure(slug, options);
+    withErrorHandling(async ({ slug, ...options2 }) => {
+      const endpoint = await client.forwarding.configure(slug, options2);
       return jsonContent({
         slug: endpoint.slug,
         forwardEnabled: endpoint.forwardEnabled ?? false,
@@ -1933,9 +1999,9 @@ function registerTools(server, client) {
       if (requestId === void 0 === (endpointSlug === void 0)) {
         throw new Error("Pass exactly one of requestId or endpointSlug");
       }
-      const options = destinationId ? { destinationId } : {};
+      const options2 = destinationId ? { destinationId } : {};
       return jsonContent(
-        requestId ? await client.forwarding.redeliver(requestId, options) : await client.forwarding.redeliverFailed(endpointSlug, options)
+        requestId ? await client.forwarding.redeliver(requestId, options2) : await client.forwarding.redeliverFailed(endpointSlug, options2)
       );
     })
   );
@@ -1948,6 +2014,7 @@ function registerTools(server, client) {
       return jsonContent(description);
     })
   );
+  return handles;
 }
 
 // src/sandbox-tools.ts
@@ -1959,7 +2026,6 @@ var SANDBOX = {
 };
 var DEFAULT_WAIT_SECONDS = 45;
 var MAX_WAIT_SECONDS = 600;
-var TOKEN_REFRESH_MARGIN_MS = 6e4;
 var DOCS_URL = "https://webhooks.cc/docs/agents";
 var ACCOUNT_ONLY_OPTIONS = [
   "mockResponse",
@@ -1970,20 +2036,29 @@ var ACCOUNT_ONLY_OPTIONS = [
   "signingHeader"
 ];
 var AgentSession = class {
-  constructor(baseUrl, webhookUrl, clientName) {
+  constructor(baseUrl, webhookUrl, clientName, credentialsFile) {
     this.baseUrl = baseUrl;
     this.webhookUrl = webhookUrl;
     this.clientName = clientName;
+    this.credentialsFile = credentialsFile;
     this.sandbox = null;
-    this.claim = null;
-    this.connected = false;
+    this.connect = null;
+  }
+  sandboxOptions() {
+    return {
+      baseUrl: this.baseUrl,
+      webhookUrl: this.webhookUrl,
+      clientName: this.clientName,
+      credentialsFile: this.credentialsFile
+    };
   }
   /**
-   * The sandbox, registered on first use and again after it expired. Tool
-   * calls can run in parallel: this.sandbox is read again after every await,
-   * and a new sandbox is assigned with no await in between, so parallel
-   * calls share one registration. Calls waiting on a registration that fails
-   * get its error (a 429 asks them to wait); the next call starts again.
+   * The sandbox: the one saved by an earlier session when it is still live,
+   * else a new registration (and again after it expired). Tool calls can run
+   * in parallel: this.sandbox is read again after every await, and a new
+   * sandbox is assigned with no await in between, so parallel calls share
+   * one registration. Calls waiting on a registration that fails get its
+   * error (a 429 asks them to wait); the next call starts again.
    */
   async sandboxClient() {
     while (this.sandbox) {
@@ -1991,35 +2066,36 @@ var AgentSession = class {
       const sandbox = await pending;
       if (!this.expired(pending, sandbox)) return sandbox;
     }
-    const created = import_sdk2.WebhooksCC.sandbox({
-      baseUrl: this.baseUrl,
-      webhookUrl: this.webhookUrl,
-      clientName: this.clientName
-    });
+    const created = import_sdk2.WebhooksCC.sandbox(this.sandboxOptions());
     this.sandbox = created;
     created.catch(() => {
       if (this.sandbox === created) this.sandbox = null;
     });
     return created;
   }
-  /** The live sandbox, if one was registered; never registers one. */
+  /** The live sandbox, from this session or the credential file; never registers one. */
   async existingSandbox() {
     const pending = this.sandbox;
-    if (!pending) return null;
-    let sandbox;
-    try {
-      sandbox = await pending;
-    } catch {
-      return null;
+    if (pending) {
+      let sandbox;
+      try {
+        sandbox = await pending;
+      } catch {
+        return null;
+      }
+      return this.expired(pending, sandbox) ? null : sandbox;
     }
-    return this.expired(pending, sandbox) ? null : sandbox;
+    const resumed = await import_sdk2.SandboxClient.resume(this.sandboxOptions()).catch(() => null);
+    if (!resumed) return null;
+    if (!this.sandbox) this.sandbox = Promise.resolve(resumed);
+    return this.sandbox;
   }
   /** True when the sandbox is past its 24 hours; then it is dropped. */
   expired(pending, sandbox) {
     if (sandbox.expiresAt.getTime() > Date.now()) return false;
     if (this.sandbox === pending) this.sandbox = null;
-    if (this.claim?.kind === "sandbox" && this.claim.claimToken === sandbox.registration.claimToken) {
-      this.claim = null;
+    if (this.connect?.via === "sandbox" && this.connect.sandbox === sandbox) {
+      this.connect = null;
     }
     return true;
   }
@@ -2030,26 +2106,11 @@ var AgentSession = class {
     }
     return sandbox;
   }
-  forgetSandbox() {
+  reset() {
     this.sandbox = null;
+    this.connect = null;
   }
 };
-function claimedTokens(baseUrl, assertion, first) {
-  let current = first;
-  let pending = null;
-  return async (options) => {
-    if (!options?.forceRefresh && current.expiresAt.getTime() - Date.now() > TOKEN_REFRESH_MARGIN_MS) {
-      return current.accessToken;
-    }
-    if (!pending) {
-      pending = import_sdk2.WebhooksCC.agent.exchange({ baseUrl, assertion }).finally(() => {
-        pending = null;
-      });
-    }
-    current = await pending;
-    return current.accessToken;
-  };
-}
 function minutesLeft(until) {
   return Math.max(1, Math.round((until.getTime() - Date.now()) / 6e4));
 }
@@ -2057,16 +2118,53 @@ function onlyKind(requests, kind) {
   if (!kind) return requests;
   return requests.filter((request) => (request.kind ?? "http") === kind);
 }
+function savedTo(credentialsFile) {
+  return import_sdk2.AgentCredentialStore.resolve(credentialsFile)?.path ?? null;
+}
 function registerSandboxTools(server, options = {}) {
   const baseUrl = options.baseUrl ?? process.env.WHK_BASE_URL ?? "https://webhooks.cc";
+  const webhookUrl = options.webhookUrl ?? process.env.WHK_WEBHOOK_URL;
   const session = new AgentSession(
     baseUrl,
-    options.webhookUrl ?? process.env.WHK_WEBHOOK_URL,
-    options.clientName ?? "webhooks-cc-mcp"
-  );
-  const registered = [];
+    webhookUrl,
+    options.clientName ?? "webhooks-cc-mcp",
+    options.credentialsFile
+  );
+  let handles = [];
+  let shown = 0;
+  const swap = (register) => {
+    const id = ++shown;
+    for (const handle of handles) handle.remove();
+    handles = register(id);
+  };
+  const showSandbox = () => swap(() => sandboxToolSet(server, session, showAccount));
+  const savedAccount = (id) => options.credentialsFile === false ? null : import_sdk2.WebhooksCC.fromSavedConnection({
+    baseUrl,
+    webhookUrl,
+    credentialsFile: options.credentialsFile,
+    // The human disconnected the agent: back to the sandbox, unless a
+    // newer connection is already on display.
+    onRevoked: () => queueMicrotask(() => {
+      if (shown === id) showSandbox();
+    })
+  });
+  function showAccount(client) {
+    swap((id) => registerTools(server, savedAccount(id) ?? client));
+    options.onConnected?.(client);
+  }
+  const saved = savedAccount(1);
+  if (saved) {
+    swap(() => registerTools(server, saved));
+    options.onConnected?.(saved);
+  } else {
+    showSandbox();
+  }
+}
+function sandboxToolSet(server, session, showAccount) {
+  const tools = [];
   const limits = `up to ${SANDBOX.maxEndpoints} endpoints at a time, ${SANDBOX.requestsPerEndpoint} captured requests each and ${SANDBOX.requests} in all, deleted ${SANDBOX.lifetimeHours} hours after the sandbox was created`;
-  registered.push(
+  const file = savedTo(session.credentialsFile);
+  tools.push(
     server.tool(
       "create_endpoint",
       `Create a temporary webhook capture endpoint in the agent sandbox (no account needed): ${limits}. The first call registers the sandbox, which takes a few seconds of proof of work. Mock responses, notifications and signature verification need an account: see connect_account.`,
@@ -2090,7 +2188,7 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "list_endpoints",
       "List this agent's sandbox endpoints. Empty until create_endpoint starts the sandbox.",
@@ -2104,7 +2202,7 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "get_endpoint",
       "Get one of this agent's sandbox endpoints by slug, with its sandbox limits and usage.",
@@ -2114,7 +2212,7 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "delete_endpoint",
       "Delete one of this agent's sandbox endpoints and its captured requests. Frees a slot; the sandbox's request budget is not refunded.",
@@ -2125,7 +2223,7 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "list_requests",
       "List recent requests captured by a sandbox endpoint, newest first.",
@@ -2137,7 +2235,7 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "get_request",
       "Get full details for a request captured by a sandbox endpoint.",
@@ -2148,7 +2246,7 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "wait_for_request",
       "Wait for a request to arrive at a sandbox endpoint.",
@@ -2160,7 +2258,7 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "generate_payload_schema",
       "Generate TypeScript interfaces, Zod schemas, Pydantic models, or JSON Schema from the bodies of requests captured by a sandbox endpoint. Several requests of one event teach which fields are optional or nullable.",
@@ -2172,62 +2270,59 @@ function registerSandboxTools(server, options = {}) {
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "connect_account",
       "Connect this agent to a human's webhooks.cc account, for the full tool set (mock responses, signatures, email, teams) and to keep the sandbox endpoints. Returns a link and a 6-digit code: show both to the human, who signs in or signs up with that email and enters the code. Then call wait_for_connection. Calling again gives a new code.",
       {
-        email: import_zod3.z.string().email({ message: "Invalid email address" }).describe("The human's email address; only someone signed in as it can connect")
+        email: import_zod3.z.string().email({ message: "Invalid email address" }).describe(
+          "The email the human signs in to webhooks.cc with (their GitHub or Google primary email if they sign in that way); only someone signed in as it can connect"
+        )
       },
       withErrorHandling(async ({ email }) => {
-        if (session.connected) {
-          return jsonContent({ connected: true, message: "Already connected to an account." });
-        }
         const normalized = email.trim().toLowerCase();
+        const previous = session.connect;
         const sandbox = await session.existingSandbox();
-        let claim;
+        let attempt;
+        let movesEndpoints = false;
         if (sandbox) {
-          claim = {
-            kind: "sandbox",
-            claimToken: sandbox.registration.claimToken,
-            email: normalized,
-            attempt: await sandbox.claim({ email: normalized }),
-            claimExpires: sandbox.expiresAt
-          };
-        } else if (session.claim?.kind === "service_auth" && session.claim.email === normalized && session.claim.claimExpires.getTime() > Date.now()) {
-          const attempt = await import_sdk2.WebhooksCC.agent.startClaim({
-            baseUrl,
-            claimToken: session.claim.claimToken
-          });
-          claim = { ...session.claim, attempt };
+          const claim = await sandbox.claim({ email: normalized });
+          session.connect = { via: "sandbox", sandbox, email: normalized, attempt: claim };
+          attempt = claim;
+          movesEndpoints = claim.movesEndpoints;
         } else {
-          const registration = await import_sdk2.WebhooksCC.agent.registerServiceAuth({
-            baseUrl,
-            email: normalized,
-            clientName: session.clientName
-          });
-          claim = {
-            kind: "service_auth",
-            claimToken: registration.claimToken,
+          let pending = null;
+          if (previous?.via === "connect" && previous.email === normalized) {
+            pending = await previous.pending.restart().catch((error) => {
+              if (error instanceof import_sdk2.AgentAuthError) return null;
+              throw error;
+            });
+          }
+          pending ?? (pending = await import_sdk2.WebhooksCC.connect({
+            baseUrl: session.baseUrl,
+            webhookUrl: session.webhookUrl,
             email: normalized,
-            attempt: registration.claim,
-            claimExpires: registration.claimTokenExpires
-          };
+            clientName: session.clientName,
+            credentialsFile: session.credentialsFile
+          }));
+          session.connect = { via: "connect", pending, email: normalized };
+          attempt = pending;
         }
-        session.claim = claim;
-        const { verificationUri, userCode, expiresAt } = claim.attempt;
+        const { verificationUri, userCode, expiresAt } = attempt;
         return jsonContent({
           verificationUri,
           userCode,
           expiresAt: expiresAt.toISOString(),
           tellTheHuman: `Open ${verificationUri}, sign in or sign up as ${normalized}, and enter the code ${userCode}.`,
           next: `Show the human that line, then call wait_for_connection. The code works for about ${minutesLeft(expiresAt)} minutes; connect_account gives a new one.`,
-          ...claim.kind === "sandbox" ? { endpoints: "The sandbox endpoints move into that account with what they captured." } : {}
+          ...sandbox ? {
+            endpoints: movesEndpoints ? "The sandbox endpoints move into that account with what they captured." : "The sandbox endpoints were made in an earlier session, so they stay in the sandbox until it expires; the account starts without them."
+          } : {}
         });
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "wait_for_connection",
       `Wait for the human to enter the code from connect_account. On success the full webhooks.cc tools for their account replace these sandbox tools. Returns after timeoutSeconds (default ${DEFAULT_WAIT_SECONDS}) if they have not finished yet; call it again to keep waiting.`,
@@ -2235,28 +2330,22 @@ function registerSandboxTools(server, options = {}) {
         timeoutSeconds: import_zod3.z.number().int().min(1).max(MAX_WAIT_SECONDS).optional().describe(`How long to wait, in seconds (default ${DEFAULT_WAIT_SECONDS})`)
       },
       withErrorHandling(async ({ timeoutSeconds }) => {
-        if (session.connected) {
-          return jsonContent({ connected: true, message: "Already connected to an account." });
-        }
-        const claim = session.claim;
-        if (!claim) {
+        const pending = session.connect;
+        if (!pending) {
           throw new Error("Nothing to wait for: call connect_account first.");
         }
-        let claimed;
+        const timeout = (timeoutSeconds ?? DEFAULT_WAIT_SECONDS) * 1e3;
+        const expiresAt = pending.via === "sandbox" ? pending.attempt.expiresAt : pending.pending.expiresAt;
+        let client;
         try {
-          claimed = await import_sdk2.WebhooksCC.agent.waitForClaim({
-            baseUrl,
-            claimToken: claim.claimToken,
-            interval: claim.attempt.interval,
-            timeout: (timeoutSeconds ?? DEFAULT_WAIT_SECONDS) * 1e3
-          });
+          client = pending.via === "sandbox" ? await pending.sandbox.waitForClaim({ timeout }) : await pending.pending.wait({ timeout });
         } catch (error) {
           if (!(error instanceof import_sdk2.AgentAuthError)) throw error;
           if (error.code === "timeout") {
             return jsonContent({
               connected: false,
               status: "waiting",
-              message: `Not connected yet. The code works until ${claim.attempt.expiresAt.toISOString()}; call wait_for_connection again.`
+              message: `Not connected yet. The code works until ${expiresAt.toISOString()}; call wait_for_connection again.`
             });
           }
           if (error.code === "expired_token") {
@@ -2275,34 +2364,25 @@ function registerSandboxTools(server, options = {}) {
           }
           throw error;
         }
-        const client = new import_sdk2.WebhooksCC({
-          baseUrl,
-          webhookUrl: session.webhookUrl,
-          getAccessToken: claimedTokens(baseUrl, claimed.identityAssertion, claimed.token)
-        });
-        session.connected = true;
-        session.claim = null;
-        session.forgetSandbox();
-        for (const tool of registered) tool.remove();
-        registerTools(server, client);
-        options.onConnected?.(client);
+        const movedEndpoints = pending.via === "sandbox" && pending.attempt.movesEndpoints;
+        session.reset();
+        showAccount(client);
         return jsonContent({
           connected: true,
-          email: claim.email,
-          scope: claimed.token.scope,
-          message: `Connected to the webhooks.cc account of ${claim.email}. The full tool set has replaced the sandbox tools (the tool list changed; if your client does not pick that up, ask the user to restart it).${claim.kind === "sandbox" ? " The sandbox endpoints are now that account's endpoints, with what they captured." : ""} This connection lasts while this MCP server runs; for a lasting setup, the human can create an API key under Account and set WHK_API_KEY.`
+          email: pending.email,
+          message: `Connected to the webhooks.cc account of ${pending.email}. The full tool set has replaced the sandbox tools (the tool list changed; if your client does not pick that up, ask the user to restart it).${movedEndpoints ? " The sandbox endpoints are now that account's endpoints, with what they captured." : ""} ${file ? `The connection is saved in ${file}, so later sessions, the whk CLI and the SDKs start connected; it lasts 90 days, and the human can remove it under Account, Connected agents.` : "This connection lasts while this MCP server runs; for a lasting setup, the human can create an API key under Account and set WHK_API_KEY."}`
         });
       })
     )
   );
-  registered.push(
+  tools.push(
     server.tool(
       "about_sandbox",
       "Explain what this agent can do without a webhooks.cc account, the sandbox limits, and how to connect an account. No network call.",
       {},
       withErrorHandling(async () => {
         return jsonContent({
-          mode: "sandbox (no WHK_API_KEY)",
+          mode: "sandbox (no WHK_API_KEY, no saved connection)",
           sandbox: {
             maxEndpoints: SANDBOX.maxEndpoints,
             requestsPerEndpoint: SANDBOX.requestsPerEndpoint,
@@ -2313,21 +2393,23 @@ function registerSandboxTools(server, options = {}) {
             notAvailable: "Mock responses, response rules, notifications, signature verification, email capture, forwarding, teams and sending webhooks."
           },
           connectAnAccount: [
-            "Call connect_account with the human's email and show them the link and code it returns.",
+            "Call connect_account with the email the human signs in to webhooks.cc with, and show them the link and code it returns.",
             "Call wait_for_connection until it reports connected; the full tools for their account then replace the sandbox tools.",
-            "Sandbox endpoints move into the account with their captured requests."
+            "Sandbox endpoints registered by this server process move into the account with their captured requests; a sandbox resumed from an earlier session stays in the sandbox (connect_account says which)."
           ],
+          savedIn: file ? `${file} (shared with the whk CLI and the SDKs): the sandbox and the connection survive restarts.` : "nowhere: this session only.",
           withAnApiKey: "Set WHK_API_KEY to a whcc_ key from the dashboard and restart for the full tools from the start.",
           docs: DOCS_URL,
-          protocol: `${baseUrl}/auth.md`
+          protocol: `${session.baseUrl}/auth.md`
         });
       })
     )
   );
+  return tools;
 }
 
 // src/index.ts
-var VERSION = true ? "1.14.0" : "0.0.0-dev";
+var VERSION = true ? "1.15.0" : "0.0.0-dev";
 function createServer(options = {}) {
   const apiKey = options.apiKey ?? process.env.WHK_API_KEY;
   const webhookUrl = options.webhookUrl ?? process.env.WHK_WEBHOOK_URL;
@@ -2338,7 +2420,7 @@ function createServer(options = {}) {
     { debouncedNotificationMethods: ["notifications/tools/list_changed"] }
   );
   if (!apiKey) {
-    registerSandboxTools(server, { baseUrl, webhookUrl });
+    registerSandboxTools(server, { baseUrl, webhookUrl, credentialsFile: options.credentialsFile });
     registerPrompts(server);
     return server;
   }
@@ -2367,13 +2449,16 @@ function mcpServerConfig(apiKey) {
   return {
     command: "npx",
     args: ["-y", "@webhooks-cc/mcp"],
-    env: { WHK_API_KEY: apiKey }
+    ...apiKey ? { env: { WHK_API_KEY: apiKey } } : {}
   };
 }
+function vscodeServerConfig(apiKey) {
+  return { type: "stdio", ...mcpServerConfig(apiKey) };
+}
 function resolveApiKey(flags) {
   return flags["api-key"] ?? process.env.WHK_API_KEY ?? null;
 }
-function mergeJsonConfig(filePath, serverName, serverConfig) {
+function mergeJsonConfig(filePath, serverName, serverConfig, key = "mcpServers") {
   let existing = {};
   if ((0, import_fs.existsSync)(filePath)) {
     try {
@@ -2384,9 +2469,9 @@ function mergeJsonConfig(filePath, serverName, serverConfig) {
       (0, import_fs.copyFileSync)(filePath, `${filePath}.bak`);
     }
   }
-  const mcpServers = existing.mcpServers ?? {};
-  mcpServers[serverName] = serverConfig;
-  existing.mcpServers = mcpServers;
+  const servers = existing[key] ?? {};
+  servers[serverName] = serverConfig;
+  existing[key] = servers;
   const dir = (0, import_path.dirname)(filePath);
   if (!(0, import_fs.existsSync)(dir)) (0, import_fs.mkdirSync)(dir, { recursive: true });
   (0, import_fs.writeFileSync)(filePath, JSON.stringify(existing, null, 2) + "\n");
@@ -2423,8 +2508,7 @@ function setupClaudeCode(apiKey) {
         "--transport",
         "stdio",
         "webhooks-cc",
-        "-e",
-        `WHK_API_KEY=${apiKey}`,
+        ...apiKey ? ["-e", `WHK_API_KEY=${apiKey}`] : [],
         "--",
         "npx",
         "-y",
@@ -2439,7 +2523,7 @@ function setupClaudeCode(apiKey) {
     console.error("Install it: npm install -g @anthropic-ai/claude-code");
     console.error("\nManual alternative \u2014 run this command:");
     console.error(
-      `  claude mcp add -s user --transport stdio webhooks-cc -e WHK_API_KEY=<your-key> -- npx -y @webhooks-cc/mcp`
+      `  claude mcp add -s user --transport stdio webhooks-cc${apiKey ? " -e WHK_API_KEY=<your-key>" : ""} -- npx -y @webhooks-cc/mcp`
     );
     process.exit(1);
   }
@@ -2458,7 +2542,7 @@ function setupCursor(apiKey) {
 }
 function setupVSCode(apiKey) {
   const configPath = (0, import_path.join)(process.cwd(), ".vscode", "mcp.json");
-  mergeJsonConfig(configPath, "webhooks-cc", mcpServerConfig(apiKey));
+  mergeJsonConfig(configPath, "webhooks-cc", vscodeServerConfig(apiKey), "servers");
   console.log(`Done! Config written to ${configPath}`);
   console.log("Reload VS Code window for changes to take effect.");
 }
@@ -2470,8 +2554,7 @@ function setupCodex(apiKey) {
         "mcp",
         "add",
         "webhooks-cc",
-        "-e",
-        `WHK_API_KEY=${apiKey}`,
+        ...apiKey ? ["-e", `WHK_API_KEY=${apiKey}`] : [],
         "--",
         "npx",
         "-y",
@@ -2484,13 +2567,13 @@ function setupCodex(apiKey) {
     console.error("\nFailed to run 'codex mcp add'. Is OpenAI Codex CLI installed?");
     console.error("\nManual alternative \u2014 add to ~/.codex/config.toml:");
     console.error(`
-[mcp.webhooks-cc]
+[mcp_servers.webhooks-cc]
 command = "npx"
 args = ["-y", "@webhooks-cc/mcp"]
-
-[mcp.webhooks-cc.env]
+${apiKey ? `
+[mcp_servers.webhooks-cc.env]
 WHK_API_KEY = "<your-key>"
-`);
+` : ""}`);
     process.exit(1);
   }
 }
@@ -2507,6 +2590,9 @@ function printUsage() {
 Usage:
   npx @webhooks-cc/mcp setup <tool> [--api-key <key>]
 
+Without a key the server starts in the keyless agent sandbox; your agent can
+connect your account later (connect_account), and the connection is saved.
+
 Tools:
   claude-code      Claude Code CLI (runs 'claude mcp add')
   claude-desktop   Claude Desktop app
@@ -2516,9 +2602,10 @@ Tools:
   windsurf         Windsurf editor
 
 Options:
-  --api-key <key>  Your webhooks.cc API key (or set WHK_API_KEY env var)
+  --api-key <key>  Your webhooks.cc API key (or set WHK_API_KEY env var); optional
 
 Examples:
+  npx @webhooks-cc/mcp setup claude-code
   npx @webhooks-cc/mcp setup claude-code --api-key whcc_abc123
   WHK_API_KEY=whcc_abc123 npx @webhooks-cc/mcp setup cursor
   npx @webhooks-cc/mcp setup vscode --api-key whcc_abc123
@@ -2546,14 +2633,13 @@ function runSetup(args2) {
     process.exit(tool ? 1 : 0);
   }
   const apiKey = resolveApiKey(flags);
-  if (!apiKey) {
-    console.error("Error: API key required. Pass --api-key or set WHK_API_KEY env var.");
-    console.error("Get your API key at https://webhooks.cc/account/api-keys\n");
-    process.exit(1);
-  }
-  validateApiKeyFormat(apiKey);
+  if (apiKey) validateApiKeyFormat(apiKey);
   console.log(`Setting up webhooks-cc MCP server for ${tool}...
 `);
+  if (!apiKey) {
+    console.log("No API key: the server starts in the keyless agent sandbox. Your agent can");
+    console.log("connect your account later with connect_account; the connection is saved.\n");
+  }
   switch (tool) {
     case "claude-code":
       setupClaudeCode(apiKey);
@@ -2591,17 +2677,25 @@ Usage:
   npx @webhooks-cc/mcp --help             Show this help
 
 Environment:
-  WHK_API_KEY        Your webhooks.cc API key (required)
+  WHK_API_KEY        Your webhooks.cc API key (optional; without it the server
+                     starts connected to the account your agent was connected
+                     to before, or in the keyless agent sandbox)
+  WHK_AGENT_FILE     Where the sandbox and the connection are saved (default:
+                     ~/.config/whk/agent.json, shared with the whk CLI and SDKs)
   WHK_WEBHOOK_URL    Custom webhook receiver URL (optional)
   WHK_BASE_URL       Custom API base URL (optional)
 
 Setup:
-  npx @webhooks-cc/mcp setup claude-code --api-key whcc_...
-  npx @webhooks-cc/mcp setup cursor --api-key whcc_...
-  npx @webhooks-cc/mcp setup vscode --api-key whcc_...
-  npx @webhooks-cc/mcp setup codex --api-key whcc_...
-  npx @webhooks-cc/mcp setup windsurf --api-key whcc_...
-  npx @webhooks-cc/mcp setup claude-desktop --api-key whcc_...
+  npx @webhooks-cc/mcp setup claude-code
+  npx @webhooks-cc/mcp setup cursor
+  npx @webhooks-cc/mcp setup vscode
+  npx @webhooks-cc/mcp setup codex
+  npx @webhooks-cc/mcp setup windsurf
+  npx @webhooks-cc/mcp setup claude-desktop
+  (add --api-key whcc_... to start with your account's tools)
+
+Hosted agents (claude.ai, ChatGPT): add https://webhooks.cc/mcp as a remote
+MCP server instead; you approve it once in your browser.
 
 Get your API key at https://webhooks.cc/account/api-keys
 `);