Configuration

The server reads all runtime configuration from environment variables.

Required Variables

Variable	Required	Description
VCFA_HOST	Yes	VCF Automation hostname or host:port, for example vcfa.example.com. A value carrying a URL scheme is rejected at startup.
VCFA_USERNAME	Yes	Username without organization, for example admin.
VCFA_ORGANIZATION	Yes	Organization name (the tenant URL slug, not the display name), or system for provider/system administrator logins. In vra8 mode, the vIDM domain shown on the Workspace ONE login page, for example System Domain.
VCFA_PASSWORD	Yes	Password for the VCF Cloud API session, or the vIDM password used for the vRA 8 login when VCFA_TARGET_PLATFORM=vra8.

On the default vcfa platform, the server authenticates by sending Basic Auth as {VCFA_USERNAME}@{VCFA_ORGANIZATION}:{VCFA_PASSWORD} to the VCF Cloud API session endpoint. Tenant logins use:

https://{VCFA_HOST}/cloudapi/1.0.0/sessions

When VCFA_ORGANIZATION is system (case-insensitive), the login is routed to the dedicated provider endpoint instead — the tenant endpoint rejects provider accounts with 401. A provider session cannot read the tenant-scoped Automation services (catalog, deployment, blueprint, event-broker, project) — vRO works, but those tools answer 403 or 500; use a tenant organization for them. The event-broker tools are the exception a tenant organization does not fix: on VCF Automation 9.1 both GET /topics and GET /subscriptions answer 403 on a tenant session too, because the account lacks the role the service requires (VCFO-099).

The provider session request:

https://{VCFA_HOST}/cloudapi/1.0.0/sessions/provider

It uses the returned bearer token for later VCF Automation, Service Broker, Cloud Assembly, and vRO API calls.

VCF Cloud API Version Negotiation

VCF Automation 9.1 introduces API version 9.1.0 alongside 9.0.0. Before authenticating, the server probes the unauthenticated discovery document at https://{VCFA_HOST}/api/versions and selects the newest API version it knows (9.1.0 preferred, then 9.0.0) for the session request. If the probe fails or advertises no known version, the server falls back to 9.0.0, which 9.1 servers still accept. Set VCFA_TARGET_PLATFORM to vcfa9.1 or vcfa9.0 to pin the version explicitly and skip the probe.

For vRA/vRO 8.12+ compatibility, set VCFA_TARGET_PLATFORM=vra8. vRA-embedded vRO rejects Basic auth on /vco/api, so in that mode the server skips the VCF Cloud API session endpoint and the GET /api/versions probe and instead runs the vRA 8 bearer-token flow: it posts VCFA_USERNAME, VCFA_PASSWORD, and VCFA_ORGANIZATION as the vIDM domain to POST /csp/gateway/am/api/login?access_token, exchanges the returned refresh token at POST /iaas/api/login, and sends the resulting token as Authorization: Bearer on every /vco/api request. A 401 from vRO — or a 403 that carries a WWW-Authenticate challenge — renews the token and retries the request once: the cached refresh token is exchanged again, and the full CSP login runs only if that token is rejected, so a renewal does not re-send the password. A 403 without a challenge is surfaced directly as an authorization result. Neither login request is allowed to follow a redirect, because the request body carries the credentials. VCFO-068 verified this mode against a vRA 8.18 lab (vRO 8.18.1). What it supports:

Surface	vra8 mode
vRO /vco/api reads and writes	Supported — create/update/delete of workflows, actions, and configuration elements, multipart artifact imports, package build/export, workflow execution and logs
Automation-service reads (catalog items, deployments, templates, projects, subscriptions, event topics)	Supported — same page envelope and object shapes as VCFA 9.x, with no apiVersion pin required
Blueprint-service and event-broker writes (create-template, delete-template, subscription create/update/delete)	Supported — verified against a vRA 8.18 lab with a disposable DRAFT template and a disposable disabled subscription, neither of which provisions infrastructure
Catalog-service and deployment-service writes (create-deployment, delete-deployment, run-deployment-action)	Supported — verified against a vRA 8.18 lab under VCFO-088 once it held a released catalog item: a disposable deployment was requested, powered off and on, and deleted through the real tool handlers, each expected* guard refused a mismatch first, and the environment was returned to its starting count. Each path still provisions, alters or destroys real infrastructure, so the confirm gate and the target guards apply exactly as on VCF Automation
export-configuration-file	Unsupported — vRA 8 serves a configuration element as JSON only and answers the artifact request with 406. Use get-configuration, or add it to the project package and export that. prepare-artifact-promotion reports a configuration backup as skipped for the same reason and still returns its report. The same 406 was later observed on vRO 9.1, standalone and appliance-embedded alike, while workflow, action and package exports succeed on those same hosts — so the refusal is specific to configuration elements, not to vRA 8; a 406 from any platform now reports this guidance instead of the server's HTML body
import-configuration-file	Unverified but not guarded — the endpoint is reachable and the multipart transport is proven, but no genuine container has been round-tripped and none can currently be produced: no vRO tested, on either platform, exports a single configuration element as a .vsoconf

Subscription writes differ from the vcfa path in this mode: vRA 8 requires the client to choose the subscription id, answers the create 201 with an empty body, and serves neither PUT nor PATCH on /subscriptions/{id}. create-subscription therefore generates a UUID and re-reads the element, and update-subscription lays the caller's changes over the live element and upserts the whole body with a POST. Because that upsert replaces the element, the body starts from the live one and strips only server-owned fields, so the element's own type and anything the client does not model carry forward instead of being cleared; an element with no eventTopicId is refused before the write, since vRA 8 requires one on the upsert. vRA 8 also serves system subscriptions with no name, which render as (unnamed).

