OpenAPI-to-MCP Safety Checklist

OpenAPI-to-MCP tooling can make APIs reachable by agents quickly. The hard part is making those actions safe, inspectable, permissioned, and recoverable. Use this checklist before publishing a generated MCP tool, running a customer demo, or positioning Valkyr against SDK/interface tooling.

Preflight

Area	Required check	Fail-closed behavior
Auth model	Confirm whether each operation uses OAuth, bearer token, session auth, service account auth, or anonymous access.	Do not publish a tool when the required credential type is unknown or mismatched.
RBAC/ACL	Verify that generated ThorAPI authorization remains the source of truth for reads, writes, search, export, and hydration.	Block the tool rather than filtering private records after retrieval.
$ref resolution	Resolve local and remote references through an allowlisted, deterministic path.	Reject unresolved, remote, cyclic, or untrusted references.
Request bodies	Preserve required fields, content types, enums, object shapes, and validation rules.	Reject ambiguous request schemas instead of inventing permissive inputs.
Tool naming	Deduplicate names and avoid collisions across tags, operations, versions, and tenants.	Refuse publish when two operations map to the same tool identity.
Rate limits	Apply per-user, per-org, and per-tool quotas where action cost or blast radius is meaningful.	Return a recoverable quota error with no partial mutation.
Runtime validation	Validate payloads before execution and normalize only documented aliases.	Do not pass unknown fields into privileged operations.
Audit evidence	Emit actor, org, operation, trace, input summary, decision, and result status without logging secrets.	Block high-consequence actions that cannot be audited.
Memory/context	Attach GrayMatter context only from permitted scopes and record retrieval provenance.	Do not use stale or unauthorized memory to fill action inputs.

Auth and Credential Rules

• Never convert an authenticated API route into an anonymous MCP tool.
• Do not downgrade OAuth scopes to generic bearer-token access.
• Keep service-account tools separate from end-user delegated tools.
• Hide secrets in logs, traces, receipts, and error responses.
• Require explicit approval mode for infrastructure, billing, deletion, export, or broad-write tools.

Schema and Tool Shape Rules

• Keep OpenAPI as the source of truth.
• Treat missing request bodies, untyped object, and broad additionalProperties as review triggers.
• Preserve enum values and validation constraints in the MCP tool schema.
• Include idempotency keys for repeatable mutations where supported.
• Prefer generated ThorAPI paths over bespoke controller aliases.

Runtime Guardrails

• Fail closed on unknown operation security.
• Fail closed on unresolved references.
• Fail closed on missing tenant, principal, workspace, or organization context.
• Fail closed when the generated ACL guard cannot run.
• Return user-safe recovery copy instead of stack traces or provider secrets.

Demo Readiness

Before a live demo, prepare:

• One read-only tool with clear output and no private-data risk.
• One bounded mutation with idempotency and rollback notes.
• A visible audit or receipt trail.
• A GrayMatter retrieval example with permitted context and provenance.
• A fallback route if hosted isolated instances are not demo-stable.

Related Pages

Use the Support & Governance sidebar for Stainless transition coverage, the GrayMatter agent-memory quickstart, and MCP agent-action audit material.