Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

refactor(mcp): share common tool annotations (#1258)

mldangelo-oai3246f4717d6c
diff --git a/plugins/codex-security/mcp-app/server.ts b/plugins/codex-security/mcp-app/server.ts
index 1eeea354a..19f9c7a5e 100644
--- a/plugins/codex-security/mcp-app/server.ts
+++ b/plugins/codex-security/mcp-app/server.ts
@@ -1,3 +1,7 @@
+import {
+ readingAnnotations,
+ writingAnnotations,
+} from "./src/server/tool-annotations.js";
import type { JsonObject } from "./src/types.js";
import { isRecord as isJsonObject } from "./src/record.js";
import { execFile } from "node:child_process";
@@ -627,12 +631,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"Check this ChatGPT account's Daybreak access and available Daybreak programs. This check is advisory and never authorizes or blocks a scan. Skip it for Amazon Bedrock scans: it does not check AWS model access or access to local CLI results.",
inputSchema: z.object({}).strict(),
- annotations: {
- readOnlyHint: true,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: readingAnnotations,
_meta: {
...modelActionMeta,
"openai/requestedEntitlements": ["cyber_trusted_access"],
@@ -704,12 +703,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"Headless and CLI only. Start or rejoin a Standard security scan. Do not use for desktop scans, Review changes, Deep Scan, or an existing SDK-owned scan. Use the returned authoritative scanId, scanDir, and handoffClaimToken throughout preflight, reporting, and completion.",
inputSchema: startHeadlessStandardScanSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: modelActionMeta,
},
async ({ targetPath, scope, targetSummary, userContext }, extra) => {
@@ -784,12 +778,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"Start or rejoin a Standard or diff Codex Security scan from its owning conversation. Use the returned authoritative scanId and scanDir. Standard and diff scans save progress checkpoints before their final semantic draft; the workbench writes the unsealed canonical artifacts. Complete the same scan once. Deep Scan uses start_codex_security_deep_scan instead.",
inputSchema: startPromptOnlyScanSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: modelActionMeta,
},
async (
@@ -948,12 +937,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Validate a local target directory and derive its display and Git metadata without saving setup.",
inputSchema: targetInspectionSchema,
- annotations: {
- readOnlyHint: true,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: readingAnnotations,
_meta: appMeta,
},
async ({ targetPath }) => {
@@ -981,12 +965,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Resolve and validate the complete local target, scope, mode, and exact Git change set without saving setup.",
inputSchema: setupInspectionSchema,
- annotations: {
- readOnlyHint: true,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: readingAnnotations,
_meta: appMeta,
},
async ({ targetPath, scope, mode, diffTarget }) => {
@@ -1019,12 +998,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Validate and save bounded target, scope, mode, and optional context selections.",
inputSchema: submissionSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: appMeta,
},
async ({
@@ -1094,12 +1068,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"Run or rejoin independent Standard security scans and semantically merge their validated findings. Pass scanId and its handoffClaimToken to resume, or targetPath to start headlessly. The call blocks until the aggregate draft is ready, fails, or is canceled. On success, use the returned scanId and scanDir; manifestPath identifies the canonical parent scan-manifest.json. Call complete_codex_security_scan once.",
inputSchema: startDeepScanSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: modelActionMeta,
},
async (
@@ -1356,12 +1325,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Read plugin-owned scan state for native Security monitoring without claiming a pending Codex handoff.",
inputSchema: scanReadSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: appMeta,
},
async ({ scanId, occurrenceId }) =>
@@ -1383,12 +1347,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Read persisted plugin-owned scan summaries for native Security navigation.",
inputSchema: scanListSchema,
- annotations: {
- readOnlyHint: true,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: readingAnnotations,
_meta: appMeta,
},
async ({ limit, mode, offset, query, status, targetId }) =>
@@ -1413,12 +1372,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Read the latest plugin-owned finding occurrence for each stable repository target and finding identity.",
inputSchema: globalFindingsPageSchema,
- annotations: {
- readOnlyHint: true,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: readingAnnotations,
_meta: appMeta,
},
async ({ limit, offset, query, severity, status, targetId }) =>
@@ -1443,12 +1397,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Read plugin-owned repository summaries and their latest scan state.",
inputSchema: repositoryListSchema,
- annotations: {
- readOnlyHint: true,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: readingAnnotations,
_meta: appMeta,
},
async ({ limit, offset, query, status, targetId }) =>
@@ -1472,12 +1421,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"Load the authoritative target, mode, optional user context, artifact directory, live progress, and optional selected finding for a launched scan. Validated legacy finding details may be migrated.",
inputSchema: scanContextSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: modelActionMeta,
},
async ({ scanId, occurrenceId, handoffClaimToken }, extra) => {
@@ -1559,12 +1503,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"Replace the context for a running scan. The next phase uses the new value; workers in the current phase keep their original context.",
inputSchema: scanContextUpdateSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: modelActionMeta,
},
async ({ scanId, userContext, handoffClaimToken }, extra) => {
@@ -1590,12 +1529,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Replace the context for the running scan attached to this workspace.",
inputSchema: appScanContextUpdateSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: appMeta,
},
async ({ scanId, userContext }) => {
@@ -1623,12 +1557,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"Record a meaningful live scan phase or coverage milestone in the Codex Security workbench.",
inputSchema: progressSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: modelActionMeta,
},
async (
@@ -1743,12 +1672,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"Finalization only: validate and seal already-authored scan-manifest.json, findings.json, and coverage.json, generate report.md, index findings, and mark the scan complete. For an app-backed running scan, scan-manifest.json is an unsealed draft and must omit scan.sealedAt and scan.artifacts; this tool supplies the exact workbench timestamps, seal, artifact digests, and derived finding identities. Call only after those canonical files exist; this tool does not create missing artifacts or run skipped phases. If it fails, surface the exact error and stop the current response without retrying completion or returning a final, no-findings, structured, or benchmark response.",
inputSchema: completeScanSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: modelActionMeta,
},
async ({ scanId, handoffClaimToken }) => {
@@ -1807,12 +1731,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Persist a completed finding's local open or closed triage status. Closed findings require one bounded close reason; reopening clears it.",
inputSchema: findingTriageSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: appMeta,
},
async ({ occurrenceId, status, closeReason, note }) =>
@@ -1837,12 +1756,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Queue a completed finding for Codex remediation before sending the host a generate or regenerate request.",
inputSchema: findingRemediationRequestSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: appMeta,
},
async ({ occurrenceId, requestId, actionToken }) =>
@@ -1867,12 +1781,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Durably claim an apply or verify handoff before asking Codex to perform the local working-tree operation.",
inputSchema: findingRemediationActionRequestSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: appMeta,
},
async ({ occurrenceId, requestId, expectedVersion, action, actionToken }) =>
@@ -1901,12 +1810,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Atomically take ownership of an unowned or stale remediation host request before resending it.",
inputSchema: findingRemediationClaimSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: appMeta,
},
async ({ occurrenceId, requestId, actionToken }) =>
@@ -1931,12 +1835,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Release a locally owned remediation host request after message delivery fails.",
inputSchema: findingRemediationClaimSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: appMeta,
},
async ({ occurrenceId, requestId, actionToken }) =>
@@ -1991,12 +1890,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Seal host-message delivery ownership before Codex starts a remediation worker.",
inputSchema: findingRemediationClaimSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: appMeta,
},
async ({ occurrenceId, requestId, actionToken }) =>
@@ -2070,12 +1964,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Export retained local findings as JSON, SARIF, or CSV, or the saved threat model as Markdown without running another analysis. Findings require completed or preserved stopped results; threat models may be provisional. Defaults to findings in CSV, or Markdown when artifact is threat-model. Exported copies remain in the scan's exports directory, except canonical findings JSON.",
inputSchema: findingsExportSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: appMeta,
},
async ({ scanId, artifact, format }) =>
@@ -2101,12 +1990,7 @@ export function createCodexSecurityServer(): McpServer {
description:
"App-only. Load one bounded page of indexed findings for a completed local scan, migrating validated legacy finding details when needed.",
inputSchema: findingsPageSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: appMeta,
},
async ({ limit, offset, query, scanId, severity, status }) =>
diff --git a/plugins/codex-security/mcp-app/src/server/compact-artifact-tools.ts b/plugins/codex-security/mcp-app/src/server/compact-artifact-tools.ts
index 4e1902a8f..796aa9a3a 100644
--- a/plugins/codex-security/mcp-app/src/server/compact-artifact-tools.ts
+++ b/plugins/codex-security/mcp-app/src/server/compact-artifact-tools.ts
@@ -1,3 +1,4 @@
+import { readingAnnotations, writingAnnotations } from "./tool-annotations.js";
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import type { ZodType } from "zod/v4";
import type { JsonObject as JsonRecord } from "../types.js";
@@ -66,20 +67,6 @@ const modelOnlyMeta = {
ui: { visibility: ["model"] as const },
};
-const readingAnnotations = {
- readOnlyHint: true,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
-};
-
-const writingAnnotations = {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
-};
-
/** Prepare diff inventories and read existing diff or Deep inventories. */
export function registerReviewItemTools(
server: McpServer,
diff --git a/plugins/codex-security/mcp-app/src/server/handoff-tools.ts b/plugins/codex-security/mcp-app/src/server/handoff-tools.ts
index 0a68592d0..ed9667aaa 100644
--- a/plugins/codex-security/mcp-app/src/server/handoff-tools.ts
+++ b/plugins/codex-security/mcp-app/src/server/handoff-tools.ts
@@ -1,3 +1,4 @@
+import { writingAnnotations } from "./tool-annotations.js";
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import * as z from "zod/v4";
@@ -50,12 +51,7 @@ export function registerScanHandoffTools(
description:
"App-only. Record that the launched scan instructions were delivered to Codex.",
inputSchema: handoffClaimSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: appMeta,
},
async ({ scanId, claimToken }) => {
@@ -77,12 +73,7 @@ export function registerScanHandoffTools(
description:
"App-only. Durably claim scan handoff delivery before sending continuation instructions to Codex.",
inputSchema: handoffTakeoverSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: appMeta,
},
async ({ scanId, claimToken, takeOverStale }) => {
@@ -105,12 +96,7 @@ export function registerScanHandoffTools(
description:
"App-only. Release a failed scan handoff delivery claim so the app can retry it.",
inputSchema: handoffClaimSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: appMeta,
},
async ({ scanId, claimToken }) => {
@@ -132,12 +118,7 @@ export function registerScanHandoffTools(
description:
"App-only. Persist the normal local Codex thread created for a claimed scan handoff.",
inputSchema: scanContinuationThreadSchema,
- annotations: {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
- },
+ annotations: writingAnnotations,
_meta: appMeta,
},
async ({ scanId, claimToken, threadId }) => {
diff --git a/plugins/codex-security/mcp-app/src/server/tool-annotations.ts b/plugins/codex-security/mcp-app/src/server/tool-annotations.ts
new file mode 100644
index 000000000..0253fdced
--- /dev/null
+++ b/plugins/codex-security/mcp-app/src/server/tool-annotations.ts
@@ -0,0 +1,13 @@
+export const readingAnnotations = {
+ readOnlyHint: true,
+ destructiveHint: false,
+ idempotentHint: true,
+ openWorldHint: false,
+};
+
+export const writingAnnotations = {
+ readOnlyHint: false,
+ destructiveHint: false,
+ idempotentHint: true,
+ openWorldHint: false,
+};