harness-mcp-v2 3.2.24 → 3.2.26

package/README.md

@@ -2,7 +2,7 @@
 
 [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fharness%2Fmcp-server.svg)](https://mcptoplist.com/server/glama%2Fharness%2Fmcp-server)
 
-An MCP (Model Context Protocol) server that gives AI agents full access to the Harness.io platform through 11 consolidated tools and 243 resource types.
+An MCP (Model Context Protocol) server that gives AI agents full access to the Harness.io platform through 11 consolidated tools and 245 resource types.
 
 ## Why Use This MCP Server
 
@@ -10,8 +10,8 @@ Most MCP servers map one tool per API endpoint. For a platform as broad as Harne
 
 This server is built differently:
 
-- **11 tools, 243 resource types.** A registry-based dispatch system routes `harness_list`, `harness_get`, `harness_create`, etc. to any Harness resource — pipelines, services, environments, orgs, projects, feature flags, cost data, and more. The LLM picks from 11 tools instead of hundreds.
-- **Full platform coverage.** 40 default toolsets spanning CI/CD, GitOps, Feature Flags, Cloud Cost Management, Security Testing, Chaos Engineering, Database DevOps, Internal Developer Portal, Software Supply Chain, Infrastructure as Code Management, Release Management, Governance, Service Overrides, Knowledge Graph, and more. Opt-in Ansible coverage is available when you need inventory and playbook data.
+- **11 tools, 245 resource types.** A registry-based dispatch system routes `harness_list`, `harness_get`, `harness_create`, etc. to any Harness resource — pipelines, services, environments, orgs, projects, feature flags, cost data, and more. The LLM picks from 11 tools instead of hundreds.
+- **Full platform coverage.** 41 default toolsets spanning CI/CD, GitOps, Feature Flags, Cloud Cost Management, Security Testing, Chaos Engineering, Database DevOps, Internal Developer Portal, Software Supply Chain, Infrastructure as Code Management, Release Management, Governance, Service Overrides, Knowledge Graph, and more. Opt-in Ansible coverage is available when you need inventory and playbook data.
 - **Multi-project workflows out of the box.** Agents discover organizations and projects dynamically — no hardcoded env vars needed. Ask "show failed executions across all projects" and the agent can navigate the full account hierarchy.
 - **35 prompt templates.** Pre-built prompts for common workflows: build & deploy apps end-to-end, debug failed pipelines, review DORA metrics, triage vulnerabilities, optimize cloud costs, audit access control, plan feature flag rollouts, review pull requests, approve pending pipelines, and more.
 - **Works everywhere.** Stdio transport for local clients (Claude Desktop, Cursor, Devin Desktop), HTTP transport for remote/shared deployments, Docker and Kubernetes ready.
@@ -123,14 +123,17 @@ When running in HTTP mode, the server exposes:
 | `/mcp`    | `DELETE`  | Terminate an active MCP session                                  |
 | `/mcp`    | `OPTIONS` | CORS preflight                                                   |
 | `/health` | `GET`     | Health check — returns `{ "status": "ok", "sessions": <count> }` |
+| `/.well-known/oauth-protected-resource` | `GET` | RFC 9728 metadata when `HARNESS_MCP_MODE=oauth` |
+| `/.well-known/oauth-protected-resource/mcp` | `GET` | Path-aware RFC 9728 metadata for the default `/mcp` resource |
 
 
 The HTTP transport runs in **session-based mode**. A new MCP session is created on `initialize`, the server returns an `mcp-session-id` header, and subsequent requests for that session must include the same header.
 
 Operational constraints in HTTP mode:
 
-- Set `HARNESS_MCP_AUTH_TOKEN` for any shared or remotely reachable deployment. When set, every `POST`, `GET`, and `DELETE` request to `/mcp` must include `Authorization: Bearer <token>`.
-- Non-loopback binds require `HARNESS_MCP_AUTH_TOKEN` by default. To run unauthenticated on a non-loopback interface anyway, set `HARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP=true` explicitly.
+- Set `HARNESS_MCP_AUTH_TOKEN` for shared or remotely reachable single-user and multi-user deployments. When set, every `POST`, `GET`, and `DELETE` request to `/mcp` must include `Authorization: Bearer <token>`.
+- OAuth mode accepts HarnessID access tokens instead of `HARNESS_MCP_AUTH_TOKEN` and can bind to a non-loopback address without the unauthenticated opt-out.
+- Non-loopback single-user and multi-user binds require `HARNESS_MCP_AUTH_TOKEN` by default. To run unauthenticated on a non-loopback interface anyway, set `HARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP=true` explicitly.
 - `POST /mcp` without `mcp-session-id` must be an `initialize` request.
 - `POST /mcp`, `GET /mcp`, and `DELETE /mcp` for existing sessions require the `mcp-session-id` header.
 - `GET /mcp` is used for SSE notifications (progress updates and elicitation prompts).
@@ -140,6 +143,45 @@ Operational constraints in HTTP mode:
 - Set `x-harness-pipeline-version: 0` or `1` on the `initialize` request to select V0 or V1 pipeline resources for that HTTP session.
 - Set `x-harness-auto-approve-risk: none|low_write|medium_write|high_write|all` on the `initialize` request to choose a stricter per-session auto-approval threshold. The server caps this value at the deployment-level `HARNESS_AUTO_APPROVE_RISK`, so a session can reduce but not expand the configured approval ceiling.
 
+#### HarnessID OAuth Mode
+
+Set `HARNESS_MCP_MODE=oauth` to let remote MCP clients discover HarnessID and complete OAuth 2.1 Authorization Code with PKCE. OAuth mode is available only with HTTP transport. Production HarnessID, MCP resource, and API routing defaults are built in:
+
+```bash
+HARNESS_MCP_MODE=oauth
+```
+
+This defaults to the issuer `https://id.harness.io/idp/realms/HarnessIDP`, resource `https://mcp.harness.io/mcp`, OAuth client `mcp-client`, and Harness API base `https://mcp.harness.io/cli`. Override them only for QA, local development, or another Harness environment.
+
+`HARNESS_API_KEY` must not be set in this mode. `HARNESS_MCP_OAUTH_JWKS_URI` defaults to `<issuer>/protocol/openid-connect/certs`, and `HARNESS_ACCOUNT_ID` is unnecessary because the account comes from the token.
+
+The server publishes RFC 9728 protected-resource metadata and returns this challenge when a client has not authenticated:
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://mcp.harness.io/.well-known/oauth-protected-resource/mcp"
+```
+
+It validates the HarnessID access token's RS256 signature, `iss`, expiry, and `sub` using the configured JWKS endpoint, and checks that the token was issued to `HARNESS_MCP_OAUTH_CLIENT_ID` through the `azp` claim. `HARNESS_MCP_OAUTH_RESOURCE` is the RFC 9728 protected-resource identifier used for discovery and challenges. Current HarnessID access tokens use `aud: account` rather than the MCP URL, so the resource is not compared with `aud`.
+
+The account ID comes from the token's `HARNESS_MCP_OAUTH_ACCOUNT_CLAIM` claim (`account_id` by default), which the HarnessID `organization` scope populates. Each session stores the caller's access token and forwards it to the Harness API as `Authorization: Bearer`, so Harness RBAC and audit records reflect the logged-in user rather than a shared PAT. The session is bound to the `sub` and account it was created with: a later request may carry a refreshed token, but one for a different user or account is rejected.
+
+Clients normally need only the MCP resource URL:
+
+```json
+{
+  "mcpServers": {
+    "harness": {
+      "url": "https://mcp.harness.io/mcp"
+    }
+  }
+}
+```
+
+The client reads the protected-resource metadata, discovers `HARNESS_MCP_OAUTH_ISSUER`, and then uses that authorization server's RFC 8414 metadata. If the client does not support dynamic client registration, use the pre-registered `mcp-client` client ID.
+
+See [HarnessID OAuth for a self-hosted MCP server](docs/harnessid-oauth.md) for the QA Keycloak checklist and validation commands.
+
 #### Multi-User Mode
 
 Set `HARNESS_MCP_MODE=multi-user` for shared HTTP deployments where each client authenticates as a different Harness user. In this mode:
@@ -502,13 +544,10 @@ pnpm docker:run
 docker run --rm -p 3000:3000 \
   -e HARNESS_API_KEY=pat.xxx.xxx.xxx \
   -e HARNESS_ACCOUNT_ID=your-account-id \
-  -e HARNESS_MCP_AUTH_TOKEN=replace-with-a-long-random-token \
   harness-mcp-server
 ```
 
 The container runs in HTTP mode on port 3000 by default with a built-in health check.
-It binds to the container network, so set `HARNESS_MCP_AUTH_TOKEN` in `.env` or the
-container environment and send that value as `Authorization: Bearer <token>` on MCP requests.
 
 ### Kubernetes
 
@@ -538,11 +577,17 @@ The server automatically loads environment variables from a `.env` file in the p
 
 | Variable                    | Required | Default                     | Description                                                                                                                                                                                                                                           |
 | --------------------------- | -------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `HARNESS_MCP_MODE`          | No       | `single-user`               | Deployment mode: `single-user` (API key in config, used for all sessions) or `multi-user` (HTTP only, per-session credentials via `x-harness-api-key` and optional `x-harness-account-id` headers)                                                   |
-| `HARNESS_API_KEY`           | Yes*     | --                          | Harness personal access token or service account token. Required in `single-user` mode. Must NOT be set in `multi-user` mode                                                                                                                          |
+| `HARNESS_MCP_MODE`          | No       | `single-user`               | Deployment mode: `single-user` (shared API key), `multi-user` (HTTP with per-session API keys), or `oauth` (HTTP with HarnessID access-token validation)                                                                                              |
+| `HARNESS_API_KEY`           | Yes*     | --                          | Harness personal access token or service account token. Required in `single-user` mode. Must NOT be set in `multi-user` or `oauth` mode, where each session brings its own credential                                                                 |
 | `HARNESS_ACCOUNT_ID`        | No       | *(from PAT/SAT)*            | Harness account identifier. Auto-extracted from PAT/SAT tokens in single-user mode; multi-user sessions can provide their own via `x-harness-account-id` when the API key does not embed one                                                          |
-| `HARNESS_BASE_URL`          | No       | `https://app.harness.io`    | Harness API/UI base URL for local stdio or self-hosted HTTP deployments. Set this to environments such as `https://harness0.harness.io` when running the server yourself. It does not affect the managed `https://mcp.harness.io/mcp` hosted endpoint |
-| `HARNESS_FME_API_KEY`       | No       | --                          | Optional single-user/self-hosted FME/Split Admin credential used for `fme_` resources in **legacy (`workspace_id`) mode only**. This can be a legacy Split admin key or an FME-entitled Harness PAT/SAT. FME calls go directly to `api.split.io`, so hosted OAuth/service-routing credentials for Harness platform APIs do not authenticate these requests. Must not be set in `multi-user` mode; FME must use each session's `x-harness-api-key` credential. If unset, FME falls back to a non-placeholder `HARNESS_API_KEY` for self-hosted sessions. Harness-native (`org_id`+`project_id`) mode ignores this and uses the standard `HARNESS_API_KEY`/`HARNESS_BASE_URL` instead |
+| `HARNESS_BASE_URL`          | No       | `https://app.harness.io` (`https://mcp.harness.io/cli` in OAuth mode) | Harness API/UI base URL. OAuth mode routes through the hosted MCP `/cli` proxy by default; other modes use the Harness SaaS API directly |
+| `HARNESS_MCP_OAUTH_ISSUER`  | No       | `https://id.harness.io/idp/realms/HarnessIDP` | HarnessID issuer matched exactly against the access token `iss` claim                                                                                                                                                  |
+| `HARNESS_MCP_OAUTH_RESOURCE` | No      | `https://mcp.harness.io/mcp` | Public canonical MCP URL published as the RFC 9728 resource identifier                                                                                                     |
+| `HARNESS_MCP_OAUTH_JWKS_URI` | No      | `<issuer>/protocol/openid-connect/certs` | HarnessID JWKS endpoint used to validate RS256 access-token signatures                                                                                                                                                  |
+| `HARNESS_MCP_OAUTH_CLIENT_ID` | No     | `mcp-client`                | HarnessID client the access token must be issued to, checked against the token's `azp` claim                                                                                                                                                        |
+| `HARNESS_MCP_OAUTH_ACCOUNT_CLAIM` | No | `account_id`                | Access-token claim carrying the Harness account ID, populated by the HarnessID `organization` scope                                                                                                                                                 |
+| `HARNESS_MCP_OAUTH_SCOPES`  | No       | `openid profile email organization` | Space-separated scopes advertised in RFC 9728 protected-resource metadata                                                                                                                                                    |
+| `HARNESS_FME_API_KEY`       | No       | --                          | Optional single-user/self-hosted FME/Split Admin credential used for `fme_` resources in **legacy (`workspace_id`) mode only**. Legacy FME is unavailable in OAuth mode so HarnessID tokens are never sent to `api.split.io`; use Harness-native `org_id`+`project_id` scope instead. Must not be set in `multi-user` or `oauth` mode |
 | `HARNESS_FME_BASE_URL`      | No       | `https://api.split.io`      | Split/FME Admin API base URL used by `fme_` resources in **legacy (`workspace_id`) mode only**. HTTP URLs require `HARNESS_ALLOW_HTTP=true` for local development. Harness-native (`org_id`+`project_id`) mode ignores this and uses the standard `HARNESS_API_KEY`/`HARNESS_BASE_URL` instead |
 | `HARNESS_ORG`               | No       | --                          | Organization ID. Used when `org_id` is not specified per tool call. If omitted, `org_id` must be provided explicitly. Agents can also discover orgs dynamically via `harness_list(resource_type="organization")`                                      |
 | `HARNESS_PROJECT`           | No       | --                          | Project ID. Used when `project_id` is not specified per tool call. Agents can also discover projects dynamically via `harness_list(resource_type="project")`                                                                                          |
@@ -558,7 +603,7 @@ The server automatically loads environment variables from a `.env` file in the p
 | `HARNESS_ALLOW_HTTP`        | No       | `false`                     | Allow non-HTTPS `HARNESS_BASE_URL`. By default, the server enforces HTTPS for security. Set to `true` only for local development against a non-TLS Harness instance                                                                                   |
 | `HARNESS_PIPELINE_VERSION`  | No       | `0`                         | **(Alpha)** Pipeline YAML version. `0` loads the `pipeline` resource type and excludes `pipeline_v1`; `1` loads `pipeline_v1` and excludes `pipeline`. HTTP sessions can override this at initialize time with `x-harness-pipeline-version: 0` or `1` |
 | `HARNESS_MCP_ALLOWED_HOSTS` | No       | --                          | Comma-separated hostnames allowed by HTTP transport Host-header validation. `mcp.harness.io` is allowed by default for localhost binds; add proxy/custom domains here                                                                                 |
-| `HARNESS_MCP_AUTH_TOKEN`    | No       | --                          | Bearer token required on `/mcp` HTTP routes when set. Required by default when HTTP transport binds to a non-loopback host                                                                                                                             |
+| `HARNESS_MCP_AUTH_TOKEN`    | No       | --                          | Static Bearer token required on `/mcp` HTTP routes when set. Required by default for non-loopback single-user and multi-user binds. Must be unset in `oauth` mode                                                                                    |
 | `HARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP` | No | `false`         | Explicitly allow unauthenticated HTTP transport on non-loopback binds. Use only behind another authenticated control                                                                                                                                    |
 | `HARNESS_MCP_TRUST_PROXY`   | No       | `0`                         | Number of reverse proxy / load balancer hops to trust for client IP resolution (Express `trust proxy`). Set to the proxy count in front of the server so per-IP rate limiting keys on the real client rather than the proxy socket peer                |
 | `HARNESS_MCP_LOG_FILE`      | No       | `~/.claude/harness-mcp.log` | File used for stdio disconnect/crash diagnostics when stderr may no longer be available                                                                                                                                                               |
@@ -669,7 +714,7 @@ Current multi-scope resources include `connector`, `service`, `environment`, `in
 | Tool               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | --------------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `harness_describe` | Discover available resource types, operations, and fields. No API call — returns local registry metadata.                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `harness_schema`   | Fetch exact YAML/JSON Schema definitions and examples for creating/updating resources. Pipeline/template schemas are bundled; connector, environment, service, secret, and infrastructure schemas are scope-aware entity schemas fetched from bundled snapshots or NG `/yaml-schema`; `release_process` and `release_activity` schemas are fetched live from `/gateway/rmg/api/yamlSchema`. Supports deep drilling via `path`.                                                                                                              |
+| `harness_schema`   | Fetch exact YAML/JSON Schema definitions and examples for creating/updating resources. Pipeline/template schemas are bundled; connector, environment, service, secret, and infrastructure schemas are scope-aware entity schemas fetched from bundled snapshots or NG `/yaml-schema`; `release_process` and `release_activity` schemas are fetched live from RMG `/api/yamlSchema`. Supports deep drilling via `path`.                                                                                                          |
 | `harness_list`     | List resources of a given type with filtering, search, and pagination.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `harness_get`      | Get a single resource by its identifier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `harness_create`   | Create a new resource. Supports inline and remote (Git-backed) pipelines. Prompts for user confirmation via [elicitation](#elicitation).                                                                                                                                                                                                                                                                                                                                                                                        |
@@ -687,7 +732,7 @@ Use `harness_schema` before creating or updating YAML-backed resources so agents
 
 - Bundled schemas include `pipeline`, `template`, `trigger`, `pipeline_v1`, `template_v1`, `inputSet_v1`, `overlayInputSet_v1`, and `agent-pipeline`.
 - Entity schemas include `connector`, `environment`, `service`, `secret`, and `infrastructure`. They are scope-aware (`account`, `org`, or `project`) and require `org_id`/`project_id` when the selected scope requires them.
-- Release Management definitions (`release_process`, `release_activity`) fetch live JSON Schema from `/gateway/rmg/api/yamlSchema` (not bundled). Pass `scope`, `org_id`, and `project_id` when scoping to org or project.
+- Release Management definitions (`release_process`, `release_activity`) fetch live JSON Schema from RMG `/api/yamlSchema` (not bundled). Pass `scope`, `org_id`, and `project_id` when scoping to org or project.
 - Vendored entity snapshots are used first when they match the runtime account; otherwise the tool falls back to the Harness NG `/yaml-schema` API and caches the result.
 - Omit `path` for a field/section summary, then pass a dot-separated `path` to inspect a nested definition.
 
@@ -912,7 +957,7 @@ For v1 pipelines:
 
 1. Fetch `harness_get(resource_type="runtime_input_template_v1", resource_id="<pipeline_id>")`.
    For Git-backed pipelines, pass `branch_name`, `connector_ref`, and `repo_name` through `params`.
-2. Read `template_yaml` and `resolved_yaml` for declared `${{ inputs.* }}` values and defaults.
+2. Use each returned `inputs[].details.name` as a top-level key in `harness_execute.inputs`.
 3. Run `harness_execute(resource_type="pipeline_v1", action="run", resource_id="<pipeline_id>", inputs={...})`.
    The server wraps these values under an `inputs:` YAML root and sends the API's `inputs_yaml` body.
 
@@ -1216,7 +1261,7 @@ Harness pipelines can be stored in three ways:
 
 ## Resource Types
 
-243 resource types organized across 40 toolsets. Each resource type supports a subset of CRUD operations and optional execute actions.
+245 resource types organized across 41 toolsets. Each resource type supports a subset of CRUD operations and optional execute actions.
 
 ### Platform
 
@@ -1505,7 +1550,7 @@ Use `harness_execute(resource_type="pull_request", action="close", ...)` for an
 
 Release Management (RMG) resources are default-enabled. Definition resources (`release_process`, `release_activity`) support list/get/create/update/delete with `body.yaml`; call `harness_schema(resource_type="release_process"|"release_activity")` before create/update. Execution resources monitor running releases — most list operations require `release_id` (UUID from `harness_list resource_type=release`, or the UI URL slug such as `identifier-1.0.0-abc`). Paste an RMG release URL into `harness_list` to auto-fill `release_id`.
 
-RMG requests use `/gateway/rmg/api/...` paths on the default Harness client, with account scoping via the `Harness-Account` header. Org/project scope uses header-based scoping when `org_id`/`project_id` are provided. `release_execution_phase` is list-only — use each phase item's `identifier` field as `params.phase_identifier` when calling `harness_get` on phase input/output resources (do not call `harness_get` on `release_execution_phase` itself). Release list `status` filtering is applied client-side on the current page only; keep paging with the same filters when results may span pages.
+RMG calls use `${HARNESS_BASE_URL}/gateway/rmg` with account scoping via the `Harness-Account` header. Org/project scope uses header-based scoping when `org_id`/`project_id` are provided. `release_execution_phase` is list-only — use each phase item's `identifier` field as `params.phase_identifier` when calling `harness_get` on phase input/output resources (do not call `harness_get` on `release_execution_phase` itself). Release list `status` filtering is applied client-side on the current page only; keep paging with the same filters when results may span pages.
 
 | Resource Type                         | List | Get | Create | Update | Delete | Execute Actions |
 | ------------------------------------- | ---- | --- | ------ | ------ | ------ | --------------- |
@@ -1531,6 +1576,58 @@ Typical workflow:
 6. `harness_get` on `release_input`, `release_execution_phase_input`, `release_execution_phase_output`, `release_execution_activity_output`, or `release_execution_activity_input` using `release_id` plus `params.phase_identifier` / `params.activity_identifier` / `activity_execution_id` as documented on each resource.
 
 
+### Vibe
+
+The default-enabled `vibe` toolset covers the [Vibe Orchestrator BFF contract](tests/fixtures/vibe-bff-openapi.yaml) under `${HARNESS_BASE_URL}/vibe/v1`. It uses the existing Harness connection and account header, without adding account/org/project query parameters or scope fields to request bodies. The team validated the Vibe flow using Harness API-key authentication (PAT/SAT), so no opt-in setting is required for default sessions. The curated OpenAPI documents bearer/session authentication; the server's OAuth mode forwards the current session's bearer token. Automated regressions verify both header paths; gateway authentication remains subject to the target environment's configuration.
+
+| Resource Type | List | Get | Create | Update | Delete | Execute Actions |
+| ------------- | ---- | --- | ------ | ------ | ------ | --------------- |
+| `vibe_project` |      |     | x      |        |        | `prepare`, `deploy` |
+| `vibe_app_lifecycle` | | x | | | | `events` |
+
+The API supports two intake paths. Keep these API-native request shapes:
+
+| Source available to the coding agent | API flow |
+| ----------------------------------- | -------- |
+| GitHub repository link/connector | `harness_create` with `resource_type="vibe_project"` and `body.mode` plus the mode-specific fields. The contract names `github_link` and `github_connector` but does not define their URL, branch, or connector field shapes; these fields are forwarded to the backend without inventing a mapping. |
+| ZIP file | Call `prepare` with the app name and file metadata, upload the bytes to the returned signed target, then call `deploy`. |
+| Local source directory | The coding agent archives the intended workspace source into a ZIP locally, then follows the ZIP flow. A local path or conversational context is not an API-supported source upload. |
+
+When packaging a directory, include the source, manifests, lockfiles, configuration, and intended uncommitted edits needed to build it. Exclude credentials, `.git`, installed dependencies, and generated artifacts. Packaging and the signed upload happen where the files are accessible; a hosted MCP server cannot read the coding agent's local directory.
+
+For an existing ZIP, prepare the upload:
+
+```json
+{
+  "resource_type": "vibe_project",
+  "action": "prepare",
+  "body": {
+    "name": "demo-app",
+    "file": {
+      "path": "app.zip",
+      "size_bytes": 12345,
+      "content_type": "application/zip"
+    }
+  }
+}
+```
+
+Pass this to `harness_execute`. The size must describe the actual ZIP; `size_bytes`, `content_type`, and `md5` are optional and nullable. Additional prepare fields are preserved for backend validation, as permitted by the OpenAPI. Preparation returns `projectId`, `sourceId`, and `upload`, including each file's `uploadUrl`, `method`, `headers`, and `expiresAt`. Upload the file bytes directly using that signed URL, method, and headers; preserve the URL exactly and do not add Harness credentials to the storage request. The prepare action does not read or upload local files.
+
+After a successful upload, explicitly deploy:
+
+```json
+{
+  "resource_type": "vibe_project",
+  "action": "deploy",
+  "resource_id": "<projectId returned by prepare>"
+}
+```
+
+For JSON imports, use the returned `id` instead. Deployment also accepts `body: {"project_id": "<Vibe app id>"}` or `params.app_id`; the API wire field is snake_case `project_id` even though prepare returns camelCase `projectId`. The generic tool's top-level `project_id` is a Harness scope identifier and is never used as the Vibe app id. Import and prepare create the app/source; neither starts deployment. Writes are not automatically retried, and deployment uses the existing high-risk confirmation policy.
+
+Read progress with `harness_get(resource_type="vibe_app_lifecycle", resource_id="<Vibe app id>")`. It retains app URLs, execution stages, substeps, failures, log lines, and build-analyzer details. The `events` execute action accepts `resource_id` or `params.app_id` and consumes the SSE endpoint as a finite batch: up to 20 JSON events or five seconds after connection, with a 1 MiB response limit. These limits belong to the Vibe endpoint. The connection's `HARNESS_API_TIMEOUT_MS` also bounds connection and stream consumption together; expiration returns a timeout error. A completed batch returns `events` and `stop_reason` (`end`, `event_limit`, or `duration_limit`) and closes the stream. Neither initial connection failures nor broken streams are retried. Events are transient diffs with no documented replay cursor; use lifecycle get for an authoritative snapshot. Both lifecycle reads are available in read-only mode.
+
 ### Feature Flags
 
 
@@ -1547,8 +1644,8 @@ Typical workflow:
 | `fme_identity`                      |      |     | x      | x      |        |                                           |
 | `fme_standard_segment`              | x    | x   |        |        |        |                                           |
 | `fme_segment_keys`                  | x    |     |        | x      |        |                                           |
-| `fme_segment`                       | x    | x   | x      |        | x      |                                           |
-| `fme_segment_definition`            | x    | x   | x      | x      | x      |                                           |
+| `fme_segment`                       | x    | x   | x      | x      | x      |                                           |
+| `fme_segment_definition`            | x    | x   | x      | x      | x      | `list_keys`, `add_keys`, `remove_keys`    |
 
 
 **FME (Split.io) resources** — `fme_`* resources support **dual-mode scoping**: legacy calls pass `workspace_id` and hit the Split.io API (`api.split.io`); newer calls pass `org_id`+`project_id` together and hit Harness-native endpoints (standard `HARNESS_API_KEY`/`HARNESS_BASE_URL`, same auth as every other `harness_*` resource) instead. Passing both `workspace_id` and `org_id`/`project_id` on the same call, or mixing `org_id` with `project_id` alone, is an error — pick one mode per call. Every operation below is available in legacy mode, unchanged. Harness-native mode coverage is currently narrower:
@@ -1563,10 +1660,10 @@ Typical workflow:
 - **`fme_rule_based_segment_definition`** — (Deprecated — see `fme_segment_definition`.) Harness-native mode is rejected on every operation/action (`list`/`update`/`enable`/`disable`/`change_request`) — use `fme_segment_definition` instead (no `enable`/`disable`/`change_request` equivalent there); this resource supports only the legacy `workspace_id`/`environment_id` contract.
 - **`fme_traffic_type`** — dual-mode `list`. Pass `org_id`+`project_id` (preferred) or the deprecated `workspace_id`. Native pagination uses `offset`/`limit` (max 100; `harness_list` `size` maps to `limit`); results are promoted to `items`/`total`. Each item has `id` and `name` (no `displayAttributeId`).
 - **`fme_identity`** — `create`/`update` are not yet implemented if `org_id`+`project_id` are passed together; otherwise proceeds as a normal legacy call.
-- **`fme_standard_segment`** — (Deprecated — see `fme_segment`.) Harness-native mode is rejected on every operation (`list`/`get`) — use `fme_segment` instead; this resource supports only the legacy `workspace_id` contract. There is no `create` operation for this resource in either mode.
-- **`fme_segment_keys`** — `list`/`update` are not yet implemented if `org_id`+`project_id` are passed together; otherwise proceeds as a normal legacy call.
-- **`fme_segment`** — `list`/`get`/`create`/`delete` are wired to the real `/fme/api/v4/segments` endpoint (consolidates `fme_standard_segment`/`fme_rule_based_segment`); `create` body: `name`, `trafficType`, `type` (required — one of `standard`/`rule_based`/`large`), optional `description`/`tags`/`owners`.
-- **`fme_segment_definition`** — Harness-native only (no legacy `workspace_id` support). `list`/`get`/`create`/`update`/`delete` are wired to `/fme/api/v4/segment-definitions`, per `Harness_Split/Main` PR #12644 (open, not yet merged as of this writing — paths may still change). `update` uses JSON Merge Patch on `description`, the only mutable field. There is no `enable`/`disable`/`change_request` action — the backend has no such endpoints for this unified resource.
+- **`fme_standard_segment`** — deprecated. Legacy `workspace_id` still hits Split v2. Harness-native is rejected — use `fme_segment`.
+- **`fme_segment_keys`** — `list`/`update` remain legacy (`workspace_id` / `environment_id`+`segment_name`). Harness-native (`org_id`+`project_id`) is rejected — use `fme_segment_definition` execute `list_keys`/`add_keys`/`remove_keys`.
+- **`fme_segment`** — Native only (`org_id`+`project_id`). CRUD. `list`/`get`/`update`/`delete` require `segment_type`: `STANDARD` | `LARGE` | `RULE_BASED`. Create body: `name`, `trafficType`, `segmentType`; optional `description`, `tags`, `owners`.
+- **`fme_segment_definition`** — Native only. CRUD plus execute `list_keys`/`add_keys`/`remove_keys`. Update is description only. Delete fails with `hasDependents` while keys remain.
 
 In single-user/self-hosted mode, legacy-mode auth uses a Bearer token from `HARNESS_FME_API_KEY`, falling back to a non-placeholder `HARNESS_API_KEY`. `HARNESS_FME_API_KEY` may be a legacy Split admin key or an FME-entitled Harness PAT/SAT, but it is rejected in `multi-user` mode so shared deployments cannot override each session user's credential. Hosted OAuth/service-routing credentials for Harness platform APIs do not authenticate direct Split.io requests. `fme_feature_flag` supports full lifecycle management in legacy mode: create (requires `traffic_type_id`), list, get, update metadata, delete, and kill/restore/reallocate/archive/unarchive execute actions. Use `fme_traffic_type` to discover traffic type IDs, `fme_identity` to create/update identity attributes, and `fme_standard_segment` / `fme_segment_keys` to inspect standard segments and add member keys. `fme_rule_based_segment` provides CRUD for targeting segments, while `fme_rule_based_segment_definition` manages environment-specific segment rules with enable/disable and change request approval flows.
 
@@ -1842,9 +1939,11 @@ Security exemption execute workflow:
 
 ## Toolset Filtering
 
-By default, 40 of 42 toolsets are enabled. One toolset is opt-in and excluded from the defaults:
+By default, 41 of 44 toolsets are enabled. Three toolsets are opt-in and excluded from the defaults:
 
 - **`ansible`** — Harness Ansible (inventories, playbooks, hosts, activity). Opt-in because it is project-scoped and adds concepts many users do not need.
+- **`autonomous_work`** — Development Harness (autonomous work). Opt-in; see toolset description for scope.
+- **`registries-v3`** — Harness Artifact Registry v3 (packages, versions, files, metadata, scans, firewall exceptions). Opt-in until v3 writes land, so agents don't have to disambiguate between v1 registries/artifacts and v3 packages/versions.
 
 ### Adding toolsets with `+` prefix
 
@@ -1922,7 +2021,9 @@ Available toolset names:
 | `ai-evals`              | eval_dataset, eval_dataset_item, evaluation, eval_run, eval_run_item, eval_run_by_eval, eval_metric, eval_metric_set, eval_metric_set_entry, eval_suite, eval_suite_evaluation, eval_suite_run, eval_target, eval_annotation, eval_analytics, eval_git_settings, eval_registry_item, eval_git_registration, online_eval |
 | `iacm`                  | iacm_workspace, iacm_variable_set, iacm_resource, iacm_module, iacm_provider, iacm_workspace_costs, iacm_activity_resource_change                                                                                                                                                               |
 | `ansible` *(opt-in)*    | ansible_inventory, ansible_playbook, ansible_host, ansible_host_activity, ansible_activity                                                                                                                                                                                                      |
+| `registries-v3` *(opt-in)* | package_v3, version_v3, file_v3, registry_metadata_v3, package_metadata_v3, version_metadata_v3, file_metadata_v3, metadata_key_v3, metadata_value_v3, artifact_scan_v3, bulk_scan_evaluation_v3, firewall_exception_v3, firewall_exception_version_v3                                       |
 | `release-management`  | release_process, release_activity, release, release_execution_phase, release_execution_task, release_execution_activity, release_input, release_execution_phase_input, release_execution_phase_output, release_execution_activity_input, release_execution_activity_output |
+| `vibe`                | vibe_project, vibe_app_lifecycle |
 
 
 ## Architecture
@@ -1940,8 +2041,8 @@ Available toolset names:
                           |
                  +--------v---------+
                 |    Registry       |  <-- Declarative resource definitions
-                |  40 Toolsets      |      (data files, not code)
-                |  243 Resource Types|
+                |  41 Toolsets      |      (data files, not code)
+                |  245 Resource Types|
                  +--------+---------+
                           |
                  +--------v---------+

package/build/client/harness-client.d.ts

@@ -6,6 +6,7 @@ import type { RequestOptions } from "./types.js";
  * AsyncLocalStorage) instead of using the static config value.
  */
 export type AccountIdResolver = () => string | undefined;
+export type BearerTokenResolver = () => string | undefined;
 export declare class HarnessClient {
     private readonly baseUrl;
     private readonly token;
@@ -17,6 +18,7 @@ export declare class HarnessClient {
     private readonly fmeApiKey;
     private readonly mcpMode;
     private accountIdResolver?;
+    private bearerTokenResolver?;
     private currentUserId?;
     private currentUserPromise?;
     constructor(config: Config);
@@ -25,6 +27,8 @@ export declare class HarnessClient {
      * calls this first, falling back to the static config value.
      */
     setAccountIdResolver(resolver: AccountIdResolver): void;
+    /** Set the per-session OAuth access token used for downstream Harness calls. */
+    setBearerTokenResolver(resolver: BearerTokenResolver): void;
     /** Resolve the account ID: per-request override → static config fallback. */
     private resolveAccountId;
     get account(): string;

package/build/client/harness-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"harness-client.d.ts","sourceRoot":"","sources":["../../src/client/harness-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAA6C,MAAM,cAAc,CAAC;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAuJjD;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,MAAM,GAAG,SAAS,CAAC;AAEzD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,iBAAiB,CAAC,CAAoB;IAC9C,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,kBAAkB,CAAC,CAAkB;gBAEjC,MAAM,EAAE,MAAM;IAY1B;;;OAGG;IACH,oBAAoB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAIvD,6EAA6E;IAC7E,OAAO,CAAC,gBAAgB;IAIxB,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,OAAO,CAAC,YAAY;IAoBpB,OAAO,CAAC,gBAAgB;IA4CxB;;;;;;;;OAQG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IA2BnC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAwJrD;;;;OAIG;IACG,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IA2F/D,OAAO,CAAC,QAAQ;CA8DjB"}
+{"version":3,"file":"harness-client.d.ts","sourceRoot":"","sources":["../../src/client/harness-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAA6C,MAAM,cAAc,CAAC;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAyKjD;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,MAAM,GAAG,SAAS,CAAC;AACzD,MAAM,MAAM,mBAAmB,GAAG,MAAM,MAAM,GAAG,SAAS,CAAC;AAE3D,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,iBAAiB,CAAC,CAAoB;IAC9C,OAAO,CAAC,mBAAmB,CAAC,CAAsB;IAClD,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,kBAAkB,CAAC,CAAkB;gBAEjC,MAAM,EAAE,MAAM;IAY1B;;;OAGG;IACH,oBAAoB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAIvD,gFAAgF;IAChF,sBAAsB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAI3D,6EAA6E;IAC7E,OAAO,CAAC,gBAAgB;IAIxB,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,OAAO,CAAC,YAAY;IAoBpB,OAAO,CAAC,gBAAgB;IAoExB;;;;;;;;OAQG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IA2BnC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAmKrD;;;;OAIG;IACG,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IA0F/D,OAAO,CAAC,QAAQ;CA8DjB"}

package/build/client/harness-client.js

@@ -2,8 +2,9 @@ import { isPlaceholderCredential, resolveFmeApiKey } from "../config.js";
 import { HarnessApiError } from "../utils/errors.js";
 import { RateLimiter } from "../utils/rate-limiter.js";
 import { createLogger } from "../utils/logger.js";
-import { redactJsonString } from "../utils/redact.js";
-import { isFormDataBody } from "../utils/type-guards.js";
+import { redactJsonString, redactSensitiveFields } from "../utils/redact.js";
+import { isFormDataBody, isRecord } from "../utils/type-guards.js";
+import { assertJsonEventStreamLimits, readJsonEventStream } from "./sse.js";
 const log = createLogger("harness-client");
 const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
 /**
@@ -100,6 +101,28 @@ const ERROR_FIELD_ENRICHMENTS = [
     { pathPrefix: "/loadTest/", field: "description" },
 ];
 const MAX_ERROR_DETAIL_CHARS = 400;
+/** Preserve standard Harness errors; adapt Vibe's nested BFF envelope only on Vibe paths. */
+function parseApiError(body, path) {
+    let raw;
+    try {
+        raw = JSON.parse(body);
+    }
+    catch {
+        return {};
+    }
+    if (!isRecord(raw))
+        return {};
+    const nested = path.startsWith("/vibe/v1/") && isRecord(raw.error) ? raw.error : {};
+    const message = typeof raw.message === "string" ? raw.message : nested.message;
+    const code = raw.code ?? nested.code;
+    return {
+        ...raw,
+        message: typeof message === "string" ? message : undefined,
+        code: typeof code === "string" || typeof code === "number" ? code : undefined,
+        details: raw.details ?? (isRecord(nested.details) ? JSON.stringify(redactSensitiveFields(nested.details)) : nested.details),
+        correlationId: typeof raw.correlationId === "string" ? raw.correlationId : undefined,
+    };
+}
 /** Extra NG fields (`details`, `detailedMessage`, `responseMessages`) not already in `message`. */
 function collectErrorDetail(parsed, message) {
     const seen = new Set([message.trim()]);
@@ -148,6 +171,7 @@ export class HarnessClient {
     fmeApiKey;
     mcpMode;
     accountIdResolver;
+    bearerTokenResolver;
     currentUserId;
     currentUserPromise;
     constructor(config) {
@@ -168,6 +192,10 @@ export class HarnessClient {
     setAccountIdResolver(resolver) {
         this.accountIdResolver = resolver;
     }
+    /** Set the per-session OAuth access token used for downstream Harness calls. */
+    setBearerTokenResolver(resolver) {
+        this.bearerTokenResolver = resolver;
+    }
     /** Resolve the account ID: per-request override → static config fallback. */
     resolveAccountId() {
         return this.accountIdResolver?.() ?? this.accountId;
@@ -196,6 +224,21 @@ export class HarnessClient {
         return headers;
     }
     applyDefaultAuth(headers, isFme) {
+        if (this.mcpMode === "oauth") {
+            deleteHeaderValues(headers, "x-api-key");
+            if (isFme) {
+                throw new HarnessApiError("Legacy workspace-based FME calls are unavailable in oauth mode. " +
+                    "Pass org_id and project_id to use the Harness-native FME API.", 401, "FME_AUTH_MISSING");
+            }
+            if (getHeaderValue(headers, "authorization"))
+                return;
+            const token = this.bearerTokenResolver?.();
+            if (!token) {
+                throw new HarnessApiError("OAuth access token is unavailable for this MCP session.", 401, "OAUTH_TOKEN_MISSING");
+            }
+            headers["Authorization"] = `Bearer ${token}`;
+            return;
+        }
         if (isFme) {
             // FME/Split Admin APIs expect Bearer auth. Drop x-api-key here so
             // placeholder credentials are never forwarded to api.split.io.
@@ -266,6 +309,8 @@ export class HarnessClient {
         }
     }
     async request(options) {
+        if (options.responseType === "sse")
+            assertJsonEventStreamLimits(options.sseLimits);
         await this.rateLimiter.acquire();
         const method = options.method ?? "GET";
         const url = this.buildUrl(options);
@@ -288,6 +333,7 @@ export class HarnessClient {
                 log.debug(`Retry attempt ${attempt}/${this.maxRetries}`, { backoffMs: Math.round(backoff) });
                 await new Promise((r) => setTimeout(r, backoff));
             }
+            let timer;
             try {
                 // Check if already aborted before starting the request
                 if (options.signal?.aborted) {
@@ -295,7 +341,7 @@ export class HarnessClient {
                 }
                 const timeoutController = new AbortController();
                 const effectiveTimeout = options.timeoutMs ?? this.timeout;
-                const timer = setTimeout(() => timeoutController.abort(), effectiveTimeout);
+                timer = setTimeout(() => timeoutController.abort(), effectiveTimeout);
                 // Merge external signal (client disconnect) with timeout signal
                 const signal = options.signal
                     ? AbortSignal.any([options.signal, timeoutController.signal])
@@ -318,17 +364,12 @@ export class HarnessClient {
                     body: fetchBody,
                     signal,
                 });
-                clearTimeout(timer);
+                // JSON/binary behavior is unchanged; SSE keeps the HTTP deadline through consumption.
+                if (options.responseType !== "sse")
+                    clearTimeout(timer);
                 if (!response.ok) {
                     const body = await response.text();
-                    let parsed = {};
-                    try {
-                        parsed = JSON.parse(body);
-                    }
-                    catch {
-                        // Non-JSON error (HTML proxy page, WAF block, etc.)
-                        // Provide actionable messages instead of leaking raw HTML to the LLM
-                    }
+                    const parsed = parseApiError(body, options.path);
                     const rawMessage = isGarbageMessage(parsed.message)
                         ? humanizeHttpError(response.status, body)
                         : parsed.message;
@@ -345,6 +386,18 @@ export class HarnessClient {
                     }
                     throw error;
                 }
+                if (options.responseType === "sse") {
+                    try {
+                        return await readJsonEventStream(response, signal, options.sseLimits);
+                    }
+                    catch (cause) {
+                        // Never reconnect a consumed stream, including when the overall HTTP deadline expires.
+                        if (timeoutController.signal.aborted && !options.signal?.aborted) {
+                            throw new HarnessApiError("Request timed out", 408, undefined, undefined, cause);
+                        }
+                        throw cause;
+                    }
+                }
                 // Binary response mode — return raw ArrayBuffer (used for ZIP downloads)
                 if (options.responseType === "buffer") {
                     const buffer = await response.arrayBuffer();
@@ -385,6 +438,9 @@ export class HarnessClient {
                 }
                 throw new HarnessApiError(`Request failed: ${err.message ?? String(err)}`, 502, undefined, undefined, err);
             }
+            finally {
+                clearTimeout(timer);
+            }
         }
         throw lastError ?? new HarnessApiError("Max retries exceeded", 500);
     }
@@ -434,11 +490,7 @@ export class HarnessClient {
                 clearTimeout(timer);
                 if (!response.ok) {
                     const body = await response.text();
-                    let parsed = {};
-                    try {
-                        parsed = JSON.parse(body);
-                    }
-                    catch { /* non-JSON */ }
+                    const parsed = parseApiError(body, options.path);
                     const rawMessage = isGarbageMessage(parsed.message)
                         ? humanizeHttpError(response.status, body)
                         : parsed.message;