Safety

Tools fall into three categories:

• Read-only discovery (readOnlyHint: true): list, get, preflight, and diff tools. They do not write local files or mutate live VCFA/vRO state. get-workflow-execution-logs is also read-only by default; it only writes a local file when the optional fileName parameter is provided.
• Local artifact writes (readOnlyHint: false, no confirm required): export, scaffold, and snapshot tools — for example export-workflow-file, export-action-file, export-configuration-file, export-resource-element, export-package, export-project-package, scaffold-workflow-file, collect-context-snapshot, and prepare-artifact-promotion. These write files under configured artifact directories and default overwrite to false. They do not mutate live VCFA/vRO state.
• Live VCFA/vRO mutations (readOnlyHint: false, confirm: true required): create, update, import, delete, run, and deployment day-2 action tools. Treat every live write operation as an environment change. Tools that overwrite or delete live state — import, update, run, and delete tools, plus rebuild-project-package — additionally set destructiveHint: true so hosts can require heightened approval; additive creates and add-*-to-project-package tools do not. create-deployment is the single exception among the creates: it provisions real infrastructure, and delete-deployment is a destructive day-2 operation rather than an undo, so it carries destructiveHint: true too (VCFO-084).

Confirmation Required

These operations should be performed only after explicit user confirmation:

• creating or updating live workflows, actions, configurations, templates, subscriptions, deployments, or packages
• running workflows, because workflow execution may change the target environment
• importing workflows, actions, configurations, packages, or resource elements
• deleting workflows, actions, configurations, resource elements, packages, templates, deployments, or subscriptions — and separately, passing force: true to a delete, which skips vRO's own reference check rather than establishing that nothing references the element
• running deployment day-2 actions

Two-Phase Target Confirmation

For high-risk live mutations, prefer a two-phase flow:

1. Discover the live target with the matching list/get tool or prepare the artifact with prepare-artifact-promotion.
2. Confirm the exact target and impact with the user.
3. Pass confirm: true plus supported expected target fields such as expectedName, expectedWorkflowName, expectedInputNames, expectedCategoryId, expectedCategoryName, expectedPackageName, expectedDeploymentName, expectedActionName, expectedCatalogItemName, expectedProjectName, expectedEventTopicId, or expectedRunnableId.
4. Verify with a read-only get/list call after mutation.

Expected fields are optional for backward compatibility. When provided, the handler fetches current live metadata before the mutation and refuses if any expected value does not match. Direct imports remain available for narrow validation and one-off tests, but package-first promotion with preflight, diff, backup, expected fields, and post-change verification is safer for reusable content.

Artifact Path Safety

Artifact file tools require plain file names under configured artifact directories. They reject:

• absolute paths
• path separators
• traversal such as ../
• unsafe symlink import sources
• unsafe symlink export targets
• existing export targets unless overwrite: true

Export and snapshot tools default overwrite to false. Pass overwrite: true explicitly when replacing an existing local artifact.

Secrets

Configuration values and workflow/action scripts may contain sensitive information. When summarizing output:

• avoid printing passwords, API tokens, and private keys
• redact sensitive configuration attribute values
• redact secure-typed workflow execution output parameters, which run-workflow-and-wait and get-workflow-execution withhold as [redacted]
• prefer names, types, IDs, and descriptions over raw values

Withholding needs a signal. A configuration attribute and a workflow execution output both carry a declared type, so both are withheld on it — and on the type key their value arrives wrapped in, which catches a value a permissive type says nothing about. A secret inside an untyped composite value has neither signal. Neither do execution log lines or the exception text of a failed workflow, which get-workflow-execution-logs and the failure diagnostics serve verbatim: keep secrets out of what a workflow logs and throws rather than relying on the server to filter them.

API error messages are sanitized before being surfaced to MCP callers. Only safe diagnostic fields — HTTP status, endpoint, message, statusCode, code, error, and errors — are included. Raw response bodies are never passed through verbatim, which prevents vRO error responses from echoing sensitive request content such as credentials or tokens.

Token Refresh

If a request receives a 401 response, the server invalidates the token that request used, re-authenticates, and retries the request exactly once. A 403 is not retried on the default vcfa platform — it is an authorization result there, and repeating the login cannot change it — nor in vra8 mode unless it carries a WWW-Authenticate challenge (both rules are spelled out below). Only that token is invalidated: a 401 whose token a concurrent request has already replaced reuses the fresh one instead of forcing another login. This covers JSON API calls, binary exports, and multipart uploads. A second consecutive failure after re-authentication is surfaced as an error without further retry.

On the default VCFA platform re-authentication repeats the Cloud API session login. In vra8 mode it exchanges the cached refresh token at /iaas/api/login and repeats the full vIDM CSP login only when that refresh token is rejected, so renewing a token does not re-send the password. A 403 in vra8 mode is retried only when it carries a WWW-Authenticate challenge: an expired vRA 8 token answers with 401, while a 403 from /vco/api means the vIDM user lacks the vRO permission, which no amount of re-authentication changes. On the default VCFA platform a 403 is never retried. Measured against a VCF Automation 9.1 appliance, an unusable session there answers 401 — a revoked one with The token is not valid or revoked., an absent or malformed token likewise, on /vco/api and on all five Automation services — so a 403 is always a denial. The WWW-Authenticate challenge is deliberately not consulted on that platform: project-service sends one on a 403 that is a genuine denial, while /vco/api and the catalog, deployment and blueprint services omit it even on a 401. Neither vra8 login request follows redirects — the request body carries the credentials, and a 307/308 would forward it to the redirect target — so a redirect is reported as a login failure naming that host.

Destructive Operations

Before deletion, confirm:

• object type
• object ID
• display name
• project/category/package context
• expected impact
• whether force: true is being passed, and why

create-deployment belongs in this list even though it creates rather than removes: it is the one tool in the surface that provisions real infrastructure, it is annotated destructive for that reason, and both of its required arguments are opaque UUIDs that nothing else in the call identifies. Pass expectedCatalogItemName and expectedProjectName so the handler verifies the target against live metadata before submitting the request.

force on delete-workflow, delete-action, and delete-configuration sends vRO's own ?force=true, which skips the reference check instead of proving the element is unreferenced — so it is a second step, not a first. A 409 reporting an element as in use right after delete-package is usually a transient release race that clears in a couple of seconds: retry the plain delete first, and reach for force only if the conflict persists and the references are understood. Confirm the impact with the user before setting it, since the unconfirmed prompt states it for exactly that reason.

For subscriptions, disabling is often safer than deleting during testing.

Discovery Guardrail

Do not invent environment-specific values. If discovery does not return a required category, action, workflow, project, template, parameter, return type, or schema detail, stop and report the missing fact.

Live Validation

Keep local repository validation separate from live VCFA validation. npm run validate should not contact VCFA.

Use the live smoke-test checklist when validating the MCP server against a real sandbox or disposable environment. Live smoke checks may use read-only list/get tools, harmless workflow execution, local artifact exports, and controlled package-first validation. Imports, deletes, deployment day-2 actions, subscription changes, template creation, and package promotion require explicit confirmation and disposable test assets.