# POST /v1/harnesses/preview

Source: <https://everruns.com/docs/api/operations/preview_harness/>

POST

/v1/harnesses/preview

Select code samplecURL (shell:curl)

```js
const url = 'https://app.everruns.com/api/v1/harnesses/preview';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"capabilities":[{"config":{},"ref":"web.search"},{"config":{"root":"/workspace"},"ref":"filesystem.read"}],"mcpServers":{"additionalProperty":{"actsAs":"none","args":["example"],"auth_mode":"none","command":"example","connectInChat":"ask","deferred":true,"elicitation_policy":"url","env":{"additionalProperty":"example"},"headers":{"additionalProperty":"example"},"oauth_provider_id":"example","protocol_mode":"auto","tool_discovery":true,"tool_labels":{"additionalProperty":"read_only"},"type":"http","url":"example","use":"catalog:linear"}},"parent_harness_id":"harness_01933b5a000070008000000000000602","system_prompt":"You are a research assistant."}'
};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```sh
curl --request POST \
  --url https://app.everruns.com/api/v1/harnesses/preview \
  --header 'Content-Type: application/json' \
  --data '{ "capabilities": [ { "config": {}, "ref": "web.search" }, { "config": { "root": "/workspace" }, "ref": "filesystem.read" } ], "mcpServers": { "additionalProperty": { "actsAs": "none", "args": [ "example" ], "auth_mode": "none", "command": "example", "connectInChat": "ask", "deferred": true, "elicitation_policy": "url", "env": { "additionalProperty": "example" }, "headers": { "additionalProperty": "example" }, "oauth_provider_id": "example", "protocol_mode": "auto", "tool_discovery": true, "tool_labels": { "additionalProperty": "read_only" }, "type": "http", "url": "example", "use": "catalog:linear" } }, "parent_harness_id": "harness_01933b5a000070008000000000000602", "system_prompt": "You are a research assistant." }'
