@webhooks-cc/mcp 1.5.0 → 1.7.0

package/README.md

@@ -149,10 +149,14 @@ Provider template and signing support includes:
 - `mux`
 - `sentry`
 - `bitbucket`
+- `docusign`
+- `adyen`
+- `paypal`
+- `plaid`
 
 Signature verification also supports:
 
-- all template providers except `sendgrid`, which uses IP allowlisting instead of cryptographic signatures
+- all template providers except `sendgrid` (IP allowlisting) and `plaid` (JWT/JWK verification requires Plaid API credentials)
 
 Use `list_provider_templates` to inspect templates, default events, signature headers, and signing requirements from the agent.
 

package/dist/bin/mcp.js

@@ -687,15 +687,17 @@ function registerTools(server, client) {
       provider: import_zod2.z.enum(import_sdk.TEMPLATE_PROVIDERS).optional().describe("Optional provider template to send with signed headers"),
       template: import_zod2.z.string().optional().describe("Provider-specific template preset"),
       event: import_zod2.z.string().optional().describe("Provider event or topic name"),
-      secret: import_zod2.z.string().optional().describe("Signing secret. Required when provider is set.")
+      secret: import_zod2.z.string().optional().describe(
+        "Signing secret. Required for signed provider templates; omit for secretless providers (sendgrid, discord, plaid)."
+      )
     },
     withErrorHandling(
       async ({ slug, method, headers, body, provider, template, event, secret }) => {
         let response;
         if (provider) {
           const templateSecret = secret?.trim();
-          if (!templateSecret) {
-            throw new Error("send_webhook with provider templates requires a non-empty secret");
+          if (!templateSecret && import_sdk.TEMPLATE_METADATA[provider]?.secretRequired !== false) {
+            throw new Error(`send_webhook with provider "${provider}" requires a non-empty secret`);
           }
           response = await client.endpoints.sendTemplate(slug, {
             provider,
@@ -871,7 +873,7 @@ function registerTools(server, client) {
       requestId: import_zod2.z.string().describe("The captured request ID"),
       provider: import_zod2.z.enum(import_sdk.VERIFY_PROVIDERS).optional().describe("Provider whose signature scheme should be verified. Omit to use stored result."),
       secret: import_zod2.z.string().optional().describe(
-        "Shared signing secret. Required for non-Discord providers when doing client-side verification."
+        "Provider credential for client-side verification (for example a shared signing secret, Adyen hex HMAC key, or PayPal webhook ID). Required for non-Discord providers."
       ),
       publicKey: import_zod2.z.string().optional().describe("Discord application public key. Required for provider=discord."),
       url: httpUrlSchema.optional().describe("Original signed URL. Required for Twilio, Square, and HubSpot verification."),
@@ -943,7 +945,9 @@ function registerTools(server, client) {
       provider: import_zod2.z.enum(import_sdk.TEMPLATE_PROVIDERS).optional().describe("Optional provider template for signing"),
       template: import_zod2.z.string().optional().describe("Provider-specific template preset"),
       event: import_zod2.z.string().optional().describe("Provider event or topic name"),
-      secret: import_zod2.z.string().optional().describe("Signing secret. Required when provider is set.")
+      secret: import_zod2.z.string().optional().describe(
+        "Signing secret. Required for signed provider templates; omit for secretless providers (sendgrid, discord, plaid)."
+      )
     },
     withErrorHandling(async ({ url, method, headers, body, provider, template, event, secret }) => {
       const response = await client.sendTo(url, {
@@ -974,7 +978,9 @@ function registerTools(server, client) {
       provider: import_zod2.z.enum(import_sdk.TEMPLATE_PROVIDERS).optional().describe("Optional provider template for signing"),
       template: import_zod2.z.string().optional().describe("Provider-specific template preset"),
       event: import_zod2.z.string().optional().describe("Provider event or topic name"),
-      secret: import_zod2.z.string().optional().describe("Signing secret. Required when provider is set.")
+      secret: import_zod2.z.string().optional().describe(
+        "Signing secret. Required for signed provider templates; omit for secretless providers (sendgrid, discord, plaid)."
+      )
     },
     withErrorHandling(async ({ url, method, headers, body, provider, template, event, secret }) => {
       const preview = await client.buildRequest(url, {
@@ -1050,9 +1056,9 @@ function registerTools(server, client) {
         }
         if (provider) {
           const templateSecret = secret?.trim();
-          if (!templateSecret) {
+          if (!templateSecret && import_sdk.TEMPLATE_METADATA[provider]?.secretRequired !== false) {
             throw new Error(
-              "test_webhook_flow with provider templates requires a non-empty secret"
+              `test_webhook_flow with provider "${provider}" requires a non-empty secret`
             );
           }
           flow.sendTemplate({
@@ -1066,6 +1072,11 @@ function registerTools(server, client) {
                 "test_webhook_flow cannot verify Discord signatures (Ed25519 requires a public key, not a secret)"
               );
             }
+            if (!templateSecret) {
+              throw new Error(
+                `test_webhook_flow cannot verify "${provider}" signatures \u2014 this provider's templates are unsigned`
+              );
+            }
             flow.verifySignature({
               provider,
               secret: templateSecret
@@ -1103,24 +1114,127 @@ 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 have a human run claim_agent with the returned userCode while logged in to webhooks.cc.",
+          "Or set WHK_API_KEY to an existing whcc_ key and use the authenticated tools."
+        ]
+      });
+    })
+  );
+  server.tool(
+    "register_agent",
+    "Self-register for a webhooks.cc API credential via the anonymous auth.md flow. Returns a whcc_ API key that works immediately in a bounded sandbox, plus a short userCode and claimUrl a human uses to bind the key to their account. No authentication required. After registering, set WHK_API_KEY to the returned credential.",
+    {
+      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: "Set WHK_API_KEY to `credential` to use the authenticated tools. Before it is claimed the key can create ephemeral endpoints and read its own captured requests in the sandbox."
+      });
+    })
+  );
+  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);
+    })
+  );
+  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.`
+      });
+    })
+  );
+  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."
+      });
+    })
+  );
+  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."
+      });
+    })
+  );
 }
 
 // src/index.ts
-var VERSION = true ? "1.5.0" : "0.0.0-dev";
+var VERSION = true ? "1.7.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
+  });
   if (!apiKey) {
-    throw new Error("Missing API key. Set WHK_API_KEY environment variable or pass apiKey option.");
+    registerAgentRegistrationTools(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 server = new import_mcp2.McpServer({
-    name: "webhooks-cc",
-    version: VERSION
-  });
   registerTools(server, client);
   registerPrompts(server);
   registerResources(server, client);

package/dist/index.d.mts

@@ -3,6 +3,14 @@ import { WebhooksCC } from '@webhooks-cc/sdk';
 
 /** Register all webhook tools on an MCP server instance. */
 declare function registerTools(server: McpServer, client: WebhooksCC): void;
+/**
+ * Agent self-registration tools (auth.md). These are UNAUTHENTICATED — they let
+ * an agent that does NOT yet have a webhooks.cc credential obtain one, then
+ * configure the MCP server with the returned key (WHK_API_KEY). Registered on
+ * every server so a probing agent can always discover the on-ramp via
+ * `describe` / `how_to_register`.
+ */
+declare function registerAgentRegistrationTools(server: McpServer): void;
 
 declare function registerPrompts(server: McpServer): void;
 
@@ -30,4 +38,4 @@ interface CreateServerOptions {
  */
 declare function createServer(options?: CreateServerOptions): McpServer;
 
-export { type CreateServerOptions, createServer, registerPrompts, registerResources, registerTools };
+export { type CreateServerOptions, createServer, registerAgentRegistrationTools, registerPrompts, registerResources, registerTools };

package/dist/index.d.ts

@@ -3,6 +3,14 @@ import { WebhooksCC } from '@webhooks-cc/sdk';
 
 /** Register all webhook tools on an MCP server instance. */
 declare function registerTools(server: McpServer, client: WebhooksCC): void;
+/**
+ * Agent self-registration tools (auth.md). These are UNAUTHENTICATED — they let
+ * an agent that does NOT yet have a webhooks.cc credential obtain one, then
+ * configure the MCP server with the returned key (WHK_API_KEY). Registered on
+ * every server so a probing agent can always discover the on-ramp via
+ * `describe` / `how_to_register`.
+ */
+declare function registerAgentRegistrationTools(server: McpServer): void;
 
 declare function registerPrompts(server: McpServer): void;
 
@@ -30,4 +38,4 @@ interface CreateServerOptions {
  */
 declare function createServer(options?: CreateServerOptions): McpServer;
 
-export { type CreateServerOptions, createServer, registerPrompts, registerResources, registerTools };
+export { type CreateServerOptions, createServer, registerAgentRegistrationTools, registerPrompts, registerResources, registerTools };

package/dist/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   createServer: () => createServer,
+  registerAgentRegistrationTools: () => registerAgentRegistrationTools,
   registerPrompts: () => registerPrompts,
   registerResources: () => registerResources,
   registerTools: () => registerTools
@@ -708,15 +709,17 @@ function registerTools(server, client) {
       provider: import_zod2.z.enum(import_sdk.TEMPLATE_PROVIDERS).optional().describe("Optional provider template to send with signed headers"),
       template: import_zod2.z.string().optional().describe("Provider-specific template preset"),
       event: import_zod2.z.string().optional().describe("Provider event or topic name"),
-      secret: import_zod2.z.string().optional().describe("Signing secret. Required when provider is set.")
+      secret: import_zod2.z.string().optional().describe(
+        "Signing secret. Required for signed provider templates; omit for secretless providers (sendgrid, discord, plaid)."
+      )
     },
     withErrorHandling(
       async ({ slug, method, headers, body, provider, template, event, secret }) => {
         let response;
         if (provider) {
           const templateSecret = secret?.trim();
-          if (!templateSecret) {
-            throw new Error("send_webhook with provider templates requires a non-empty secret");
+          if (!templateSecret && import_sdk.TEMPLATE_METADATA[provider]?.secretRequired !== false) {
+            throw new Error(`send_webhook with provider "${provider}" requires a non-empty secret`);
           }
           response = await client.endpoints.sendTemplate(slug, {
             provider,
@@ -892,7 +895,7 @@ function registerTools(server, client) {
       requestId: import_zod2.z.string().describe("The captured request ID"),
       provider: import_zod2.z.enum(import_sdk.VERIFY_PROVIDERS).optional().describe("Provider whose signature scheme should be verified. Omit to use stored result."),
       secret: import_zod2.z.string().optional().describe(
-        "Shared signing secret. Required for non-Discord providers when doing client-side verification."
+        "Provider credential for client-side verification (for example a shared signing secret, Adyen hex HMAC key, or PayPal webhook ID). Required for non-Discord providers."
       ),
       publicKey: import_zod2.z.string().optional().describe("Discord application public key. Required for provider=discord."),
       url: httpUrlSchema.optional().describe("Original signed URL. Required for Twilio, Square, and HubSpot verification."),
@@ -964,7 +967,9 @@ function registerTools(server, client) {
       provider: import_zod2.z.enum(import_sdk.TEMPLATE_PROVIDERS).optional().describe("Optional provider template for signing"),
       template: import_zod2.z.string().optional().describe("Provider-specific template preset"),
       event: import_zod2.z.string().optional().describe("Provider event or topic name"),
-      secret: import_zod2.z.string().optional().describe("Signing secret. Required when provider is set.")
+      secret: import_zod2.z.string().optional().describe(
+        "Signing secret. Required for signed provider templates; omit for secretless providers (sendgrid, discord, plaid)."
+      )
     },
     withErrorHandling(async ({ url, method, headers, body, provider, template, event, secret }) => {
       const response = await client.sendTo(url, {
@@ -995,7 +1000,9 @@ function registerTools(server, client) {
       provider: import_zod2.z.enum(import_sdk.TEMPLATE_PROVIDERS).optional().describe("Optional provider template for signing"),
       template: import_zod2.z.string().optional().describe("Provider-specific template preset"),
       event: import_zod2.z.string().optional().describe("Provider event or topic name"),
-      secret: import_zod2.z.string().optional().describe("Signing secret. Required when provider is set.")
+      secret: import_zod2.z.string().optional().describe(
+        "Signing secret. Required for signed provider templates; omit for secretless providers (sendgrid, discord, plaid)."
+      )
     },
     withErrorHandling(async ({ url, method, headers, body, provider, template, event, secret }) => {
       const preview = await client.buildRequest(url, {
@@ -1071,9 +1078,9 @@ function registerTools(server, client) {
         }
         if (provider) {
           const templateSecret = secret?.trim();
-          if (!templateSecret) {
+          if (!templateSecret && import_sdk.TEMPLATE_METADATA[provider]?.secretRequired !== false) {
             throw new Error(
-              "test_webhook_flow with provider templates requires a non-empty secret"
+              `test_webhook_flow with provider "${provider}" requires a non-empty secret`
             );
           }
           flow.sendTemplate({
@@ -1087,6 +1094,11 @@ function registerTools(server, client) {
                 "test_webhook_flow cannot verify Discord signatures (Ed25519 requires a public key, not a secret)"
               );
             }
+            if (!templateSecret) {
+              throw new Error(
+                `test_webhook_flow cannot verify "${provider}" signatures \u2014 this provider's templates are unsigned`
+              );
+            }
             flow.verifySignature({
               provider,
               secret: templateSecret
@@ -1124,24 +1136,127 @@ 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 have a human run claim_agent with the returned userCode while logged in to webhooks.cc.",
+          "Or set WHK_API_KEY to an existing whcc_ key and use the authenticated tools."
+        ]
+      });
+    })
+  );
+  server.tool(
+    "register_agent",
+    "Self-register for a webhooks.cc API credential via the anonymous auth.md flow. Returns a whcc_ API key that works immediately in a bounded sandbox, plus a short userCode and claimUrl a human uses to bind the key to their account. No authentication required. After registering, set WHK_API_KEY to the returned credential.",
+    {
+      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: "Set WHK_API_KEY to `credential` to use the authenticated tools. Before it is claimed the key can create ephemeral endpoints and read its own captured requests in the sandbox."
+      });
+    })
+  );
+  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);
+    })
+  );
+  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.`
+      });
+    })
+  );
+  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."
+      });
+    })
+  );
+  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."
+      });
+    })
+  );
 }
 
 // src/index.ts
-var VERSION = true ? "1.5.0" : "0.0.0-dev";
+var VERSION = true ? "1.7.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
+  });
   if (!apiKey) {
-    throw new Error("Missing API key. Set WHK_API_KEY environment variable or pass apiKey option.");
+    registerAgentRegistrationTools(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 server = new import_mcp2.McpServer({
-    name: "webhooks-cc",
-    version: VERSION
-  });
   registerTools(server, client);
   registerPrompts(server);
   registerResources(server, client);
@@ -1150,6 +1265,7 @@ function createServer(options = {}) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createServer,
+  registerAgentRegistrationTools,
   registerPrompts,
   registerResources,
   registerTools

package/dist/index.mjs

@@ -1,6 +1,6 @@
 // src/index.ts
 import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { WebhooksCC } from "@webhooks-cc/sdk";
+import { WebhooksCC as WebhooksCC2 } from "@webhooks-cc/sdk";
 
 // src/prompts.ts
 import { z } from "zod";
@@ -250,11 +250,13 @@ import {
   MAX_GLOB_PATTERN_LEN,
   NotFoundError,
   RateLimitError,
+  TEMPLATE_METADATA,
   TEMPLATE_PROVIDERS,
   TimeoutError,
   UnauthorizedError,
   VERIFY_PROVIDERS,
   verifySignature,
+  WebhooksCC,
   WebhooksCCError
 } from "@webhooks-cc/sdk";
 var MAX_BODY_SIZE = 32768;
@@ -701,15 +703,17 @@ function registerTools(server, client) {
       provider: z2.enum(TEMPLATE_PROVIDERS).optional().describe("Optional provider template to send with signed headers"),
       template: z2.string().optional().describe("Provider-specific template preset"),
       event: z2.string().optional().describe("Provider event or topic name"),
-      secret: z2.string().optional().describe("Signing secret. Required when provider is set.")
+      secret: z2.string().optional().describe(
+        "Signing secret. Required for signed provider templates; omit for secretless providers (sendgrid, discord, plaid)."
+      )
     },
     withErrorHandling(
       async ({ slug, method, headers, body, provider, template, event, secret }) => {
         let response;
         if (provider) {
           const templateSecret = secret?.trim();
-          if (!templateSecret) {
-            throw new Error("send_webhook with provider templates requires a non-empty secret");
+          if (!templateSecret && TEMPLATE_METADATA[provider]?.secretRequired !== false) {
+            throw new Error(`send_webhook with provider "${provider}" requires a non-empty secret`);
           }
           response = await client.endpoints.sendTemplate(slug, {
             provider,
@@ -885,7 +889,7 @@ function registerTools(server, client) {
       requestId: z2.string().describe("The captured request ID"),
       provider: z2.enum(VERIFY_PROVIDERS).optional().describe("Provider whose signature scheme should be verified. Omit to use stored result."),
       secret: z2.string().optional().describe(
-        "Shared signing secret. Required for non-Discord providers when doing client-side verification."
+        "Provider credential for client-side verification (for example a shared signing secret, Adyen hex HMAC key, or PayPal webhook ID). Required for non-Discord providers."
       ),
       publicKey: z2.string().optional().describe("Discord application public key. Required for provider=discord."),
       url: httpUrlSchema.optional().describe("Original signed URL. Required for Twilio, Square, and HubSpot verification."),
@@ -957,7 +961,9 @@ function registerTools(server, client) {
       provider: z2.enum(TEMPLATE_PROVIDERS).optional().describe("Optional provider template for signing"),
       template: z2.string().optional().describe("Provider-specific template preset"),
       event: z2.string().optional().describe("Provider event or topic name"),
-      secret: z2.string().optional().describe("Signing secret. Required when provider is set.")
+      secret: z2.string().optional().describe(
+        "Signing secret. Required for signed provider templates; omit for secretless providers (sendgrid, discord, plaid)."
+      )
     },
     withErrorHandling(async ({ url, method, headers, body, provider, template, event, secret }) => {
       const response = await client.sendTo(url, {
@@ -988,7 +994,9 @@ function registerTools(server, client) {
       provider: z2.enum(TEMPLATE_PROVIDERS).optional().describe("Optional provider template for signing"),
       template: z2.string().optional().describe("Provider-specific template preset"),
       event: z2.string().optional().describe("Provider event or topic name"),
-      secret: z2.string().optional().describe("Signing secret. Required when provider is set.")
+      secret: z2.string().optional().describe(
+        "Signing secret. Required for signed provider templates; omit for secretless providers (sendgrid, discord, plaid)."
+      )
     },
     withErrorHandling(async ({ url, method, headers, body, provider, template, event, secret }) => {
       const preview = await client.buildRequest(url, {
@@ -1064,9 +1072,9 @@ function registerTools(server, client) {
         }
         if (provider) {
           const templateSecret = secret?.trim();
-          if (!templateSecret) {
+          if (!templateSecret && TEMPLATE_METADATA[provider]?.secretRequired !== false) {
             throw new Error(
-              "test_webhook_flow with provider templates requires a non-empty secret"
+              `test_webhook_flow with provider "${provider}" requires a non-empty secret`
             );
           }
           flow.sendTemplate({
@@ -1080,6 +1088,11 @@ function registerTools(server, client) {
                 "test_webhook_flow cannot verify Discord signatures (Ed25519 requires a public key, not a secret)"
               );
             }
+            if (!templateSecret) {
+              throw new Error(
+                `test_webhook_flow cannot verify "${provider}" signatures \u2014 this provider's templates are unsigned`
+              );
+            }
             flow.verifySignature({
               provider,
               secret: templateSecret
@@ -1117,24 +1130,127 @@ 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 have a human run claim_agent with the returned userCode while logged in to webhooks.cc.",
+          "Or set WHK_API_KEY to an existing whcc_ key and use the authenticated tools."
+        ]
+      });
+    })
+  );
+  server.tool(
+    "register_agent",
+    "Self-register for a webhooks.cc API credential via the anonymous auth.md flow. Returns a whcc_ API key that works immediately in a bounded sandbox, plus a short userCode and claimUrl a human uses to bind the key to their account. No authentication required. After registering, set WHK_API_KEY to the returned credential.",
+    {
+      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: "Set WHK_API_KEY to `credential` to use the authenticated tools. Before it is claimed the key can create ephemeral endpoints and read its own captured requests in the sandbox."
+      });
+    })
+  );
+  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);
+    })
+  );
+  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.`
+      });
+    })
+  );
+  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."
+      });
+    })
+  );
+  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."
+      });
+    })
+  );
 }
 
 // src/index.ts
-var VERSION = true ? "1.5.0" : "0.0.0-dev";
+var VERSION = true ? "1.7.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
+  });
   if (!apiKey) {
-    throw new Error("Missing API key. Set WHK_API_KEY environment variable or pass apiKey option.");
+    registerAgentRegistrationTools(server);
+    return server;
   }
-  const client = new WebhooksCC({
+  const client = new WebhooksCC2({
     apiKey,
     webhookUrl: options.webhookUrl ?? process.env.WHK_WEBHOOK_URL,
     baseUrl: options.baseUrl ?? process.env.WHK_BASE_URL
   });
-  const server = new McpServer2({
-    name: "webhooks-cc",
-    version: VERSION
-  });
   registerTools(server, client);
   registerPrompts(server);
   registerResources(server, client);
@@ -1142,6 +1258,7 @@ function createServer(options = {}) {
 }
 export {
   createServer,
+  registerAgentRegistrationTools,
   registerPrompts,
   registerResources,
   registerTools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webhooks-cc/mcp",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "MCP server for webhooks.cc — AI agent integration for webhook testing",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -36,15 +36,15 @@
   },
   "homepage": "https://webhooks.cc",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3",
-    "@webhooks-cc/sdk": "1.7.0"
+    "@webhooks-cc/sdk": "1.9.1"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
+    "@types/node": "^26.2.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.10"
   },
   "scripts": {
     "build": "tsup",