Function registerEventTools

mcp/src/tools/events.ts:15–93

(server: McpServer, client: McpClient)

// LLM cannot list events for other accounts.

export function registerEventTools(server: McpServer, client: McpClient): void {
  server.registerTool(
    "list_events",
    {
      title: "List webhook events",
      annotations: { readOnlyHint: true },
      description:
        "List the durable webhook event log in reverse-chronological order. Useful for reconciliation (\"did our webhook receiver see this event?\") and for debugging delivery state. Events past the 30-day retention boundary are not returned. **Cursor-paginated:** returns one page in `events` plus a `next_cursor` when more remain — pass it back as `cursor` to walk further back. Returns each event's `data` payload plus a `delivery_status` summary of how many subscribers have received it.",
      inputSchema: strictInputSchema({
        type: z
          .string()
          .optional()
          .describe(
            "Exact event type filter. Valid values: `email.received`, `email.sent`, `email.pending_review`, `email.review_approved`, `email.review_rejected`, `email.blocked`, `email.delivered`, `email.bounced`, `email.complained`, `email.flagged`, `domain.sending_verified`, `domain.sending_failed`, `domain.suppression_added`.",
          ),
        agent_id: z.string().optional(),
        conversation_id: z.string().optional(),
        message_id: z.string().optional(),
        since: z
          .string()
          .optional()
          .describe("RFC3339 timestamp; returns events with `created_at >= since`."),
        until: z.string().optional().describe("RFC3339; returns events with `created_at < until`."),
        ...paginationInput,
      }),
    },
    async (args) =>
      runTool(async () => {
        const page = await client.listEvents({
          ...(args.type !== undefined ? { type: args.type } : {}),
          ...(args.agent_id !== undefined ? { agentId: args.agent_id } : {}),
          ...(args.conversation_id !== undefined
            ? { conversationId: args.conversation_id }
            : {}),
          ...(args.message_id !== undefined ? { messageId: args.message_id } : {}),
          ...(args.since !== undefined ? { since: args.since } : {}),
          ...(args.until !== undefined ? { until: args.until } : {}),
          ...(args.cursor !== undefined ? { cursor: args.cursor } : {}),
          ...(args.limit !== undefined ? { limit: args.limit } : {}),
        });
        return { events: page.items, ...(page.next_cursor ? { next_cursor: page.next_cursor } : {}) };
      }),
  );

  server.registerTool(
    "get_event",
    {
      title: "Get one webhook event",
      annotations: { readOnlyHint: true },
      description:
        "Fetch a single event by id. The response includes the full envelope payload AND a `delivery_status` block showing how many of the matched webhooks have delivered/pending/failed. Use this to triage \"did this specific event reach my receiver?\" Returns an error with status 410 if the event has passed the 30-day retention boundary (replay is no longer possible).",
      inputSchema: strictInputSchema({
        event_id: z.string().describe("Stable event id (evt_<32hex>)."),
      }),
    },
    async (args) => runTool(() => client.getEvent(args.event_id)),
  );