@webhooks-cc/mcp 1.5.0 → 1.6.0

package/dist/bin/mcp.js

@@ -1103,24 +1103,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.6.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
@@ -1124,24 +1125,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.6.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 +1254,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";
@@ -255,6 +255,7 @@ import {
   UnauthorizedError,
   VERIFY_PROVIDERS,
   verifySignature,
+  WebhooksCC,
   WebhooksCCError
 } from "@webhooks-cc/sdk";
 var MAX_BODY_SIZE = 32768;
@@ -1117,24 +1118,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.6.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 +1246,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.6.0",
   "description": "MCP server for webhooks.cc — AI agent integration for webhook testing",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -38,7 +38,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3",
-    "@webhooks-cc/sdk": "1.7.0"
+    "@webhooks-cc/sdk": "1.8.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",