One configuration request body still differs in this mode: PUT /configurations/{id} must carry the element name. The attribute key used to differ too — vRA 8 answers 400 for the singular attribute and for a body carrying both — but every platform now sends the plural attributes, which VCFA 9.1 accepts on create and update alike. That PUT replaces the element on both platforms, so update-configuration reads the live element once and carries an omitted name and description forward (see the tools reference for the attribute rules). Catalog items and deployments were both empty in the lab that first verified this mode, so their item shapes stayed unconfirmed until VCFO-088 read a released item and provisioned, inspected, powered off and on, and destroyed a deployment on vRA 8.18. The catalog item, deployment and deployment-action shapes match VCF Automation 9.1 key for key, with two differences: the vRA 8 catalog item serves neither isRequestable, sourceProjectId nor global, and its catalog service caps a list page at 20 items whatever size is requested (the pager follows last and totalPages, so nothing is missed). The DeploymentRequest that a day-2 submission and a delete answer with has been observed on vRA 8.18 only, since no 9.1 round has submitted an action or recorded the delete body. Both renderers still fall back to (unnamed) rather than trusting a name to be present.

External vRO Appliance

When an organization's vRO runs on its own appliance rather than embedded in the VCF Automation appliance, set VCFA_VRO_HOST to that appliance's host[:port]. Only the vRO API base moves:

https://{VCFA_VRO_HOST}/vco/api

Everything else stays on VCFA_HOST: the session endpoints above, the GET /api/versions probe, the vRA 8 CSP and IaaS logins in vra8 mode, and the catalog, deployment, blueprint, project, and event-broker services. No second login runs — the token the Automation appliance issues is sent to the external vRO as-is, which VCFO-081 verified live on VCF Automation 9.1 with an external vRO 9.1. The vra8 topology is wired the same way but has not been live-verified against an external vRO.

An external vRO cannot stand in as VCFA_HOST: it answers the session endpoint and /api/versions with a redirect to its own UI, so the login fails. Conversely, leaving VCFA_VRO_HOST unset in such an environment sends /vco/api to the Automation appliance's embedded orchestrator, which refuses a tenant with a 403 and an HTML page rather than a vRO JSON error — that error carries a hint pointing at this variable.

While the two hosts differ, every request log line and every vRO API error names the host it went to (GET /workflows on vro.example.com, export workflow on vro.example.com), a transport failure names it too (Request to vro.example.com failed: ENOTFOUND), and a redirect answer to a JSON API request is surfaced rather than followed, naming its target. Unset, blank, or equal to VCFA_HOST, the variable changes nothing. The value must be a hostname or host:port: a scheme, a path, or anything that cannot serve as the host of a URL is rejected at startup.

Optional Variables

Variable	Description
VCFA_TARGET_PLATFORM	Target platform mode: vcfa (default, auto-negotiates the VCF Cloud API version), vcfa9.1/vcfa9.0 (pin the VCF Cloud API version, skipping the GET /api/versions probe), or vra8 (vRA/vRO 8.12+, vIDM bearer-token auth).
VCFA_VRO_HOST	Optional host[:port] of an external vRO appliance. Only the vRO /vco/api requests go there; the login, the GET /api/versions probe, and the Automation services stay on VCFA_HOST, and the token issued there is reused as-is. Leave unset for the embedded vRO. Works with vcfa, vcfa9.x, and vra8. See External vRO Appliance.
VCFA_IGNORE_TLS	Set to true to disable TLS certificate verification for this server's requests to the VCFA host and, when VCFA_VRO_HOST is set, the vRO host (lab environments only).
VCFA_ARTIFACT_DIR	Root directory for local artifact import/export files. Defaults to artifacts/ in the MCP server process working directory, typically the open project.
VCFA_PACKAGE_DIR	Override the package artifact directory.
VCFA_RESOURCE_DIR	Override the resource element artifact directory.
VCFA_WORKFLOW_DIR	Override the workflow artifact directory.
VCFA_EXECUTION_LOG_DIR	Override the workflow execution log export directory.
VCFA_ACTION_DIR	Override the action artifact directory.
VCFA_CONFIGURATION_DIR	Override the configuration artifact directory.
VCFA_CONTEXT_DIR	Override the persisted context snapshot directory. If unset, context snapshots prefer the MCP client's current workspace root at artifacts/context/, falling back to VCFA_ARTIFACT_DIR/context.
VCFA_PROJECT_PACKAGE_NAME	Stable fully-qualified package name reused by package-first workflows, for example com.example.project.
VCFA_PROJECT_PACKAGE_DESCRIPTION	Optional description used if the exact project package is explicitly created.

Artifact Directories

Artifacts are organized into typed subdirectories under VCFA_ARTIFACT_DIR:

VCFA_ARTIFACT_DIR/
  actions/
  configurations/
  context/
  execution-logs/
  packages/
  resources/
  workflows/

Use the specific directory overrides only when you need different storage locations per artifact type.

TLS Warning

VCFA_IGNORE_TLS=true disables TLS certificate verification only for this server's requests to the configured VCFA host — and, when VCFA_VRO_HOST is set, the vRO host — using a dedicated HTTPS agent. It does not set NODE_TLS_REJECT_UNAUTHORIZED or affect any other HTTPS traffic in the process. Use it only for lab or test environments where the risk is understood.