search-audits
Search and filter Descope project audit logs by login IDs, actions, tenants, methods, or geographic locations to monitor authentication events and security activities.
Instructions
Search Descope project audit logs
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| loginIds | No | Filter by specific login IDs | |
| actions | No | Filter by specific action types | |
| excludedActions | No | Actions to exclude from results | |
| tenants | No | Filter by specific tenant IDs | |
| noTenants | No | If true, only show events without tenants | |
| methods | No | Filter by authentication methods | |
| geos | No | Filter by geographic locations | |
| hoursBack | No | Hours to look back (max 720 hours / 30 days) | |
| limit | No | Number of audit logs to fetch (max 10) |
Implementation Reference
- src/descope.ts:59-97 (handler)The asynchronous handler function that executes the 'search-audits' tool. It constructs a time range based on hoursBack, calls descope.management.audit.search with filters, limits results, and returns formatted JSON text or error message.
async ({ loginIds, actions, excludedActions, tenants, noTenants, methods, geos, hoursBack, limit }) => { try { const now = Date.now(); const from = now - (hoursBack * 60 * 60 * 1000); const audits = await descope.management.audit.search({ from, to: now, loginIds, actions, excludedActions, tenants, noTenants, methods, geos, }); // Limit the number of audits to the specified limit const auditResponse = audits.data; const limitedAudits = auditResponse ? auditResponse.slice(0, limit) : []; return { content: [ { type: "text", text: `Audit logs for the last ${hoursBack} hours:\n\n${JSON.stringify(limitedAudits, null, 2)}`, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error fetching audit logs: ${error}`, }, ], }; } }, - src/descope.ts:37-58 (schema)Zod schema defining the input parameters and validation for the 'search-audits' tool, including optional filters, time range, and result limit.
// Optional filters loginIds: z.array(z.string()).optional() .describe("Filter by specific login IDs"), actions: z.array(z.string()).optional() .describe("Filter by specific action types"), excludedActions: z.array(z.string()).optional() .describe("Actions to exclude from results"), tenants: z.array(z.string()).optional() .describe("Filter by specific tenant IDs"), noTenants: z.boolean().optional() .describe("If true, only show events without tenants"), methods: z.array(z.string()).optional() .describe("Filter by authentication methods"), geos: z.array(z.string()).optional() .describe("Filter by geographic locations"), // Time range (defaults to last 24 hours) hoursBack: z.number().min(1).max(24 * 30).default(24) .describe("Hours to look back (max 720 hours / 30 days)"), // Limit (defaults to 5) limit: z.number().min(1).max(10).default(5) .describe("Number of audit logs to fetch (max 10)"), }, - src/descope.ts:33-98 (registration)Registration of the 'search-audits' tool on the MCP server, specifying name, description, input schema, and handler function.
server.tool( "search-audits", "Search Descope project audit logs", { // Optional filters loginIds: z.array(z.string()).optional() .describe("Filter by specific login IDs"), actions: z.array(z.string()).optional() .describe("Filter by specific action types"), excludedActions: z.array(z.string()).optional() .describe("Actions to exclude from results"), tenants: z.array(z.string()).optional() .describe("Filter by specific tenant IDs"), noTenants: z.boolean().optional() .describe("If true, only show events without tenants"), methods: z.array(z.string()).optional() .describe("Filter by authentication methods"), geos: z.array(z.string()).optional() .describe("Filter by geographic locations"), // Time range (defaults to last 24 hours) hoursBack: z.number().min(1).max(24 * 30).default(24) .describe("Hours to look back (max 720 hours / 30 days)"), // Limit (defaults to 5) limit: z.number().min(1).max(10).default(5) .describe("Number of audit logs to fetch (max 10)"), }, async ({ loginIds, actions, excludedActions, tenants, noTenants, methods, geos, hoursBack, limit }) => { try { const now = Date.now(); const from = now - (hoursBack * 60 * 60 * 1000); const audits = await descope.management.audit.search({ from, to: now, loginIds, actions, excludedActions, tenants, noTenants, methods, geos, }); // Limit the number of audits to the specified limit const auditResponse = audits.data; const limitedAudits = auditResponse ? auditResponse.slice(0, limit) : []; return { content: [ { type: "text", text: `Audit logs for the last ${hoursBack} hours:\n\n${JSON.stringify(limitedAudits, null, 2)}`, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error fetching audit logs: ${error}`, }, ], }; } }, );