```

* Production APIapp.everruns.com/api/v1/harnesses/preview

## Request Bodyrequired

Media typeapplication/json

Request to preview harness shape with capabilities applied

object

**capabilities**

Capability configurations to layer onto the preview. Empty list means none.

Array\<object>

Per-agent capability configuration

Associates a capability with an agent, including optional per-agent configuration. The config field allows the same capability to behave differently per-agent.

object

**config**

Per-agent configuration for this capability (capability-specific)

**ref**

required

Reference to the capability ID

string

##### Example

```json
[
  {
    "config": {},
    "ref": "web.search"
  },
  {
    "config": {
      "root": "/workspace"
    },
    "ref": "filesystem.read"
  }
]
```

**mcpServers**

MCP servers scoped to this preview, keyed by scope (`shared` / per-agent / etc.). Use the camelCase key `mcpServers` (preferred) or the snake\_case alias `mcp_servers`. Empty by default.

object

***key***

additional properties

Session-, agent-, or harness-scoped remote MCP server configuration.

This intentionally mirrors the `mcpServers` object shape used by common MCP client config files while staying within Everruns’ current remote-HTTP-only support.

object

**actsAs**

Identity whose grant this attachment requests.

string

Allowed values: none service user user\_or\_service

##### Example

```plaintext
service
```

**args**

Arguments passed to the stdio `command`.

Array\<string>

**auth\_mode**

Authentication mode used when executing tools from this scoped server.

string

Allowed values: none api\_key oauth

##### Example

```plaintext
api_key
```

**command**

Executable to spawn for a stdio transport server.

string | null

**connectInChat**

Whether a missing sign-in may pause the turn with an in-chat Connect card (`ask`, the default) or fails the call with a settings link (`never`).

string

Allowed values: ask never

##### Example

```plaintext
ask
```

**deferred**

Whether the server’s tools are listed only when the model asks for them through tool search (`false`, the default, lists them at turn start).

boolean

**elicitation\_policy**

Which elicitation modes this server may use (`url` by default).

string

Allowed values: url url\_and\_form none

##### Example

```plaintext
url
```

**env**

Environment variables set for the stdio `command`.

object

***key***

additional properties

string

**headers**

Additional HTTP headers sent on MCP requests (HTTP transport only).

object

***key***

additional properties

string

**oauth\_provider\_id**

Provider id used to resolve a user-scoped bearer token.

string | null

**protocol\_mode**

Protocol-era adoption policy for the MCP client (`auto` negotiates).

string

Allowed values: auto 2025-03-26 2025-06-18 2026-07-28

##### Example

```plaintext
auto
```

**tool\_discovery**

Whether to discover tool definitions live from this server.

boolean

**tool\_labels**

Risk labels for this server’s tools, by the tool’s own name: `read_only` never asks for approval in the normal mode, `changes` always asks. They win over the tool’s annotations and over a catalog preset’s saved labels. Honored on harness, agent and person-owned servers; dropped from session-scoped servers.

object

***key***

additional properties

A person’s saved risk label for one MCP tool.

Decision (2026-10-10): a person’s label always wins over the tool’s own annotations, because a remote server describes itself and a person who owns the integration knows better. `read_only` also clears `open_world`, since tool approval treats an outward-reaching tool like a destructive one; without that a read-only MCP tool would still ask every time.

string

Allowed values: read\_only changes

**type**

MCP transport type. Only remote HTTP is supported today.

string

Allowed values: http stdio

##### Example

```plaintext
http
```

**url**

URL of the remote MCP server endpoint. Required for HTTP transport; empty/ignored for stdio.

string

**use**

One of:

* string

  Organization catalog preset that supplies transport and authentication policy.

  string

  ##### Example

  ```plaintext
  catalog:linear
  ```

* null

  null

**parent\_harness\_id**

Parent harness to extend. When set, its prompt, capabilities, and MCP servers are merged with the fields in this request before rendering.

string | null

##### Example

```plaintext
harness_01933b5a000070008000000000000602
```

**system\_prompt**

System prompt to render as the base prompt for the preview. Optional: omit to preview a harness that contributes no base prompt of its own.

string | null

##### Example

```plaintext
You are a research assistant.
```

## Responses

### 200

Harness preview generated

Media typeapplication/json

Preview response showing merged prompt and tools

object

**features**

required

Session features from effective capabilities and their dependencies.

Array\<string>

**system\_prompt**

required

string

**tools**

required

Array\<object>

object

##### Examplegenerated

```json
{
  "features": [
    "example"
  ],
  "system_prompt": "example",
  "tools": [
    {}
  ]
}
```

### 500

Internal server error

Media typeapplication/json

Standard error response.

Wire shape is [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457): every error response includes `title` and `status`, and may include `detail`, `code`, `allowed_actions`, `retry_after_seconds`, `instance`, and `type`. The content type is rewritten to `application/problem+json` with the `application/problem+json` content type.

object

**allowed\_actions**

Recovery actions the caller can take next.

Array\<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

* **Error recovery** — `ErrorResponse.allowed_actions` carries `rel`s like `retry`, `retry-later`, `unarchive`, `get-existing` so the agent knows the right next call after a 4xx/429.
* **Entity hypermedia** — `WithUrls<T>.allowed_actions` carries state-aware `rel`s like `cancel`, `events`, `self`, `update` on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed `rel` vocabulary distinguishes them.

object

**hint**

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

**href**

Absolute (preferred) or relative URL the caller may invoke directly. **Always present on entity hypermedia actions** (`WithUrls<T>.allowed_actions`); **optional on error-recovery actions** (`ErrorResponse.allowed_actions`) where the matching `operation_id` is enough and the URI is implicit from the failed call.

string | null

**method**

HTTP method to use against `href`. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

**operation\_id**

OpenAPI `operationId` the caller should invoke. Lets an MCP client resolve the call without parsing `href`.

string | null

**rel**

required

Link relation describing the action. Examples: `self`, `cancel`, `pause`, `resume`, `events`, `retry`, `retry-later`, `unarchive`, `get-existing`, `delete`, `update`.

string

**schema\_ref**

OpenAPI `$ref` to the request-body schema, when the action takes one (e.g. `#/components/schemas/UpdateSessionRequest`). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null

**code**

Stable, machine-readable error code (snake\_case).

string | null

**detail**

Human-readable explanation specific to this occurrence.

string | null

**instance**

Request URI for this occurrence.

string | null

**retry\_after\_seconds**

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

**status**

required

HTTP status code; mirrors the response status line.

integer format: int32

**title**

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

**type**

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

##### Example

```json
{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://everruns.com/docs/errors/session_not_found"
}
```