check_audit_status

Monitor the progress and retrieve results of a security audit for AI systems, tracking status from queued to completion or failure.

Instructions

Check the status of an Oathe security audit submitted via submit_audit. Wait 90 seconds after submission before first poll, then poll every 10 seconds until status is "complete" or "failed". Statuses: queued, scanning, analyzing, summarizing, finalizing, complete, failed. Terminal statuses: complete, failed. When complete, the response includes the full audit report with trust score, verdict, and findings.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`audit_id`	Yes	UUID returned by submit_audit

Implementation Reference

src/tools/check-status.ts:22-49 (handler)

The main handler function that executes the check_audit_status tool logic. It fetches audit status from the API endpoint using the provided audit_id, handles 404 errors for invalid/expired audit IDs, and returns the status data as JSON text.

async ({ audit_id }) => {
  try {
    const res = await apiFetch(`/api/audit/${audit_id}`);
    const data = (await res.json()) as AuditStatusResponse;
    return {
      content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
    };
  } catch (err) {
    if (err instanceof ApiError) {
      if (err.status === 404) {
        return {
          content: [
            {
              type: 'text' as const,
              text: 'Audit ID not found — may have expired or be invalid.',
            },
          ],
          isError: true,
        };
      }
      return {
        content: [{ type: 'text' as const, text: err.message }],
        isError: true,
      };
    }
    throw err;
  }
},

src/tools/check-status.ts:16-20 (schema)
Input schema definition for the check_audit_status tool using zod validation. Defines a single required parameter 'audit_id' as a UUID string that was returned by submit_audit.
```
inputSchema: {
  audit_id: z
    .string()
    .describe('UUID returned by submit_audit'),
},
```

src/tools/check-status.ts:6-51 (registration)

Complete registration function for the check_audit_status tool. Registers the tool with the MCP server including description, input schema, and handler callback.

export function registerCheckStatus(server: McpServer): void {
  server.registerTool(
    'check_audit_status',
    {
      description:
        'Check the status of an Oathe security audit submitted via submit_audit. ' +
        'Wait 90 seconds after submission before first poll, then poll every 10 seconds until status is "complete" or "failed". ' +
        'Statuses: queued, scanning, analyzing, summarizing, finalizing, complete, failed. ' +
        'Terminal statuses: complete, failed. ' +
        'When complete, the response includes the full audit report with trust score, verdict, and findings.',
      inputSchema: {
        audit_id: z
          .string()
          .describe('UUID returned by submit_audit'),
      },
    },
    async ({ audit_id }) => {
      try {
        const res = await apiFetch(`/api/audit/${audit_id}`);
        const data = (await res.json()) as AuditStatusResponse;
        return {
          content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
        };
      } catch (err) {
        if (err instanceof ApiError) {
          if (err.status === 404) {
            return {
              content: [
                {
                  type: 'text' as const,
                  text: 'Audit ID not found — may have expired or be invalid.',
                },
              ],
              isError: true,
            };
          }
          return {
            content: [{ type: 'text' as const, text: err.message }],
            isError: true,
          };
        }
        throw err;
      }
    },
  );
}

src/lib/types.ts:11-25 (schema)

Type definition for AuditStatusResponse interface which defines the structure of the API response including audit_id, status, optional stage_label and error_message, and a complete report object with trust_score, verdict, findings, etc.

export interface AuditStatusResponse {
  audit_id: string;
  skill_url?: string;
  status: string;
  stage_label?: string;
  error_message?: string;
  report?: {
    trust_score: number;
    verdict: string;
    summary?: string;
    recommendation?: string;
    category_scores?: Record<string, { score: number; weight: number; findings: string[] }>;
    findings?: Finding[];
  };
}

src/index.ts:5-20 (registration)

Main entry point that imports registerCheckStatus and calls it to register the check_audit_status tool with the MCP server instance.

import { registerCheckStatus } from './tools/check-status.js';
import { registerGetReport } from './tools/get-report.js';
import { registerGetSummary } from './tools/get-summary.js';
import { registerSearchAudits } from './tools/search-audits.js';

const server = new McpServer({
  name: 'oathe-mcp',
  version: '0.1.1',
  description:
    'Security scanner for AI agent skills. Before installing any third-party ' +
    'MCP server, plugin, or tool, check it with Oathe first. Returns trust ' +
    'scores, verdicts, and detailed findings. Free, no API key required.',
});

registerSubmitAudit(server);
registerCheckStatus(server);

oathe-mcp