Skip to content

Vayu MCP Server

Endpoint: http://127.0.0.1:9877/mcp (Streamable HTTP) · Also: stdio CLI

Vayu exposes its engine to AI agents (Claude Code, Cursor, VS Code, Codex, Zed) through a Model Context Protocol server. The server is TypeScript, hosted in the Electron main process, built on the official MCP TypeScript SDK (v2: @modelcontextprotocol/server), and proxies the engine's REST API on :9876 (or the fallback port the app chose when 9876 was held; see VAYU_ENGINE_URL below). The C++ engine is not modified - the MCP layer is Apache-2.0 like the rest of the app.

Once Vayu is running, any agent opts in with one command; if Vayu is down, the agent gets a clean "start Vayu" error. Threat model and posture: SECURITY.md.

Overview

  • Hosted in the app. MCP is a capability the running app exposes, not a separate process to manage. It is started and stopped alongside the engine sidecar by app/electron/main.ts, best-effort (a bind failure logs, the app continues without it, and mcp:status reports why so Settings can show it: another program holding the port is named, and no endpoint is offered while nothing is listening). Only the port is bound at launch (listener.ts, which imports no SDK); the SDK, the tool registry and the service are loaded by the first POST /mcp that arrives, so a launch no agent connects to never evaluates them - 5-7 MB of the main process at idle, measured on the packaged Windows app.
  • Proxy, not a second source of truth. Every tool maps to an existing engine endpoint via a thin fetch client (engine-client.ts). The main process cannot import the renderer's @/services, so this client is standalone.
  • Local-only. Binds 127.0.0.1, with Host- and Origin-header (DNS-rebinding) validation on /mcp.
  • Configurable from Settings. Server on/off, the allowlist, caps, the write toggle, and per-tool switches live in Settings → MCP and persist across restarts.

Connecting

Ensure Vayu is running, then register the endpoint once per machine. In the app, Settings → MCP offers a one-click Connect for Claude Code and VS Code (shells out to their CLIs) and copyable snippets for the rest.

Connect resolves the client CLI before running it, because a GUI-launched app often has a stripped PATH. On macOS and Linux that means the login shell ($SHELL -lc, falling back to /bin/sh -lc for a shell that does not accept -lc); on Windows it means where, preferring an .exe and then a .cmd shim over the extensionless POSIX script VS Code also installs. A .cmd/.bat shim is run through cmd.exe, which Node has required since 20.12. If the CLI is not installed, or the run fails for any reason, Connect says so and the snippet below it is the manual path.

# Claude Code (or click Connect in Settings → MCP)
claude mcp add --transport http vayu http://127.0.0.1:9877/mcp
// Claude Code (.mcp.json) / Cursor (.cursor/mcp.json)
{
  "mcpServers": {
    "vayu": { "type": "http", "url": "http://127.0.0.1:9877/mcp" }
  }
}
// VS Code (.vscode/mcp.json) - note the "servers" key
{
  "servers": { "vayu": { "type": "http", "url": "http://127.0.0.1:9877/mcp" } }
}
# Codex (~/.codex/config.toml)
[mcp_servers.vayu]
url = "http://127.0.0.1:9877/mcp"

Client compatibility

MCP defines three transports: stdio, Streamable HTTP, and the legacy HTTP+SSE (deprecated; not built for). The fixed-port Streamable HTTP endpoint covers most clients with a single URL; Zed (stdio-only) uses the CLI below.

Client Streamable HTTP stdio Config location
Claude Code ✅ (http) ✅ .mcp.json, ~/.claude.json, claude mcp add
Cursor ✅ ✅ .cursor/mcp.json, ~/.cursor/mcp.json
VS Code ✅ (servers key) ✅ .vscode/mcp.json
OpenAI Codex ✅ ✅ ~/.codex/config.toml
Zed ❌ not yet ✅ context_servers (stdio CLI)

Transports

Streamable HTTP (primary)

listener.ts binds 127.0.0.1:9877 at launch and answers what needs no SDK (gates.ts: non-/mcp paths 404, GET/DELETE 405); http.ts serves each POST /mcp once the first one has loaded it, through the SDK's createMcpHandler. Every request gets a fresh server, in both protocol eras:

  • A 2026-07-28 client (the revision with no initialize handshake and an envelope on every request) is served per request by the protocol's own design. It is answered with a JSON body, or an event stream when the reply needs one.
  • A 2025-era client (an initialize handshake) is served statelessly by the same factory, on an event stream that carries the one answer. There is no session: GET and DELETE are 405.

The handler checks no headers of its own, so http.ts checks them in front of it: the Host must be a loopback name (127.0.0.1, localhost or [::1]), and an Origin, when a browser sends one, must be a loopback origin too; anything else is 403. That is the DNS-rebinding protection, and it also turns away a page on another site that posts to the port. The handler itself answers 415 to a POST whose Content-Type is not application/json, and a 2025-era request 406 when its Accept does not take both application/json and text/event-stream, as the transport specification requires; an SDK client always sends both. A body that is not valid JSON is answered 400 with JSON-RPC -32700 (parse error), and one over the 4 MB cap 413 with -32600 - past the cap the rest of the upload is drained and discarded rather than the socket being closed under it, since resetting the connection mid-upload loses the very response the status code exists to deliver. The cap bounds what is held in memory, not what crosses the wire. The body is read before the handler sees it, so these are answered directly rather than by the SDK. Both messages are fixed strings - nothing derived from the underlying error reaches the wire - and -32603 ("Internal error") is left to mean a genuine handler failure, including a socket error while reading. That message is a fixed string too: the thrown error goes to the MCP log (src: "mcp", with the request path), not to the client. The handler answers a failure to build the server the same way (500, -32603, its own fixed "Internal server error"), and http.ts logs the cause at error. Stopping the server (MCP switched off in Settings, or the app quitting) first ends every exchange the socket's close would otherwise wait on, on both legs. What a 2026-07-28 client holds open is ended by the SDK: a subscriptions/listen stream lasts as long as the client likes, and a call in flight is cut with an empty response. Every 2025-era exchange in flight has its connection dropped (#3575), whether or not the cancel registry below holds it: no result and no JSON-RPC error is written, and the engine request behind it is aborted as a cancel would abort it. What the client sees depends on how far its answer got. Before any of the response is sent, an SDK client's call fails at once with a connection error. Once a progress event or a keep-alive comment (every 15 s) is out, the client is reading a stream that ends with no answer, and it holds the call until its own request timeout. Then the socket closes gracefully, so a request still arriving is answered rather than cut off. A connection still answering at that moment is closed once its answer is flushed, rather than held for its keep-alive timeout; one whose request is itself still arriving (an oversized upload drained for its 413) is only half-closed, and the stop waits for the client to close its side. The port is free when the stop resolves. One owner, lifecycle.ts, orders starts and stops (#3337): a stop that lands while the port is still binding waits for the bind and closes it, a re-enable binds only once the previous close has finished, and a service whose lazy load outlives its listener is never built. The per-request rebuild means Settings changes (allowlist, caps, disabled tools) take effect on the next request with no extra bookkeeping. Two things are carried from one request to the next, both for a 2025-era client and both under an Mcp-Session-Id the host issues: the client's name from its handshake (see How History names the client), and an abort handle for each of its requests still in flight, so a cancel it sends reaches the call it names (see What is live on each transport).

stdio CLI (Zed / headless / CI)

cli.ts is a standalone stdio server that reuses the same server factory and tool registry, through the SDK's serveStdio: one server per connection, for whichever era the client opens with. It is for stdio-only clients (Zed) and headless/CI. Run:

node dist-electron/mcp/cli.js

Configuration comes from environment variables (see Configuration), since there is no Settings UI. It still requires a running engine.

An open Vayu window sees a stdio session's writes. The CLI runs in its own process, so it has no mcp:data-changed channel to the renderer (see Lifecycle & IPC). It does not need one for the rows the UI edits: the engine publishes every committed write of a collection, a request, an example, an environment, the globals or a trash entry on its change feed (GET /changes, issue #3420), whoever made it, and the app follows that feed. A request a Zed session edits therefore shows in the tab that has it open, and a field the user was editing there is kept and flagged as a conflict rather than overwritten. What the feed does not carry - runs, cookies, engine config, local services, the OAuth token cache - reaches an open window on its own polls, or on the next read.

The CLI sets host: "cli" on its tool context (the app sets "app"), and every sentence that sends the user somewhere to lift a refusal reads it, so a guard in a stdio session names the variable that lifts it and never a Settings screen or the app (#2439): an allowlist refusal names VAYU_MCP_ALLOWLIST, a refused write VAYU_MCP_ALLOW_WRITES, an unreachable engine vayu-engine and VAYU_ENGINE_URL. The full pairing is under Configuration; the wording lives in remedy.ts and nowhere else.

Logging (#1558): stdout is the JSON-RPC channel, so every diagnostic goes to stderr as text, unconditionally - never gated by VAYU_LOG_CONSOLE the way the Electron-hosted host's console rendering is. Set VAYU_LOG_DIR to also write a JSON-lines mcp_<stamp>.log there (unset: console only) - its own prefix, since this process shares no file or data directory with the Electron main process. A call served through this transport and one served through the Electron-hosted transport each leave a src: "mcp" record; see Engine Logging.

What is live on each transport

Two things need the person or the client to hear from the server mid-session: a confirmation question before a destructive tool runs (elicitation), and word that tools/list changed when a Settings change alters it. That is any change to what the list answers, not only to which tools it names: the Reveal secrets toggle lists the same tools and rewrites their descriptions (a tool's withholding pointer is dropped with it, #2441), so it fires the notice too.

Client Confirmation question tools/list changed Cancellation
2026-07-28, HTTP ✅ asked in-band, the call retried with the answer ✅ on a subscriptions/listen stream ✅ the SDK aborts the call when the client cancels
2026-07-28, stdio ✅ asked in-band - (the CLI's config cannot change) ✅ notifications/cancelled, read by the SDK
2025-era, stdio ✅ the SDK puts the question to the client - (as above) ✅ notifications/cancelled, read by the SDK
2025-era, HTTP confirmed: true flag on the client's next tools/list ✅ notifications/cancelled, matched by the host

Only a client that declared elicitation is asked; any other client gets the confirmed: true flag instead, because asking one that cannot answer is a protocol error the tool cannot recover from. A 2025-era client over HTTP gets the flag even when it declared elicitation: the server that would ask is gone when its request ends, so there is no one to carry the answer back to. Neither fallback is unsafe, only less direct. tools.listChanged is advertised only to the clients with a ✅ under tools/list changed, so no client waits for a notice that never comes. See Design notes.

A cancel ends the call on every leg, with the same effect: the call's AbortSignal fires and the engine request behind it is aborted (the Cancellation bullet under Tools). On 2025-era HTTP the cancel is its own POST, and the fresh server it reaches never saw the call, so the SDK alone would answer 202 and drop it. The host keeps an abort handle for each 2025-era request it is serving instead (in-flight-calls.ts, #3574), under the Mcp-Session-Id it issued and the JSON-RPC request id, and a notifications/cancelled naming both ends that request's exchange, which aborts the signal; the cancel still gets its 202. A cancel with no session id, or another session's, reaches nothing: every client counts its request ids from 0, so the id alone names no one call. The handle is dropped when the exchange ends however it ends - an answer, a cancel, the client disconnecting, a stop - and at most 256 are held, the oldest dropped first (its call keeps running, no longer cancellable). A stop does not need the handle: it drops every 2025-era exchange, held or not. The issued session id is the whole binding: a loopback caller that presents it and a request id can abort that call.

The other way round, a collection's remembered data-file path (dataFile) is answered on HTTP only: the stdio CLI runs without the app, whose renderer publishes it to the HTTP server. See Data files. get_app_focus is the same shape: the open tab and environment are renderer state, so it answers an error saying the window is not connected on stdio.

How History names the client

Every run an MCP tool starts is sent with origin: {"kind": "mcp", "client": "<name>"} (#1817; the field is described under POST /execute): run_request, streaming or not, every request run_collection_smoke sends, run_collection, and both shapes of start_load_run. The name is the clientInfo.name the client gave - in its initialize handshake, or for a 2026-07-28 client on each request - forwarded as given: the engine trims it and caps it at 128 characters, and the renderer turns a known identifier into a product name through app/src/lib/mcp-client-names.ts. When no name is known the run carries {"kind": "mcp"} alone, and History shows it as an unnamed MCP client. The origin is set after every argument has been folded into the payload, so no tool argument can claim another one. It is metadata the client asserts, not identity.

How the name reaches the tool differs by era and transport:

  • 2026-07-28, either transport - every request carries it in its own envelope, so the server serving it reads it there.
  • 2025-era stdio - one server serves the whole connection and reads the handshake itself.
  • 2025-era Streamable HTTP - every request gets a fresh server, so the one that read the handshake is gone before the first tools/call. The host answers each initialize with an Mcp-Session-Id header and records the handshake's name under it, read from the request (the SDK's own schema check of the handshake decides that it is one); a Streamable HTTP client echoes that id on every later request, and the host looks the name up for that request's server (client-sessions.ts). The record is bounded: 256 sessions of at most 128 characters of name each, the least recently used evicted first, and one idle for 24 hours forgotten. The transport still validates no session, so a request with no id, or one the host does not know (a restart of the app clears the record), is served as before and starts an unnamed MCP run.

Tools

Every tool carries a category (surfaced in Settings for enable/disable), MCP annotations (readOnlyHint / destructiveHint / idempotentHint / openWorldHint + a display title), and a strict Zod input schema (arguments are validated by the SDK, and an undeclared one is refused; see Error results). Every read tool declares an outputSchema and returns validated structuredContent alongside the text rendering, except the three whose answer is not an object: list_environments and list_client_certificates answer a bare JSON array, and export_run_report answers the document's own text. An outputSchema is object-rooted, and reshaping those answers would break every agent that reads them. The read schemas are loose and name only the stable keys, so a field the engine adds still arrives; a non-object engine answer is wrapped as { "raw": ... } rather than refused, because the SDK reports a rejected result as a broken tool and hides the body. output-schema.conformance.test.ts fails a read tool that is on neither side of that line, and an exception that stops being true.

Argument names are uniform (#2446), held by schema-naming.conformance.test.ts over every tool's top-level inputs: an id is named for what it identifies (requestId, runId, entryId, itemId), never a bare id (no exceptions), and a limit comes with an offset. The one exception is listed in the test with its reason: get_live_metrics, which answers the tail of a ring buffer and so has nothing to page from.

The four categories partition tools by what they can do - and thus which gate applies: read (inspection; returns workspace data, with secrets withheld unless the user enables reveal - see Secret values, which also covers what a write tool answers and what a run output reads as), execute (has an effect outside this process without touching saved data - allowlist when it sends real traffic to a target, none when the effect is a loopback service the engine hosts, as for the mock issuer), write (mutates saved data or engine config - write toggle), load (starts/stops load tests - allowlist + caps + confirmation).

Tool Category Maps to Gate
get_engine_health read GET /health (structured) -
get_app_focus read The renderer's last snapshot over app:focus (app window only; no engine call) - (names and ids only: the open tab's type, entity id and label, and the active environment's id and name; an error saying the window is not connected from the stdio CLI or before a window has published)
get_safety_config read The session's McpSafetyConfig (no engine call, answers on HTTP and stdio alike) - (allowlist: { allowAll, hosts } with the hosts in full, caps: { maxRps, maxConcurrency, maxDurationSeconds, maxIterations }, gates: { allowWrites, allowNetworkSettings, revealSecretsToAgents } as booleans, and disabledToolCount; a count, never the names; no secret value, since none is part of the config; #2444)
list_collections read GET /collections?q=&limit=&offset= - (a page of the {data, pagination} envelope with pagination.nextOffset / note as list_runs, q matching the name; 50 rows by default, 500 max, refused above; each row a summary - id, name, parentId, order - unless fields: "full", whose whole rows have secret variables and auth credentials withheld unless revealed; a full row's declared data-file contract rides as dataSchema: { columns, fileName, declaredAt }; a collection with none has no dataSchema key, never the engine's {}; the file the app remembers for it rides as dataFile: { path, fileName, hash }, HTTP transport only - see Data files; a summary hashes no file)
list_requests read GET /requests?collectionId=&q=&limit=&offset= - (collectionId is optional: omitted, the page spans every live collection and each row's collectionId says where it lives, an empty one is an input error; fields: "full" without it reads the whole workspace on the engine; paged as list_collections; each row a summary - id, collectionId, name, method, url, order, updatedAt - unless fields: "full" asks for the whole stored row; auth credentials, credential-header values, a URL's password and credential query values, and credential params rows withheld unless revealed, on the whole row before the summary is cut, so a summary's url is masked by the row's API-key auth too)
get_request read GET /requests/:id - (the whole row, withheld as list_requests withholds a full row; an unknown id is a 404 error)
get_graphql_schema read POST /compose + POST /execute (transient) with origin: mcp allowlist on the composed host, and held by the engine to the URL it sends (targetPolicy); omitted environmentId is the active environment, "none" is none, an unknown id is refused; SDL capped at 256 KB, types to read it in parts; endpoint withheld as a saved request's url is
list_environments read GET /environments - (secret values withheld unless revealed)
list_runs read GET /runs?limit=&offset=&type=&status=&requestId=&collectionId=&q=&baseline= Page of the {data, pagination} envelope, newest first, as one JSON document also returned as structuredContent (pagination.nextOffset is the offset to read next, null on the last page, and pagination.note says so in words); 100 rows by default, 500 max (refused above, not clamped); rows carry a compact summary, endTime is null until the run is completed, failed or stopped, and a row includes a data-driven run's dataFileName / dataFileHash / dataFileCastNumbers (summary.scenario.* on a collection run - see Data files); a terminal load run's row carries resultSummary {rps, p95Ms, errorRate, verdict}, plus, on a load run that asserted or errored, assertions {exact, sampled, errored, teardownFailed} and assertionsPassed / assertionsFailed over its two populations (#2820, #3537: exact is assert.* outcomes, required extract.* misses and inline pm.test calls, sampled the deferred replay, never folded into errorRate), plus capacity {stopReason, maxHealthyConcurrency?, kneeConcurrency?} on a capacity run (#2930: the report's capacity headline, each level absent when the search did not find it) (errorRate a percentage 0-100, verdict absent when the run declared no budgets, each key absent when not recorded) a design run's {statusCode, latencyMs} and a terminal collection run's {passed, failed, skipped, errored, stopped, verdict} (#2954: its step outcomes, disjoint, errored apart from failed, stopped a step a Stop cut short and absent from a run stored before #3397; each key absent when not recorded, verdict absent when the run declared no budgets) (verdict is the stored budget verdict even for a stopped run, whose partial data the app shows as "Not judged", and so for a completed run whose drain a Stop cut, which carries drainCut {cancelled} (#3538: the requests left unanswered, absent otherwise); on a load row errorRate uses the same failure definition as the report's summary.errorRate, over the stored status-code distribution, and is omitted when none is stored); secret values and credential header values read <redacted> unless revealed
get_run read GET /runs/:id A projection, never the row: terminal, unknownStatus (true only for a status outside the engine's five, else absent), endTime (null until terminal), elapsedMs, progress (duration-bound runs only, else null), the config's mode / concurrency / targetRps / duration and a nextStep; no trace, result or other snapshot field; a 404 names the id
get_run_report read GET /runs/:id/report A run still pending or running returns the partial report with top-level partial: true and a note (absent for a terminal run; a status outside the engine's five is treated as unfinished and adds unknownStatus: true); a failed load run the engine could not fully record carries summary.partial: true (the last saved tick's counts, no latency block, peakConcurrency or avgQueueWaitMs - absent, not zero) or summary.summaryMissing: true (no summary: the counts are not whole-run totals, and again none of those three), both absent otherwise and unrelated to the top-level key (#2895); a completed run whose drain a Stop cut carries summary.drainCut {cancelled} (#3538: its figures cover only the answered requests, and the app shows it as "Not judged"), absent otherwise; on a collection run summary.totalRequests is requests sent and scenario.stepsExecuted is steps, so a skipped step is neither a request nor a failure, and the load-only figures (sendRate, throughput, the byte counts, peakConcurrency, droppedRequests, avgQueueWaitMs, the overheads) are absent rather than 0 (#2822); stored trace bodies capped at 32 KB per node, and 96 KB across the report; an inline script's element row (elements, a scenario step's or summary.elements) carries messages and console (the first 10 distinct each, an entry seen more than once with its count) with messagesDropped / consoleDropped, the sampled replay's failures are the results row whose trace.failures lists each distinct message once beside failureCounts, and its console lines are testValidation.console / consoleDropped (a scenario load run's per step, on scenario.steps[].tests) (#3127), all passed through as the engine sends them; secret values and credential header values read <redacted> unless revealed
get_run_samples read GET /runs/:id/samples?limit=&offset= 25 samples per call by default, 500 max, with pagination.nextOffset / note as list_runs; a load run captures every transport error, every completion at or above slowRequestThresholdMs and the first three of each status code, so a healthy 300-request run returns about three samples per status code (responseSamplePeriod / maxResponseSamples do not feed it); a body that is not UTF-8 text (or holds a zero byte) is base64 in body with bodyEncoding: "base64"; secret values and credential header values read <redacted> unless revealed
get_run_timeseries read GET /runs/:id/metrics?limit=&offset= Raw ticks, never maxPoints-downsampled; 100 ticks per call by default, 1000 max - the engine's own cap is 50000; pagination.nextOffset / note as list_runs; a tick's status_seconds (#2866) is passed through as the engine stored it - the responses that completed in the seconds the tick closed, by class, [] for a tick that closed none, absent on a tick stored before it
get_run_monitor read GET /runs/:id/monitor?limit=&offset= Same bounds and pagination.nextOffset / note as get_run_timeseries; raw samples, never maxPoints-downsampled
get_engine_config read GET /config - (a URL entry's credentials withheld unless revealed)
list_client_certificates read GET /client-certificates - (paths, format, hasPassphrase, and usable with a problem when the engine would not present the entry; the engine never answers a passphrase; an entry the user removed is in the Trash and not listed until restored, #2973)
get_live_metrics read SSE snapshot of last N ticks limit must be a whole number from 1 to 3000 (refused above, not clamped: 3000 is the stock live buffer, liveReplayWindowMs 300,000 ms at the 100 ms tick cadence), and there is no offset - it answers the tail of the buffer, so a page position has nothing to count from; the answer is {ticks, completed} (#2955): completed is the stream's own complete event, true once the run ended and false when the time budget ended the read with the run still going, and only when true a note says the final tick's latency window may be empty (its percentiles can read 0) and the run's percentiles come from get_run_report; a tick that closes a second carries statusSeconds (#2866, as the engine sends it: the responses that completed in each second it closed, [] for none), the others do not; a capacity run's ticks carry capacity (#2928, as the engine sends it: {level, levelElapsedMs, levelsJudged, stopReason?}, stopReason once the search has ended), other runs' do not; a streaming run's ticks carry streamEvents (so far), streamsOpen and eventsPerSecond, and the statusSeconds ones also streamTimeToFirstEvent (#3236, as the engine sends them: absent when not measured, never 0). Every tick carries phase (#3568, as the engine sends it: setup, sending, draining, summarising or settled; in draining the run's end has come and backpressure is the in-flight requests it waits out). The ticks that carry statusSeconds also carry cumulativeLatency / cumulativePhases (the run-so-far distributions) and, for a scenario load run, scenario (#2823: {iterations, iterationsCompleted, iterationsAbandoned, stepsExecuted, steps: [{index, name, executed, errors}]}, no latency; the final tick included). The engine keeps a run's live buffer liveRetentionMs after it ends (60 s by default); past that the call is a not_found that says the buffer expired and the run still exists, pointing at get_run_report (#2779)
compare_runs read 2× GET /runs/:id/report → diff (structured) baseRunId optional - omitted, it resolves the target's pinned baseline, through its saved request or, for a load run over a collection, its collection. Two runs of different types are refused, naming both. The result carries comparability: what made the two runs different experiments (see below)
export_run_report read POST /export/run-report (series: "none") The Export menu's document as its own text (not a result object): aggregates, budgets and, with baseRunId or baseline: true (not both; baseline resolves the pin as compare_runs does), a comparison; no traces, samples, per-tick series or request values - get_run_samples and get_run_report hold those. format defaults to markdown (plain GFM: verdict, run, headline numbers, latency against budgets, a streaming run's events, a capacity search's result, the contract's coverage and schema checks, a scenario's sequence and transactions, errors, comparison, warnings - the report's layout) and json is the document itself for a program; html is the Export menu's alone (a file for a person, with charts an agent cannot read) and is refused here, naming the Export menu, without asking the engine. A design or collection run, or one still executing, is an engine error; secret values read <redacted> unless revealed
run_request execute POST /compose (with requestId when no url is given - a saved request sent as the app's Send does) + POST /execute with origin: mcp (+ GET /runs/:id/events when streaming) allowlist, checked on the composed URL on either path and held by the engine to the URL it sends after any pre-request script (targetPolicy); omitted environmentId is the active environment, "none" is none, an unknown id is refused; headers is {name, value} lines or a string map, a repeated name sent once per line (issue #2466); response body capped at 32 KB; verifySSL: false refused - the downgrade belongs on a saved request; stream omitted on a send by requestId follows the saved request's Event stream setting, an explicit true or false wins, and an ad-hoc send streams only when asked (#3561); with write access off, persistVariables: false, so nothing a script or extractor sets is stored; the response and any streamed events read secret values and credential header values as <redacted> unless revealed
run_collection_smoke execute GET /requests?… (+ GET /collections when recursive) + POST /compose + POST /execute with origin: mcp (×N) runs one page of the list, limit (default 25, max 100, a larger value refused) from offset, and the result's requestTotal, hasMore, next.offset and note say what is left; allowlist per host, and again by the engine on each sent URL (targetPolicy); omitted environmentId is the active environment, "none" is none, an unknown id is refused before any row is sent; each row's url, reason, error and failing test lines read secret values as <redacted> unless revealed; every row's url (composed, skipped, send-error or compose-failure, where it is the stored one) also has a URL password dropped and a credential query value emptied unless revealed; sends a progress notification per row when the client sent a progressToken (index and status word only, never a name or URL)
run_collection execute GET /requests?… (+ GET /collections when recursive) + POST /compose (×N) + POST /runs with origin: mcp allowlist on every step - one step off it refuses the whole run - and held by the engine to each step's sent URL and OAuth 2.0 token endpoint (targetPolicy); omitted environmentId is the active environment, "none" is none, an unknown id is refused; optional data rows with dataFileName / dataFileHash / dataFileCastNumbers beside them, forwarded into the scenario block; optional thresholds budgets, the same argument start_load_run takes; optional maxStreamDurationMs / maxStreamEvents forwarded top-level to bound the steps whose saved request streams (#3235); the result's nextStep names get_run, the terminal statuses and the poll interval
diagnose_connection execute POST /diagnostics/connection allowlist; one HEAD, verification on, redirects off, 10 s deadline; answers which hop failed (outcome) and never a body or headers; proxy.url arrives from the engine without its user:password@ (#3258), which reveal does not change
create_collection write POST /collections write toggle; a blank or whitespace-only name is an input error, as on update_collection, and never reaches the engine (#3253); takes variables, auth and elements (extractors, assertions, timers, scripts) - preRequestScript/postRequestScript fold into script.pre/script.post sugar; returns the row shaped and withheld as list_collections answers it
update_collection write GET /collections (scan, when variables change or a script argument is given with no explicit elements) + PUT /collections/:id (merge-patch, with If-Match after that read; a 412 re-reads and merges once) write toggle; a blank or whitespace-only name is an input error, never sent to the engine (#3253); variables merges like update_environment's (a blank or whitespace-padded name is a 400 naming the key), removeVariables deletes names; elements replaces the stored list whole, script sugar folds into it; secret: false over a stored secret is refused unless revealed; returns the row shaped and withheld as list_collections answers it
delete_collection write GET /collections + GET /requests?… (×N) + DELETE /collections/:id write toggle + confirm; the engine stops every running mock of the subtree as part of the delete, for any client (#3449)
get_spec read GET /collections (scan, only for collectionId) + GET /specs/:id/meta, or GET /specs/:id with includeContent - (document text off by default and capped at 32 KB; a collection binding nothing answers bound: false)
diff_spec read POST /specs/diff + GET /requests/:id (×N, reveal off, one per entry with a headers, url or params change) - (each bucket - added, declined, removed, changed - capped at 50 entries, with summary carrying the true totals; declined lists operations whose request the user deleted, which sync_spec never re-creates; the per-entry draft is dropped; the current side of a headers, url or params change that could carry a credential withheld unless revealed)
preview_spec_bind read POST /specs/describe + POST /specs/match + GET /collections + GET /requests?… (×N) - (stores nothing; relays the basePaths describe answers to match, so literal-URL requests under a server's base path pair as the bind would (#3030); wouldClear names the requests a bind would strip of the operation they carry; lists capped at 50, counts true)
bind_spec write POST /specs/bind write toggle; one transaction - stores the document, moves the binding, stamps what matched and clears what no longer does
sync_spec write POST /specs/sync (policy: "safe") write toggle; one transaction - stores the document, moves the binding, creates and updates requests; deletes nothing, overwrites no hand-edited field and re-creates no request the user deleted, with skipped counting what it declined (declined for the last)
export_spec read POST /specs/export - (mode: contract by default, full to write every edit into a bound document; document text capped at 32 KB, with contentBytes for the true size; notes says what the export could not carry and how many credentials it left out in secretsOmitted)
export_postman read POST /export/postman - (credentials always written empty - auth, secret variables, and by name header, parameter, URL and cookie values - counted in notes.secretsOmitted; bodies and scripts are not judged; including them is a choice the app's dialog asks a person for; notes.notCarried names what Postman has no place for; document text capped at 32 KB, with contentBytes for the true size)
unbind_spec write GET /collections (scan) + PUT /collections/:id (openapi: null) write toggle; the document and the requests' recorded operations are kept; the returned row is withheld as list_collections answers it
preview_import read POST /import/parse - (stores nothing; import_document's own arguments; answers counts, names and meta, never the parsed tree)
import_document write POST /import write toggle; one transaction - every format the app accepts (OpenAPI 2.0/3.x, Postman v2.0/v2.1, a Postman environment or globals export, Insomnia v4, an Insomnia v5 collection or environment, a JMeter test plan), detected by content; meta.skipped names what the document declared and Vayu cannot represent (a no_server_url entry, an OpenAPI document with no servers, adds a sentence saying {{baseUrl}} is undefined and to set it with update_collection or update_environment; preview_import says the same); the caveat reads meta.folderCount and, when above 0, says the requests are filed under sub-collections and that recursive: true on run_collection or run_collection_smoke runs them all
create_request write POST /requests write toggle; takes the builder's whole surface - auth, followRedirects / maxRedirects / timeout / httpVersion / stream / verifySSL, elements (extractors, assertions, timers, scripts) - minus file body parts; a url given with no params is stored with one Params row per query pair, which the engine derives (#3551); headers is ordered {key, value, enabled?} rows (repeats and disabled rows kept) or a string map, and a row carrying valueWithheld: true is an input error naming the header, since nothing is stored for it to keep (#3550); the returned row is withheld as list_requests answers it
update_request write GET /requests/:id (when a script argument is given with no explicit elements, a headers row carries valueWithheld: true, or url or headers is given while reveal is off) + PUT /requests/:id (merge-patch, with If-Match after that read; a 412 re-reads and merges once, a second is a conflict with nothing written) write toggle; same fields, and only the ones named are written; a url given with no params has the engine bring the stored enabled query rows into line with it, keeping disabled and path rows (#3551); elements replaces the stored list whole, script sugar folds into it; with reveal off a url keeps each credential slot the read emptied and the call still holds empty (the userinfo password of the same user, a credential query or fragment pair by name and occurrence), naming each kept slot in a caveat line, while a slot removed or filled is written as given (#3549); headers (rows or map, as create_request takes them) replaces the whole list, a row written back as read with valueWithheld: true and no value keeping the value of the stored row with the same name (case-insensitive) and occurrence, one with no such row an input error naming the header and nothing written; with reveal off a write that leaves out a stored row whose value the read withheld still succeeds and names it in a caveat line (#3550); mockResponseMode / mockExampleId set which saved example a mock answers with, fixed refused without an example id; the returned row is withheld as list_requests answers it
delete_request write GET /requests/:id + DELETE /requests/:id write toggle + confirm
list_trash read GET /trash?q=&limit=&offset= - (paged as list_collections, each entry as the engine answers it; collections, requests, environments, saved examples and client certificates, whose name is host or host:port)
restore_trash_entry write POST /trash/:id/restore write toggle (not destructive - no confirmation); names the entry with entryId; a restored row is withheld as the read of it is; an environment comes back inactive; a request or saved example is refused with the engine's 409 (naming the item and the Trash entry to restore first) when its owner is in the trash, an example also when its request is gone or full, and a client certificate when a live entry holds its host and port
purge_trash_entry write GET /trash + DELETE /trash/:id write toggle + confirm (the prompt names the entry and what it holds - a collection's purge totals, an environment's variable count, a saved request's or example's name and owner, that a client certificate's registry entry and stored passphrase go while its files stay); names the entry with entryId
list_request_examples read GET /requests/:id/examples - (bodies capped at 32 KB each, 96 KB across the list; credential-header values withheld unless revealed)
create_request_example write POST /requests/:id/examples write toggle; always stored as origin: "user" - an agent cannot claim an import; headers is ordered {key, value, enabled?} rows (repeats and disabled rows kept) or a string map, and a row carrying valueWithheld: true is an input error naming the header, since nothing is stored for it to keep (#3550); the returned row has credential-header values withheld unless revealed
update_request_example write GET /requests/:id/examples (a headers row carries valueWithheld: true, or headers is given while reveal is off; there is no by-id read) + PUT /requests/:id/examples/:exampleId (merge-patch, with If-Match after that read; a 412 re-reads and merges once, a second is a conflict with nothing written) write toggle; origin is not writable; headers (rows or map) replaces the whole list, a row written back as list_request_examples returned it (valueWithheld: true, no value) keeping the value of the stored row with the same name (case-insensitive) and occurrence, one with no such row an input error naming the header and nothing written; with reveal off a write that leaves out a stored row whose value the read withheld still succeeds and names it in a caveat line; an example id the list does not hold answers not_found (#3550); the returned row has credential-header values withheld unless revealed
delete_request_example write GET /requests/:id/examples + DELETE /requests/:id/examples/:exampleId write toggle + confirm (the prompt names the example and the mock consequence); a soft delete for a saved (user) example - it goes to the Trash; an imported example becomes a spec-sync tombstone, not a Trash entry
move_item write GET /collections + GET /requests?… + POST /reorder write toggle; names the item with itemId; first / last only, over the destination's sub-collections and requests as one list, and a collection into its own subtree is refused before the engine sees it; a stamped request moved out of its spec contract comes back unstamped, its operation declined at the source (#3446); the renumbered rows come back withheld as the reads of them are
create_environment write POST /environments write toggle (the engine assigns the id; created inactive); a blank or whitespace-only name is an input error, as on update_environment, and never reaches the engine (#3253); the returned row has secret values withheld unless revealed
update_environment write GET /environments (scan) + PUT /environments/:id (fetch-merge, with If-Match; a 412 re-reads and merges once) write toggle; a blank or whitespace-only name is an input error, never sent to the engine (#3253); variables takes a string or {value, secret, type, enabled, description}, removeVariables deletes names; a blank or whitespace-padded name is a 400 naming the key (#3251); secret: false over a stored secret is refused unless revealed, and the returned row has secret values withheld
activate_environment write PUT /environments/:id (isActive), + GET /environments for "none" write toggle; one PUT - the engine deactivates the previous row in the same transaction; the active row is the environment every call naming no environmentId resolves and sends against; the returned row has secret values withheld unless revealed
delete_environment write GET /environments (scan) + DELETE /environments/:id write toggle + confirm (the prompt names the variable count); a soft delete - the environment goes to the Trash, inactive
get_globals read GET /globals - (answers an empty set, never a 404; secret values withheld unless revealed)
resolve_variables read GET /globals + GET /collections + GET /environments - composes, no single endpoint answers it - (omitted environmentId is the active environment, "none" is none, an unknown id is refused, the rule every send follows; secret values withheld unless revealed)
update_globals write GET /globals + POST /globals (fetch-merge, with If-Match; a 412 re-reads and merges once) write toggle; POST replaces the blob, so the read is what makes it a merge; a blank or whitespace-padded name is a 400 naming the key; secret: false over a stored secret is refused unless revealed, and the returned row has secret values withheld
get_cookies read GET /cookies?q=&limit=&offset= - (paged as list_collections, one cookie a row with its jar's environmentId, q matching the name or domain; a summary row is environmentId, name, domain, path, expires and never the value; fields: "full" adds the flags and the value, withheld unless revealed)
clear_cookies write DELETE /cookies[?environmentId=] write toggle; omitted clears every jar, null the no-environment jar, an id that environment's
set_run_baseline write PUT /runs/:id/baseline write toggle; one pin per saved request or collection (a load run over a collection pins for the collection), and a run of neither pins as a flag nothing reads; the returned run row reads secret values and credential header values as <redacted> unless revealed
delete_run write GET /runs/:id + DELETE /runs/:id write toggle + confirm
update_engine_config write GET /config (reveal off, a batch naming a key ending in url) + POST /config write toggle; the proxy* keys and customCaCertificates also need the network gate, and a batch naming one without it is refused whole; with reveal off a proxyUrl (or proxySystemUrl) equal to the read's credential-stripped value is written as the stored value, with a caveat line, so its user:password stays (#3549); any other value is written as given. /config has no If-Match, so that read and the write are not one conditioned step
start_load_run load POST /compose + POST /runs, or (with scenario) GET /requests?… + POST /compose (×N) + POST /runs; both with origin: mcp allowlist (also held by the engine, targetPolicy) + caps + confirm; omitted environmentId is the active environment, "none" is none, an unknown id is refused on both shapes (the app's load-test dialog advises about an off-network host where this gates: an info notice, Start never blocked); optional data rows (single target; their column names, the union across every row, go to POST /compose as dataColumns, so a bare {{email}} is bound from the row rather than answered by a same-named environment variable, #2956) or scenario.data (sequence), each with an optional dataFileName / dataFileHash / dataFileCastNumbers beside it at the same level; optional thresholds budgets (the maxAssertionFailureRatePct check judges the worse of the exact inline and the sampled pm.test populations and names both, #2892; streamTimeToFirstEventP95Ms and streamEventsPerSecondMin judge a streaming run's stream section and are not evaluated, so failed, on any other run, #3234) and monitor server-vitals block; headers is {name, value} lines or a string map, a repeated name sent once per line (issue #2466); mode is one of constant_concurrency (the default, or constant_rps when a positive targetRps is given and mode is left out) | constant_rps | ramp_up | iterations | capacity, a schema refusal naming the five otherwise, narrowed to constant_concurrency | ramp_up | iterations for a scenario; an omitted shape field is sent as the engine's default (see Load defaults); targetRps is constant_rps's alone, and a rate beside any other stated mode is forwarded for the engine's 400 to refuse (#2396); the recording knobs and comment below apply to both shapes, the redirect policy to a single target only; the confirmation preview states the effective shape in words ("constant_concurrency, 100 virtual users, closed loop, 60 s") above the planned payload; the result carries a nextStep field naming get_run, the terminal statuses and the poll interval, and a shape object with the resolved fields and closedLoop (single target and scenario alike); a single target's confirmation preview reads secret values as <redacted> and its auth credentials as <member>Withheld unless revealed
stop_run load POST /runs/:id/stop - (a load test, a collection run or a streaming send; a collection run's result has no summary when its worker has not stored one within the 5 s settle budget - read get_run_report then, #2822)
fetch_oauth2_token execute POST /oauth2/token allowlist, on accessTokenUrl and refreshTokenUrl; authorization_code refused before the call; the access token is never returned
get_oauth2_token_status read GET /oauth2/token?key= - (an absent entry is found: false, not a 404); the access token is never returned
clear_oauth2_token write DELETE /oauth2/token?key= write toggle; idempotent - deleted: false when nothing was cached
start_mock_issuer execute POST /mock-issuer/start - (loopback-only listener, so no allowlist entry applies); limits are the engine's - 31-day expiry, 60s slowMs, 32 clients, 8 concurrent issuers
list_mock_issuers read GET /mock-issuer -
stop_mock_issuer execute POST /mock-issuer/:id/stop - (unknown id is a 404, surfaced as a tool error)
update_mock_issuer execute PUT /mock-issuer/:id (merge-patch) - (live edit of failureMode / slowMs; an empty patch is refused before the engine sees it)
start_mock_server execute POST /mock/start - (loopback-only listener, so no allowlist entry applies); the latencyMs ceiling and the allowedOrigins rules are the engine's; a result with routesWithoutExample or duplicateRoutes above 0 (#3115) carries a caveat sentence after the JSON, so the 501s and the never-answering requests are not left to be found in the record
list_mock_servers read GET /mock - (running mocks only - a stopped one has no record)
get_mock_routes read GET /mock/:id/routes - (a start-time snapshot, constant under a running mock, except each row's hits count); a request sharing a method and path with another carries shadowed: true and shadowedBy (#3115)
get_mock_activity read GET /mock/:id/activity?limit=200 - (the {data, pagination} envelope with pagination.nextOffset / note as list_runs, newest first, 50 rows by default, 200 max; the route has no offset, so the tool reads the engine's whole 200-entry ring and slices it - exact, not a truncation, and a mock logging between two pages shifts offset by what arrived; discarded when the mock stops, and re-fetched to see new entries rather than pushed; secret values read <redacted> unless revealed)
stop_mock_server execute POST /mock/:id/stop - (unknown id is a 404, surfaced as a tool error)
start_webhook_inbox execute POST /inbox/start - (loopback-only listener; bind / confirmNonLoopback are never sent; the allowedOrigins rules are the engine's)
list_webhook_inboxes read GET /inbox -
stop_webhook_inbox execute POST /inbox/:id/stop - (frees the port, keeps the record and its captures)
delete_webhook_inbox write GET /inbox + DELETE /inbox/:id write toggle + confirm (the prompt names the capture count)
get_inbox_captures read GET /inbox/:id/requests?limit=&offset= 25 captures per call by default, 100 max, with pagination.nextOffset / note as list_runs; each body capped at 32 KB (a body that is not valid UTF-8 arrives as bodyEncoding: "base64" and is cut in decoded bytes, #3109); secret values and credential header values read <redacted> unless revealed
clear_inbox_captures write DELETE /inbox/:id/requests write toggle
update_inbox_response execute PUT /inbox/:id (merge-patch) - (live edit of the canned reply)

Notes:

  • start_load_run requires confirmation - a question to the person when the client can be asked, otherwise a confirmed: true flag (see What is live on each transport) - and enforces the RPS / virtual-user (concurrency) / duration caps. In capacity mode the virtual-user cap bounds the search's ceiling (concurrency) and its starting level (startConcurrency), which is what stops an adaptive run from outgrowing it; sloMs and stepDuration are that mode's own two fields, and get_run_report returns the search's findings under capacity, including each level's errorPct and samples (the completions its p99 was read from; 0 means it measured nothing), the kneeErrorPct and the maxErrorPct limit a level breaches above, beside the p99s. A plateau stop also carries saturationConcurrency, saturationRps and saturationP99Ms, the level where throughput stopped growing. Every shape field the agent leaves out is sent as the engine's default for the mode (Load defaults), so the caps judge the run that will start, the confirmation preview states it in words ("constant_concurrency, 100 virtual users, closed loop, 60 s") with the resolved fields in its planned payload, and the started result's shape object carries the same fields. get_live_metrics is a bounded snapshot (SSE read with a time budget), not a stream - tools/call stays request/response. The engine drops a run's live buffer 60 s after it ends by default (liveRetentionMs); the answer after that is the expired-buffer sentence described under Error results, not the engine's body. The answer carries completed beside the ticks, so a run that finished is told apart from a read that merely ran out of budget (#2955).
  • What a load run keeps is settable too (issue #760), which is what the MCP surface was missing rather than any part of the load shape: successSamplePeriod (the engine's success_sample_rate - a period, keep 1 in N, not a percentage; the argument is named for what the value means and the payload key stays the engine's), slowRequestThresholdMs, saveTimingBreakdown and comment, plus the two that size the population of the sampled replay (#2447, #3555): responseSamplePeriod (response_sample_rate, a period too, 1-100000, engine default 100) and maxResponseSamples (max_response_samples, 0-1000000, engine default 1000; 0 keeps none) bound the responses kept for postRequestScript, stored scripts and schema checks, whose outcome is the report's testValidation and schemaValidation. They do not feed get_run_samples, which reads the errors, the completions at or above slowRequestThresholdMs and the first three of each status code. A kept response is a full body in memory until the replay has run, so the count is held to the Max response samples cap (Safety config), and the confirmation preview shows both keys in its planned payload. All of them reach a scenario run too: both executors read them off the one RunContext, and comment is lifted into the run summary and the report's metadata.configuration whichever produced the run. Bounds mirror validate_run_config, so a value the schema accepts is one POST /runs accepts, and an absent knob stays absent - each has an engine default a stated value would overwrite. The redirect policy (followRedirects / maxRedirects) belongs to the request half instead: it rides through POST /compose beside the method and the body, overriding a saved request's stored policy or supplying the only one an ad-hoc target has. A scenario run refuses both by name, as it does every other single-target field - each step keeps the policy stored on it. maxRedirects is bounded 0-100 here because POST /runs has no guard of its own and the value becomes the redirect limit, where a negative means unlimited. The tool exposes no per-run timeout, and that is not an omission: POST /runs accepts one, but a run started here takes the timeout of the request itself. A run started by requestId sends with the stored request's own timeout when it states one (issue #2937), because POST /compose writes it into the payload the run is started from; otherwise, and for an ad-hoc target, it takes the defaultTimeout setting (resolve_request_timeout_ms), which update_engine_config changes - the run's OAuth 2.0 token fetches and every pm.sendRequest its scripts make included (issues #2833, #2841). Four transfers keep bounds of their own: a stream ends on its idle timeout and its duration and event caps, never a whole-transfer deadline; the import fetch has its own 30 s and stall timeout; the connection test its 10 s; and the server-vitals monitor its scrape timeout. Recorded here so it is not re-derived as a gap each time the schema is read.
  • An agent can bind a collection to a spec now, export one, ask whether a contract has drifted and apply the safe half of that drift (issues #862, #855 and #871) and import a document outright (issue #877). get_spec says what a collection is bound to, diff_spec says what a re-fetched document would change about it, sync_spec applies the part of that a caller with no opinion should apply, bind_spec binds one, export_spec writes it back out as a document, and unbind_spec detaches it. bind_spec takes the document text and nothing else - no pairing
  • because everything it needs is engine-side after #761's phase B: the engine reads the document (issue #853), derives both indexes from it - the operation index and the response-schema index, dialect translation included (issues #629, #628, #860) - and matches the collection's subtree against the index it just derived, through the same core::operation_match.hpp rule POST /specs/match previews with. So a document an agent sends as bytes reports coverage and validates responses, with no OpenAPI reader on the agent's side, and POST /specs/export owns the assembly that sends one back. A bind writes identity in both directions, which is what kept the tool out through phase A: re-binding to a different document clears every stamp that document does not account for, because coverage resolves a stamp by operationId and a surviving one claims the wrong operation rather than none. The tool result reports cleared beside stamped for that reason - it is the half a caller would otherwise discover from a later run. unbind_spec still leaves stamps alone, so unbind-then-rebind of the same document costs nothing.
  • import_document is the fourth verb, and the one that took a parser move (issue #877). Every other spec tool had shipped while this one could not: POST /import/apply takes a parsed tree, and the four parsers that built one lived in the renderer, so an agent could bind, diff, sync and export a contract and not import a document. They are engine-side now - core/import_document.hpp, reading through the same core::read_document that answers what a stored document declares - so the tool sends bytes and options and nothing else, and detection is by content rather than by a format argument a caller could get wrong. POST /import is the parse, the flattening and POST /import/apply in one call: the tree lands atomically, and the globals a Postman globals export carries are merged afterwards rather than written over, because POST /globals replaces the whole set and must not run in front of a write that can still fail. The caveat sentence names meta.skipped for the reason diff_spec names userTouched: an import that dropped a WebSocket request, an unsupported body or an operation's default response looks exactly like one that had none. A Postman script that calls an API Vayu does not run (require() of anything but crypto-js, uuid, lodash, moment, csv-parse/lib/sync, xml2js, chai, ajv and tv4, a bundled library such as cheerio) imports and throws at first run, so meta.unsupportedScriptApis (issue #2576; [{request, names}], absent when empty) names those requests in both tools' result, meta riding whole. External $refs are not followed - resolving one means fetching a URL or reading a file beside the document, which is the import dialog's business (a URL proxy and a gated IPC), so a multi-file spec imports whole and says nothing about the files it names.
  • diff_spec is the read half of a sync (issue #871). It sends the collection and the candidate document and nothing else: the requests and the bound document are the engine's to read, because a caller that could supply the "previous" side of a three-way comparison could turn its own edits into the document's. Three things about the answer are this tool's rather than the route's. The per-entry draft is dropped - it is what an apply would write, and POST /specs/sync re-reads it off the document it stores rather than being handed it, so nothing on either side of the tool consumes it; the rendered current / next pair, which is what says what moved, survives. Each bucket is capped at 50 entries while summary keeps the engine's true totals, so a document that renamed every operation comes back described rather than whole. The declined bucket (issue #3031) is the operations whose request the user deleted: shaped like added, counted in summary.declined, and described in the caveat sentence as the user's call rather than an omission. It is the same entries the Spec tab lists unticked, and no MCP tool can tick one - sync_spec takes no rows, and the person brings one back in the app. And a field flagged userTouched is named in the caveat sentence, not just carried in the JSON: it is the one part of a drift an apply may not take silently, and an agent reading "6 changed" would otherwise propose overwriting somebody's edit.
  • sync_spec applies a drift, and does not let the agent choose which of it (issue #871). It sends policy: "safe" and nothing else: the engine works out the rows from core::safe_spec_apply, the same function whose answer diff_spec reports per entry as safe / safeFields. That is the whole design. Which of a drift is safe to write - every operation the document adds (never one whose request the user deleted, issue #3031), every field it moved that nobody had edited by hand, no deletions, and a request whose bound document could not be read left alone whole - used to live in the renderer alone (spec-apply.ts, defaultSelection), which is why applying a drift was app-only through phase 1: electron/ may not import src/, so any tool would have needed a copy, and a copy of that rule is a second opinion about which of a user's fields a sync may overwrite. The rule moved engine-side instead, and defaultSelection now reads the marks rather than deriving them, so the Spec tab's pre-ticked boxes and an agent's sync are one answer. A person who changes a tick still sends explicit rows - a choice a person made is not a policy. The tool result's skipped (requests untouched, fields not written, deletions not made, declined operations not re-created) is named in the caveat sentence for diff_spec's reason: a caller that stated no ticks cannot see what it did not tick, and "5 updated" alone reads as "applied the drift".
  • A report read mid-run says so, and get_run is the status read (#2436). The engine answers GET /runs/:id/report for a run that has not finished with the numbers accumulated so far: a load run's live counts (no latency block and no results[] rows until it ends, #2659), zeros elsewhere, no budget verdict, nothing in the report itself that tells it apart from a finished run that measured the same. get_run_report therefore adds top-level partial: true and a note when metadata.status is pending or running (after the withhold and the trace bounds, so a report that took the bounds' early return is marked too) and leaves both keys out for a terminal run, so the key's presence is the whole signal. get_run is the cheap read for "is it done": terminal comes from the status, never from endTime. Both reads classify the status through one function (classifyRunStatus, derived from the five statuses list_runs filters on), and a status outside them is treated as unfinished by both, never as finished (#3339): get_run answers terminal: false, unknownStatus: true and a nextStep saying the status is not one Vayu recognises (read again, or stop_run, which bounds the polling), and get_run_report marks the report partial: true with unknownStatus: true and a note naming the status. unknownStatus is absent for a recognised status, never false. The engine emits no such status today; metadata present with no string status counts as one, and a report with no metadata object is handed back as it came. The engine stores end_time as startTime on a row that has not started (a seed kept for a run a crash kills) and as 0 on a running load or collection run (#3340), but emits endTime: null for a pending or running run (#2953), so get_run, list_runs and the report all agree; the status is still the signal that survives an engine that predates that. A failed load run the engine could not fully record is a different statement, made inside summary and not to be read as the top-level partial (#2895): summary.partial: true is a run reconciled after an engine crash, whose counts, errorRate, statusCodes, avgRps, duration and bytes are the last saved tick's (a floor under the real totals) while latency is absent, not zero (#2938), and peakConcurrency and avgQueueWaitMs are absent, not recorded (#2963); summary.summaryMissing: true is a failed run with no summary at all (a crash before the first tick, or a worker failure), whose counts are not whole-run totals (a sample's, often 0) and no latency block, peakConcurrency or avgQueueWaitMs is written. Both are absent otherwise, never false; the tool description and outputSchema name them, and a failed run's get_run nextStep points at them. The app draws the same two reports as a notice and "not recorded". progress is elapsedMs / plannedDurationMs clamped to 0..1 for a run whose stored duration parses and whose mode is not iterations, and null otherwise rather than a guess. The poll interval in its nextStep, and in the nextStep the three start results carry (start_load_run for a single target and for a scenario, run_collection), is one function: a tenth of the planned duration between 2 and 10 s, 5 s when there is no duration to take a tenth of.
  • get_run_report carries contract coverage for a run of a collection bound to an OpenAPI document (issue #629): which of the contract's operations the run exercised, which of their declared responses it saw, and any statuses the document never declared, under coverage. Passed through verbatim - the tool adds nothing. Absent, never zeros, for a run that was not measured against a contract, so an agent must branch on the key's presence rather than reading a zero as full non-coverage.
  • Bodies are bounded before they reach an agent (issue #767). run_request and get_run_report were raw passthroughs, and no engine cap covers this case: maxResponseBodyBytes bounds load runs only ("Design-mode sends are not affected"), maxTraceBodyBytes is 5 MB, sized for the database and a human reading one full trace, and maxDesignResponseBodyBytes (issue #1157) does bound a design send but at 32 MB, three orders of magnitude past what a tool result can carry. So a single ordinary page fetch answered with 1.3 M characters and blew the tool-result token limit outright. Both tools now cap a body at 32 KB - maxSampleBodyBytes, the engine's own answer to how much of a body an automated reader gets, rather than a new number. What a cut looks like, in the engine's existing vocabulary (cap_node_body, run_samples_response): bodyTruncated: true beside the full size, in bodySize on a run_request response and bodyBytes on a stored trace node, and rawRequestTruncated / rawRequestBytes for a cut wire message - whose headers are always kept whole, since the Cookie line libcurl attached appears nowhere else. A cut bodyRaw comes back with its parsed body as null, because the two carry the same payload and an intact body would return in full exactly what was just dropped. Quote bodyRaw, not body: bodyRaw is the received text, while body is its parse, with keys sorted and a repeated key reduced to its last value. A trace the engine had already truncated keeps the original size the engine recorded. Under the bound, nothing is added and nothing is changed. A body that is not UTF-8 text is base64 (issue #2458): the live answer's bodyEncoding is always present, "utf8" or "base64", and a stored trace's response node carries bodyEncoding: "base64" only when it applies (absent is text). A base64 body is bounded by the bytes it decodes to, not by its text, and is cut on a whole 4-character group (the engine's cap_base64_node_body rule), so the prefix still decodes; bodySize and bodyBytes count decoded bytes and bodyEncoding is kept. Both tool descriptions tell the agent to decode such a body rather than read it as text. bodyCapped on a run_request response is not this (issue #1157): it is the engine's own flag, always present, saying it stopped reading the response at maxDesignResponseBodyBytes, so bodySize is the prefix it read and re-sending returns the same amount - only raising that config entry changes it, where bodyTruncated says the full body is still in the app's history. It is passed through untouched and both can be true of one response. Load-run reports are unaffected: a load run's results never go through build_result_trace, so they carry no trace node at all, and its captured bodies live behind GET /runs/:id/samples, which has always truncated and disclosed this way.
  • The traces are bounded as a set, not only one at a time (issue #769). Capping each node does not cap the report: /runs/:id/report returns up to 100 rows for a single-request run (every stored step for a scenario run, bounded by maxScenarioStoredSteps) and each may keep 32 KB on each of three nodes, so a 100-step scenario measured 3.3 M characters with every node honestly flagged as truncated - 2.5x the size that failed in #767. At that row count truncation is no longer the binding constraint: 100 steps of an 8 KB body, under the per-node cap and so never touched, still totalled 845 K. So get_run_report also holds the traces to 96 KB in total - MAX_INLINE_BODY_BYTES * 3, the largest single row the per-node bound can produce, rather than a new number beside it. Rows past the budget keep every scalar (id, status, latency, step identity) and carry traceOmitted: true in place of their trace, with tracesOmitted and traceBudgetBytes on the report. Non-passing steps spend the budget first, matching ScenarioStepStore::add's own rule for stepsStored, so the two do not disagree about which steps matter - and the rows come back in run order regardless, since the budget decides what a row carries, never where it sits. The first trace is always embedded whatever it costs, so a design run's single-row report never comes back empty. The rows themselves are not capped further: at ~200 bytes of scalars each they are noise beside one body, and the run's shape is the answer even when the payloads cannot come along. Bounded sizes for the fixtures above: 33 K characters for the single 1 MB row, 76 K for 100 steps x 1 MB, 120 K for 200 rows with all three nodes populated (24.7 M unbounded).
  • start_load_run's stream flag consumes each response as a text/event-stream (issue #576), with maxStreamDurationMs and maxStreamEvents bounding one stream. Both caps are forwarded verbatim on the thresholds precedent - their ranges are the engine's, and re-deriving them here would be a second copy to keep in step (shared with run_collection, where they need no flag, #3235) - and the tool states no stream of its own when the agent named none: a run by requestId keeps the saved request's Event stream setting, which the by-id compose carries (#3561), as the app's load run does, and an ad-hoc run sends no stream key, because the engine refuses a cap without the flag. Worth telling an agent explicitly: reaching either cap completes the stream successfully, so a streaming run's 0% error rate is not evidence the caps were never hit - get_run_report's stream.capped is what answers that. The report's stream section also carries the per-completion event distribution, a derived eventsPerSecond and timeToFirstEvent (issue #3234), the wait from submit to each stream's first event, which timingBreakdown.phases.firstByte does not measure: it ends at the response headers.
  • start_load_run's monitor block scrapes the target's own metrics endpoint for the life of the run (url, optional intervalMs and format, and the series names to read), so an agent asked why a target slowed down can read its CPU on the same timeline as p99 - the report comes back with a monitor section carrying per-series min/max/avg, the sample count, and the missed scrapes split by cause: failures (no 2xx answer, the latest cause in lastError) and noMatchScrapes (answered, but none of the names matched; a Prometheus name is matched bare, so a {label="..."} filter is a 400). The block is forwarded verbatim: its value ranges are the engine's (validate_run_config), and monitor.series' ceiling is the monitorMaxSeries setting, so a second copy of those bounds in the tool schema would refuse blocks the engine accepts the moment a user raises it. The monitor endpoint is a second host, and it takes the allowlist decision described under Safety rather than the target's check by extension. The engine holds monitor.url to the run's targetPolicy too (#3121), so a loopback or private host that decision exempts travels in the allowedHosts the run carries. The scrape needs no cap of its own: the monitor thread is joined when the run ends, so whatever bounds the run bounds it.
  • compare_runs takes baseRunId optionally. Omitted, it resolves the run pinned as the baseline for whatever saved request the target ran - GET /runs/:id for the requestId, then GET /runs?baseline=true&type=load&requestId=<id>&limit=1 - which is the same lookup the app's history view makes, so an agent and the UI never compare a run against different references. A load run over a collection has no requestId, so it resolves through the configSnapshot.scenario.collectionId the same GET /runs/:id carries instead (collectionId=<id> in place of requestId=<id>, #3544); a run naming both resolves through its request. The newest pinned load run wins, so a pinned sequential run of the same collection never shadows it. Nothing to resolve through (an ad-hoc run with neither a saved request nor a collection), no pin for that request or collection, or a target that is the pin: each is a refusal naming the fix, never a silent comparison against some other run. export_run_report's baseline: true resolves the same way. Two runs of different types are refused too (#2438): a run_type entry in comparability makes the tool an error naming both runs, their types and list_runs' type filter, with no deltas, because a load test's throughput against a collection run's is not a regression either way. The compare_runs prompt embeds the same refusal in place of the comparison (runTypeRefusal, tools/run-housekeeping.ts). The History strip and the run-report export keep showing the entry. Every metric in the result carries a direction - lower-is-better, higher-is-better or neutral (total requests, which moves with how long a run was told to run) - so a reader can tell a regression from an improvement without knowing each metric's sense. A figure a run's report says the engine did not record is null on that side, with delta and pctChange null too (#2904): summary.summaryMissing (a failed run with no summary) nulls that run's summary.* metrics and its latency, summary.partial (reconciled after a crash) its latency alone. A zero there would read as a measurement. The result also carries comparability (#2162), which an agent reads before the deltas: a list of { code, message, base, target }, empty for a like-for-like pair, one entry per way the runs were not the same experiment. base and target are the two values already formatted ("20 s" against "3 s, stopped"). The codes, always in this order: run_type (#2438; design, load and scenario shown as the app names them, Send, Load test and Collection run; a collection's load run is load too, so it compares with a single request's load run without this entry), mode, concurrency (virtual users; for a ramp_up run its start level and ramp time too), target_rps, duration (the runs' measured summary.testDuration, in seconds, more than 2x apart), status (any two differing run statuses, such as Stopped against Completed), http_version (auto is unknown and never differs), data_file (by content hash; none against one counts), request (method or URL, the URL without userinfo, query or fragment because the comparison is not masked the way get_run_report is), compression (the same fact as compressionNegotiationDiffers, which stays) and expect_continue (#2516; Expect: 100-continue allowed or not allowed, an absent key reading as not allowed). When both reports carry metadata.runType, a mode, concurrency or target_rps only one of them recorded is a difference, its missing side not recorded; a report with no runType is from an engine that may not record them, and there a field a report does not carry is unknown, not a difference. The history view's vs-baseline strip renders the same list from the same computation (src/lib/run-compare.ts), so the two cannot disagree.
  • Run housekeeping (issue #755) is the History surface an agent could otherwise only page through: list_runs takes the engine's own filters (type, status, requestId, collectionId, q over the stored config, baseline) plus limit/offset, so finding one run is a query rather than a scan of 100-row blobs. Order is fixed newest-first - GET /runs takes no sort parameter, and the app's oldest-first view sorts client-side. collectionId matches a collection run and a load run over a collection (both store scenario.collectionId), never a single-request design or load run. The filters are Zod enums rather than passthrough strings because the engine ignores a type or status it cannot parse: forwarded raw, a typo would answer the unfiltered page and read as "nothing matched anywhere". set_run_baseline writes the pin compare_runs already resolved but nothing could set (the write half #472 never shipped), and delete_run deletes a run and everything recorded against it behind the same write toggle + confirmation delete_request uses. A run still executing is stopped engine-side and deleted only once its worker settles; a worker that does not settle in time is a 409 with the run intact, surfaced as "not deleted, retry once it reports a terminal status" rather than as a generic engine error. The call names the run, so a run pinned as a baseline is deleted too - unlike the app's Clear run history (DELETE /runs), which keeps pins (#2429); the tool description says so.
  • The stored-series reads are bounded on this side of the boundary. get_run_samples, get_run_timeseries and get_run_monitor default to 25 / 100 / 100 rows against engine defaults of 50 / 5000 / 5000: those defaults are sized for the dashboard's charts, which draw every point for a human, and an agent reads the same rows as JSON through a context window. The ceilings are 500 (the engine's own page cap, shared with GET /runs) and 1000 for the two series, well under the engine's 50000. A limit past a ceiling is refused, not clamped - the #319 precedent - because a short page silently substituted for the one asked for reads as the whole answer. A page with more behind it says so inside the JSON document, never in a second text block that would stop the answer parsing (#2445): pagination.nextOffset is the offset to read next (null on the last page) and pagination.note says the same in words, present only while hasMore is true. The same holds for list_runs and get_inbox_captures, and all five declare the envelope as their outputSchema.
  • The whole-list reads page in the engine and summarise here (#2443). list_collections, list_requests, get_cookies and list_trash forward q / limit / offset to the engine's paged list routes (50 rows by default, 500 max, refused above) and answer the same envelope, with the same nextOffset / note. The first three answer a summary row by default and the whole row with fields: "full". The summary is cut on this side rather than by the engine's GET /requests?fields=summary, because withholding must see the whole row first: a request's url is masked by reading its auth (an API key placed in the query), which a summary does not carry. Paging and filtering stay in the engine, so the rows a call reads are still bounded by limit. The engine client's unpaged reads (listCollections, listRequests, getCookies, listTrash) are unchanged, and the internal readers that need every row - a delete's cascade, move_item, the collection runs, the spec tools and vayu://collections - keep calling them.
  • update_engine_config reads the config back after applying and flags any changed key that needs an engine restart to take effect under restartRequired in its structured result (read from each entry's typed requiresRestart field, not from its label). Such values are saved, but the running engine keeps the old value until it is restarted, so the tool says so in its text output too.
  • The collection / request write verbs are the CRUD an agent needs to work unattended: create_collection gives it a collectionId to file new requests under, and update_request / delete_request let it correct or remove a request it got wrong instead of leaving the cleanup to a human. The two updates are merge-patches - the tool sends only the fields the caller named, and PUT /collections/:id / PUT /requests/:id keep everything else stored, so a patch naming just name cannot blank a url, an auth block or a script. A patch naming nothing is refused rather than sent as a write that changes nothing, and bodyType without body is refused too (the blob and its denormalized column move together or the two disagree about what the request sends). update_collection carries a collection's own state - name, description, variables, auth, both scripts - and never its position: re-parenting is move_item's job (below), because a move is a batch. The destination's siblings renumber with it, and POST /reorder is the write path that commits the whole batch or none of it; a PUT writes one row.
  • delete_collection cascades, so it reads the subtree first: GET /collections gives it every descendant through parentId, one GET /requests?collectionId= per collection in that subtree gives the request count, and those counts are what the confirmation states. An unreadable subtree - or an id no collection has - is a refusal, never a prompt carrying a number nobody verified. delete_request reads the row the same way, so the prompt names the request and its URL rather than an opaque id.
  • The Trash tools (issue #1071) close the loop those two deletes open, and the one delete_environment opens since #2970 and the one delete_request_example opens for a saved example since #2971. A client certificate joins them in #2973 although no tool deletes one (the user removes it in Settings): its entry is kind: "clientCertificate", named by its target, a root with parentId null and both counts 0. list_trash answers a page of GET /trash (#2443), each entry unchanged - roots only, with collections / requests counting what each entry's delete took (what a restore puts back) and purgeCollections / purgeRequests counting what a purge would destroy under it (#3449), an environment entry carrying variables, an example entry carrying its request as parentId, and a request or example entry carrying its owner's name as parentName, exactly as the route documents. restore_trash_entry is the one write tool here that is not destructive - it puts a row back rather than removing one - so it carries the write toggle alone, with no confirmation step; it surfaces the engine's own 404/409 text verbatim instead of writing a second sentence that could disagree with it, and reports reparentedToRoot in its result text when a restored collection came back at the top level because its parent is gone or itself in the trash; a restored environment comes back inactive, and activate_environment is what makes it the active one again. A request or saved example whose owner is in the trash is refused with the engine's 409 text, which names the item and the Trash entry to restore first by name and id (#3449); so is an example whose request is gone or already holds the 100 examples a request may, and so is a client certificate while a live entry holds the same host and port. purge_trash_entry is the Trash's own hard delete and is gated exactly like delete_collection: it reads the entry off GET /trash first, so the confirmation prompt names what a mistyped id would otherwise destroy sight unseen (a collection's sub-collections and requests, counted by the purge totals so an earlier delete's rows under it are included, #3449; an environment's variable count; a saved request's or example's name and the collection or request it came from; a client certificate's registry entry and stored passphrase with its files untouched), and an entry the trash does not hold - or one of a kind this build does not know - is a refusal before any prompt is shown. Both name the entry with entryId, not a bare id (#2446: an id beside requestId / runId / environmentId reads as "the id of something else"). A call that sends only id is refused with "entryId" is required. (the alias was retired in #2962).
  • A saved request an agent writes is the one the builder writes (issues #759, #795). create_request / update_request carry the request's auth block and the six Settings tab fields (followRedirects, maxRedirects, timeout, httpVersion, stream, verifySSL) as well as its url, headers, body and both scripts, so an agent that can send an authenticated request can now save one. The auth input is the same schema run_request takes rather than a copy of it - one definition, four descriptions - which is what lets an agent read a request's auth over get_request (or list_requests with fields: "full") and write it back verbatim. Its mode is a closed set (bearer, basic, apikey, oauth2, inherit, none, noauth): the engine sends a request with an unknown mode and no auth at all, so a misspelling (Bearer, api-key) or a mode Vayu does not execute (digest, aws, ntlm, hawk, oauth1, edgegrid, jwt) is refused at the schema, with a message saying which, and omitting auth keeps what is stored. An apikey block places the key with in (header, the default, or query); a Postman-style addTo is refused rather than read as a header (#2477). Both the auth block and each setting follow the merge-patch rule the strings already did: named is written, absent is left alone, so an update that mentions only maxRedirects cannot hand a stored followRedirects: false back to the engine's default. timeout (issue #2937; milliseconds, 1-86400000, checked at the schema as the engine checks it) has one more state than the others: null on update_request resets it to "no timeout of its own", so the request sends with the defaultTimeout setting again, where an absent key keeps the stored value; create_request takes it absent or null for none. For verifySSL that rule is a security rule rather than a convenience: a defaulted true on an unrelated update would silently re-enable a certificate check the user turned off. The one exclusion left is deliberate: file body parts, which name a path on the user's machine an agent cannot choose for them. update_request also carries mockResponseMode / mockExampleId (issue #481 phase 3), the same setting the Examples tab's mode picker writes: fixed is refused before the engine is called when it names no mockExampleId, exactly like the bodyType-without-body refusal above, and the change only takes effect the next time start_mock_server runs - a running mock's route table is a snapshot, not a live view of the request. Deleting the example it names (delete_request_example, or the Examples tab) clears mockExampleId engine-side (issue #3422). One that stops resolving another way is not refused retroactively; the mock server falls back to "first" at serve time, same as a fixed mode pointed at an example that never existed.
  • A skipped certificate check has to leave a record (issue #795). The stored verifySSL: false is writable over MCP; a per-call one is not. run_request declares verifySSL only so that false is refused by name - the refusal points at the two supported routes, adding the internal authority under Vayu Settings > Network & connectivity (verification stays on) or saving the request with verifySSL: false and running that. start_load_run, run_collection and run_collection_smoke take no such argument at all; they compose saved requests, so the stored field is what they honour. The difference is what survives the call: a stored value is a document the app's Settings tab shows unticked with a warning under it, get_request reads back and the user can undo, while an argument on one send is visible only inside the agent's own transcript. The allowInsecureTls safety toggle #795 sketched was rejected for the same reason it would have been convenient - it is a global permission, granted once for one dev host and then in force for every allowlisted host, where the stored field is per request.
  • Examples are writable, and where one came from is not (issue #759). list_request_examples reads what a request has saved beside it - what a mock server for its collection answers with - and the three write tools author it, so an agent that can start a mock (start_mock_server) can now author what it serves. The origin column is the one field no tool accepts: it says whether a row came from an importer (import) or from a person (user), and an OpenAPI sync replaces the first kind while leaving the second alone (#588, #655). An agent that could claim import would hand its own example to the next sync to overwrite, and one that could claim user could pin a stale imported row against the document it came from - neither is the agent's call, so create_request_example always stores user and the update tool cannot restate it. headers on the two write tools is an ordered array of {key, value, enabled?} rows or a string map (#3422). An example is a stored list and a captured response can repeat a name - several Set-Cookie lines are several rows - which a map cannot hold, so the rows are forwarded in order, a repeated key kept and enabled defaulting to true; the map is the short spelling, one value per name. A row that is not an object with a string key and a string value is refused by its position, unless it is a row as read with valueWithheld: true and no value, which keeps the stored value (#3550; see Secret values). A row may also carry the members a stored row has beside those, each a string: description, type (a Postman import's) and source (body-mode on the Content-Type row the app's Body panel or an importer wrote, legacy-default on a row the engine's repair pass disabled), forwarded as given, a kept row's included - a row written back without its source is no longer the app's own, so rows go back as read. Any other member is refused by name. Update replaces the whole list. The rows are {key, value}, unlike run_request's {name, value} lines, because they are the rows the engine stores and list_request_examples returns, not a request in flight. Bodies are bounded on the way out for the reason get_run_report's traces are (#767, #769): an example body is capped engine-side at 1 MB and a request may hold 100 of them. One over 32 KB comes back cut, flagged bodyClipped with its stored size in bodyBytes; once the list has spent 96 KB the remaining bodies are dropped with bodyOmitted and counted in bodiesOmitted, every row's scalars kept. bodyClipped is not the engine's bodyTruncated, which says the response was already cut when it was captured - two different facts, so two different names. delete_request_example says what the delete leads to by origin (#2971): a user example goes to the Trash, so its description, preview and prompt name list_trash and restore_trash_entry; an imported one is a spec-sync tombstone with no restore, and a row that states no origin is worded as an imported one, so the prompt never promises a restore the engine would not keep. The tool still confirms in both cases.
  • Collection-level state is writable, and merges the way an environment's does (issue #759). create_collection / update_collection take the variables, auth and elements that shape every request below them - the same list the composer walks (compose_elements runs the chain's elements before the request's own, issue #1514). preRequestScript / postRequestScript stay as sugar on these two tools (issue #1517): a non-empty string folds into a script.pre / script.post entry and an empty one removes it - never sent to the engine under those two names, which POST /collections / PUT /collections/:id refuse outright now that elements is the only script source. variables uses update_environment's input and its rules unchanged, including removeVariables and the "a new variable carries a value" refusal, because it is the same blob shape and a second dialect would be a second thing to learn. The read that makes each a merge is only done when it is needed: variables actually changing, or a script argument with no explicit elements (which needs the stored list to fold the sugar into without dropping the collection's other elements) - passing elements directly, like a plain rename, sends one PUT and nothing else. A collection never inherits auth (#3445): both tools' auth schema omits inherit and refuses it as an input error naming the modes that are accepted, and the engine refuses it too (400), so {mode: "none"} is how a collection stops being an auth source. run_request, start_load_run and the request tools keep inherit.
  • move_item is a bounded move, not a reorder (issue #759). It maps to POST /reorder, whose batch validates and commits under one acquisition of the engine's DB mutex (#386) - which is why re-parenting goes here rather than through PUT /collections/:id's own parentId. That PUT holds its own read to its write since #1440, so two concurrent moves no longer each pass an acyclicity check neither one's commit was visible to; what one row at a time still cannot do is refuse the pair together - the first move is committed by the time the second is rejected - or renumber the destination's siblings in the same write. What the tool offers is the row menu's "Move to…" (the moved row is itemId): a destination, and first or last among its new siblings. Positions in between stay a UI gesture on purpose - naming one means reproducing the app's ordering arithmetic (modules/collections/reorder-math.ts) from outside it, and getting it wrong is a folder that visibly reshuffles. The siblings are the destination's sub-collections and its requests, one order space (#2535, Ordering): the tool reads both lists and merges them with the sibling comparator (tools/sibling-order.ts, pinned to the engine's and the renderer's by tree-order-conformance.json), so last lands past every child of either kind and first ahead of them all. The batch states that list's whole arrangement, each row under its own type, rather than leaning on the engine's normalize pass, because normalization runs before the moves and would leave a row moved to the end of a list it is already in tied with the sibling it displaced; only the rows whose stored order actually changes get an entry. A collection may move to the top level (parentId: null) and a request always belongs to a collection. Moving a collection into itself or into its own subtree is refused here, walking the same tree the app's "Move to…" dialog walks, so the answer names the problem - the engine refuses the same batch under its lock, and that check stays the authority. A request that records a bound document's operation and lands, alone or under a moved collection, outside that binding's contract (another document, none, or a sibling collection bound to the same document), comes back with specOperation: null, and the operation is declined at the binding it left (#3446, as delete_request declines it), so that collection's next sync_spec does not create it again.
  • update_environment fetches the environment and merges the supplied variables (PUT /environments/:id replaces the whole variables blob), so partial updates preserve untouched variables and the name. The write is conditioned on the version it read (#2433): the PUT carries If-Match: W/"<updatedAt>" from the row the list answered, so a change the app or another client made in between is a 412 rather than a silent loss. On a 412 the tool reads the row again, merges the same arguments onto it and writes once more; a second 412 is answered as a transient error saying nothing was written, and repeating the call merges into the latest version. update_collection does the same whenever it reads (a variables or script edit); a call naming only stated fields reads nothing and sends no If-Match. update_request does the same whenever it reads (a script edit, a header row written back withheld, or a url or headers while secrets are withheld, #3549, #3550), and so does update_request_example (a header row written back withheld, or headers while secrets are withheld, #3550). Overwriting an existing variable changes its value only - its secret, type, createdAt and enabled/disabled state are preserved, so a rotated secret stays masked and a disabled variable stays disabled. The answer is the stored row, withheld as list_environments withholds it. It is a PUT, not a POST: since #95 the engine's POST /environments is create-only, and since #97 it rejects a body carrying an id outright. create_request and create_environment stay POSTs for the same reason - they create, and let the engine assign the id. No tool here sends an id in a body: on the PUT the path is the identity, a body id disagreeing with it is a 400, and on the POST any id at all is one.
  • The variables an agent writes are the flags it did not state (issue #758). update_environment and update_globals take each variable either as a string - set the value, keep every flag - or as an object {value, secret, type, enabled, description} whose omitted fields keep their stored setting (an entry as read also carries valueWithheld and createdAt, accepted and kept as stored, #3556), which is what makes secret and enabled reachable at all without a read-modify-write dance on the agent's side. Two rules make that safe rather than merely convenient: a variable the blob does not already hold (or holds malformed) must carry a value, so {secret: true} against a mistyped name is an error instead of a new empty secret variable; and a name in both variables and removeVariables is refused, because "set it and delete it" has no correct order and guessing one would apply half the call and report success. removeVariables is the delete a blank value cannot express - "" leaves the name resolving to an empty string - and a name that was not there comes back as a note on the result rather than an error, so a retried call does not fail on its own success. A blank or whitespace-padded name in variables is refused by the engine with a 400 naming the key (#3251); a legacy such key already stored is removed with removeVariables, spelled exactly as stored, and until it is every write that merges the blob fails on it. secret masks the value in the app and withholds it from every MCP read, write answer and run output unless the user enables reveal (see Secret values). Clearing it with secret: false is refused while reveal is off, since the next read would return the value; secret: true is always accepted.
  • Activation is one write, and "none" is the other direction. activate_environment sends isActive: true and nothing else: the DB layer clears the previously active row in the same transaction (deactivate_other_environments_locked), so a companion deactivate would be a second definition of the same rule. There is no "no environment" row to write true to, so "none" reads the list to find the row holding the flag and writes isActive: false to it - and when nothing is active it writes nothing, says so, and emits no data-changed event. The app follows either direction: useActiveEnvironmentRestore adopts whatever the engine reports, including a clear it has seen the engine hold a selection before.
  • update_globals has to read first. Globals is the one resource with no create/update split - one row, one id - so POST /globals saves the blob whole and an absent variables means {}, not "keep". The tool reads GET /globals and posts the merged result under the version it read (If-Match: W/"<updatedAt>", #2988), the conditioned read-merge-write update_environment does for the same blob-replacement reason, with the same one re-read on a 412 and the same transient answer on a second. An engine that never saved any globals answers updatedAt: 0, and W/"0" is a version like any other, so a first save is conditioned too.
  • clear_cookies has three scopes, not two. Omitting environmentId clears every jar, passing an id clears that environment's, and passing null clears the jar used when no environment is selected - the engine reads an absent query parameter and a present-but-empty one differently, so omitting and passing null are genuinely different calls (the renderer's apiService.clearCookies sends the same three). No confirmation gate: nothing saved is lost, only session state a re-login restores - which is why it is a write tool for the toggle and not one of the confirm-gated deletes.
  • run_collection_smoke runs each saved request once and returns a structured pass/fail matrix (2xx–3xx status + all tests passing = pass). Each request is composed exactly as the app's Send would (see Request composition below), and sent buffered even when its Event stream setting is on (#3561): a row is judged by its exchange, and a stream answers with a run id instead. A request whose scripts asserted anything carries a tests node - total, failed, and the failing name: message lines (issue #733) - so a row that fails on its tests says which, rather than leaving an agent with ok: false beside a 200. Both scripts count, and a pre-request assertion's line is prefixed [pre-request] (issue #810): it failed before the request went out, which is a different thing to go and look at. An assertion from a script the request inherits is prefixed with its level first - [collection] or [folder], so [folder] [pre-request] name: message (issue #2522) - because the request's own scripts are the wrong place to go looking for it; the request's own assertion carries none. The list is cut at ten, the number the engine caps a schema verdict's failures at, while failed stays the true count. A response that ran no assertions carries no tests node: none ran is not all passed. A request the engine could not complete (status: 0, a timeout, DNS or TLS failure) carries the engine's own account as error, "<errorCode>: <errorMessage>" (issue #3552), the field a thrown send already uses, masked with the rest of the row; an answer with no errorCode leaves it unset. For a collection bound to an OpenAPI document each row also carries a schema verdict (issue #681) and folds it into ok the way testResults folds: a response the document declares a schema for and that does not match it fails the request, with the failing JSON Pointers listed so an agent need not re-run to learn where. failOnSchemaError: false unfolds it (issue #720): the verdict still rides every row, it just stops deciding ok - useful against a document known to lag its API. It defaults to true here, where the same-named flag on POST /runs defaults to false, because this tool has folded since #681 and an agent reading its matrix would otherwise start seeing contract failures pass. run_collection offers the same flag with the engine's default (issue #766, Scenario runs below); one schema fragment words both, so the two can differ only in the unit they judge and the way they default. Only a checked verdict can fail a row - checked: false (no declared schema for the status or content type, a body that is not JSON) is reported and never counted against the run, and a collection bound to nothing carries no schema field at all. Requests whose host still can't be verified after resolution (e.g. a variable did not resolve and allow-all is off) are skipped, not sent. It runs a collection's direct requests unless recursive: true: GET /requests?collectionId= serves direct requests only, while collections nest via parentId, so a run on a parent folder tests none of its descendants. The result appends a note naming the sub-collections it left out (and says so explicitly if the collection list could not be read), because a matrix whose total silently excludes nested folders reads as a whole-collection pass. The note names both ways out: recursive: true here, and run_collection with recursive: true (preferred for a large tree: one stored run with a run id). recursive: true walks the tree through the same function run_collection's pre-flight does (walkCollectionRequests, scenario-runs.ts), so the rows come in the sidebar's order (#2535) and each names its folder, the collection names from the root down joined by /; a recursive run has nothing left out, so it carries no note, and a failed GET /collections is the engine error, with nothing sent. An OpenAPI import files its operations under sub-collections (grouped by tag or by path, per meta.folderStrategy), so a direct-only smoke of its root answers total: 0; import_document's caveat says how many sub-collections hold the requests and names the recursive path. Requests run serially, so a collection takes as long as its requests do added together, and each one is real traffic: past about 25 requests or against a slow API the description steers an agent to run_collection (one stored run with a run id, read with get_run_report), leaving the smoke for a bounded pass/fail matrix. A call runs one page (#2451): limit requests (default 25, max 100; a larger value is refused, not clamped, like every bound in this registry) starting at offset. The list - the direct requests, or the whole expansion of a recursive run - is read once in the engine's stable order and then sliced [offset, offset + limit), so a collection edited between two calls shifts the window under the second one (the description says so). total, passed, failed and skipped keep their meaning as the counts of the rows run in this call; the result adds requestTotal (the list's size, before the cut), hasMore, and - only while hasMore is true - next: {offset}, the offset that resumes. Whenever the call did not run everything in scope the result's own note field says so in a sentence (Ran 25 of 140 requests, starting at offset 0; call again with offset: 25 for the rest.), in the structured content and so in the JSON text block alike: a default of 25 that cut a collection quietly would read as a whole-collection pass. An offset at or past requestTotal runs nothing and the note says so (hasMore false). A call that ran everything carries requestTotal and hasMore: false and no note. Progress (below) counts the page, not the collection. A cancellation returns what finished. When the call's signal aborts mid-run the loop stops and the result carries the rows completed so far with cancelled: true, hasMore: true and next.offset set to offset plus the rows returned. The abort is told from a row's own send error by the signal, not by the error: an aborted fetch rejects like any other failure, but a send that fails with the signal still live stays a failed row and the run goes on. The request in flight at the abort is not a row, and next.offset points at it, so resuming sends it again; the note warns it may already have reached the API. The masking reads that follow the loop run without the aborted signal, since one that fails closes the call and would discard the rows. The SDK itself sends no response to a request whose signal aborted (a notifications/cancelled for it, or the connection closing), so the partial result is what a caller that reads the handler's return value gets - the tests, dispatchTool - and what the cancelled loop no longer does is walk the remaining rows, each a failed fetch the instant after the abort. That holds on every transport: on 2025-era HTTP the host matches the client's cancel to the call and ends its exchange, so no request goes out after the cancel there either (see What is live on each transport). When the client sent a progressToken (#2451) the call reports notifications/progress - 0/total before the first request, then one per row on every path (sent, skipped off the allowlist or failed to compose), with a message of the form 3/40 ok / 3/40 skipped / 3/40 failed. The message is an index and a status word and nothing the request resolved to: the masking that covers a row's url, error and test lines runs on the finished matrix (it needs the secrets a script set along the way), so a mid-run string has no such cover and carries none of that data. The notification goes out on the request's own stream (mcpReq.notify), not the session's, and a failed or post-cancellation send is dropped. A client with a short request timeout only benefits if it resets that timeout on progress (the TypeScript SDK's resetTimeoutOnProgress): a single POST /execute may take up to 310 s (the engine's 300 s ceiling plus the client's grace), so without it the client can give up on a run still working. A call with no token sends nothing.
  • The OAuth 2.0 token tools (issue #760) are how an agent gets a token problem named instead of discovering it as a wall of 401s inside a run: fetch_oauth2_token acquires (or force-refreshes) a token for a config and caches it engine-side, get_oauth2_token_status says whether an entry exists and whether it has expired, and clear_oauth2_token drops one. The config is the same block a saved request's auth carries, so it can be copied out of get_request verbatim; the cache key is the engine's (accessTokenUrl + clientId + credentialsId + username + the extra parameter rows the engine would send, a credential-named row such as client_assertion by its name alone, so the key never carries a secret), so configs differing only in scope share an entry and a distinct credentialsId is what separates them. Two rules here are security decisions rather than plumbing, and both are stated in the tool descriptions so an agent reads them before it reads a refusal. No tool returns access-token bytes. The engine is what applies a token to a request, so the bytes buy an agent nothing it can use through Vayu, while handing them over would turn a credential the user acquired into something an agent can carry off the machine; what comes back is the entry's shape - key, type, scope, expiry, whether a refresh token came with it - plus an explicit accessTokenWithheld, because an agent that finds no token and is not told why concludes the acquisition half-failed. And the authorization_code grant is refused before the engine is called, not merely because the browser exchange is one MCP cannot drive: acquire_token answers a cache hit before it looks at the grant, so a call naming a config that happened to match an entry the user authorized interactively would otherwise reach into it. The refusal names the app's Auth tab as the place to authorize, and the entry that lands there is the one these tools then read. The allowlist gate covers refreshTokenUrl as well as accessTokenUrl - a gate that read one of two URLs is a gate a config can walk around.
  • The mock-issuer tools let an agent asked to "test this auth flow" mint its own tokens: start_mock_issuer stands up a local OAuth 2.0 issuer and returns its issuerId, tokenUrl, authorizeUrl and signingKey, so the agent can point a request's oauth2 auth at the token URL, run_request it, and assert on what the target received - offline, with no real provider's 2FA prompts or rate limits in the loop. expiresInSeconds plus issueRefreshTokens is how the 401-then-refresh path is exercised, and failureMode is how retry handling is. No allowlist entry is needed and none is checked: the engine binds every issuer to 127.0.0.1 and takes no host for it, so an issuer is unreachable off the machine; the per-tool switch is what turns these off. The start body is forwarded verbatim under the engine's own key names, and the engine's limits (31-day expiry, 60s slowMs, 32 clients, 8 concurrent issuers) stay engine-side rather than being restated in the tool schema, for the same reason monitor's ranges are - a second copy would refuse values the engine accepts the moment either side moves. The schema owns the shape: a claims object, an integer port, a failureMode from the closed set. Stopping an issuer frees its port; tokens it already minted stay valid until they expire, since nothing verifies them against a live issuer. A running issuer is edited, not recreated: update_mock_issuer merge-patches failureMode and slowMs live (issue #757), so an agent can mint a token against a healthy issuer, flip it to server_error to watch the client retry, and flip it back without the token URL under test moving or the signing key changing. Those two are the only settings a bound listener will take - the engine refuses port, clients, claims and issueRefreshTokens with "stop it and start a new one", so the tool does not offer them at all rather than offering a call that always fails. expiresInSeconds is mutable engine-side and is also left out: a token's lifetime is fixed when it is minted, so changing it says nothing about the tokens an agent already holds. An empty patch is refused here rather than forwarded, because the engine accepts one and answers 200 - which would report a change that did not happen (the update_inbox_response precedent).
  • The mock-server tools are how an agent stands up the API a client under test expects, out of the collection's own saved examples (issue #757, over the engine's mock server from #481): start_mock_server binds a listener that answers each request's example - status, headers, body - and returns its mockId and base URL, get_mock_routes lists what it will serve, and stop_mock_server frees the port. latencyMs and errorRatePct are how a client's timeout and retry handling get exercised; 0 and 100 percent are exact by construction, in between it is a per-request roll. A started mock is not necessarily a usable one, which is why the result carries a caveat rather than leaving the counts in the JSON: a route whose request has no saved example answers 501, a path matching nothing answers 404, and a collection with no mappable requests serves nothing at all. Loopback-only for the same engine-side reason as an issuer - mock_server.cpp starts every listener on 127.0.0.1 with no host to configure - so no allowlist entry is needed or checked. A stop is a delete here, unlike an inbox: a mock records nothing, so its record dies with its listener and it simply leaves list_mock_servers. The route table is a snapshot taken at start and cannot change under a running mock (editing the collection means restarting), which is why the renderer holds it at staleTime: Infinity and a stop_mock_server event carries the mockId so that cache entry is dropped rather than refetched into a 404. Each row's mode, exampleName and hits are the exception - they read off the request's stored mock settings and the mock's own hit counter, so they can change between two reads of the same table even though the routes themselves cannot. get_mock_activity is the opposite of that snapshot: it is a log that grows for as long as the mock runs, newest first, so an agent watching a client under test calls it again to see what has arrived since the last read rather than trusting a cached copy - unlike the route table, which is worth fetching only once. It is capped at 200 rows per call (50 by default), pages with offset in the {data, pagination} envelope the other paged reads answer (the engine route takes limit alone and keeps 200 entries, so the tool reads that whole ring and slices it) and, like the route table, is discarded outright on stop_mock_server rather than kept the way an inbox keeps its captures. allowedOrigins (issue #2367) is which browser pages may read the mock's answers, the half of reach that "loopback-only" does not decide: a page open in the user's browser is on this machine. Absent or [] is the engine's default, any origin and never credentials; a list admits only those origins, with credentials. The schema says "array of strings" and no more - the count and length ceilings and what makes an entry an origin are the engine's, and a bad entry comes back as a 400 naming it (allowedOrigins[1]) - and the start result and list_mock_servers echo the canonical list. Fixed for the mock's life, like latencyMs.
  • The webhook-inbox tools are the assertion half an agent testing a webhook needs (issue #756): start_webhook_inbox stands up a local inbox and returns its URL, get_inbox_captures reads back what arrived - method, path, query, headers, body, caller address - and update_inbox_response changes what the sender sees, live, so one inbox can answer 200 for the first trigger and 503 for the next. Loopback-only, and not by policy alone: the engine's bind / confirmNonLoopback pair is never emitted by inboxStartPayload, whatever arguments a call carries, so an inbox MCP started cannot be reached off this machine - a stated non-goal of epic #753, guarded in the one function that builds the body and mutation-checked in tools.test.ts. A stop is not a delete: stop_webhook_inbox frees the port and leaves every capture readable, while delete_webhook_inbox destroys them and therefore takes the write toggle and a confirmation whose prompt names how many captures go with it (read from GET /inbox first, the way delete_run reads the run). clear_inbox_captures is the middle case - recorded data destroyed, listener kept - so it takes the toggle without the confirmation. No live stream: GET /inbox/:id/live is single-watcher (a second is a 409) and the app's own inbox tab may hold it, so MCP polls get_inbox_captures instead - the same bounded-snapshot posture get_live_metrics takes. Capture bodies are cut to 32 KB for the result with the engine's own bodyTruncated / bodyBytes disclosure kept intact (a body that is not valid UTF-8 carries bodyEncoding: "base64", is cut in decoded bytes so it stays whole base64, and is masked in its bytes like any other base64 body, #3109), since inboxMaxBodyBytes reaches 8 MB and a webhook payload is whatever the sender sent. allowedOrigins (issue #2367) is forwarded the same way as the mock's - an array of strings, validated by the engine, echoed canonical by the start result and list_webhook_inboxes. It is CORS policy, which browser pages may read the canned answer, and does not touch who can connect, so it sits beside the loopback guarantee rather than loosening it.
  • Cancellation: the AbortSignal the SDK hands each call fires when the client cancels it, and it is threaded into the engine fetch for every tool call, resource read, template list and prompt, so a client cancelling an in-flight call actually aborts it rather than leaving the engine request running detached. How the cancel reaches the signal differs by leg: over stdio the SDK reads the notifications/cancelled itself, a 2026-07-28 HTTP client's cancel is handled by the SDK itself, and on 2025-era HTTP the host matches the cancel to the call by Mcp-Session-Id and request id (see What is live on each transport). The one exception is the run-ID completion callback, which the SDK invokes as (value, context?) with no request context to carry a signal.
  • Timeouts: engine-local calls are bounded at 35s, but POST /execute waits on a third-party server, so its budget is derived from the engine's own defaultTimeout setting (read per call from GET /config, up to its 300s ceiling) plus 10s of grace - the same rule the renderer uses for its proxied calls. It is a worst case for the payload sent (#2836, electron/mcp/execute-budget.ts): the setting again when auth.mode is oauth2 (the token fetch has the same bound), plus the scriptTimeout setting (60s when unreadable) for every enabled script.pre / script.post element, because one call runs them in sequence. A request with neither keeps exactly the setting plus 10s. That way the engine's own TIMEOUT error, with its error code and its run row, arrives before this client gives up. If the budget does expire, the tool says the call may still have completed and what to check before repeating it, which depends on the tool (see Error results); it is never reported as an unreachable engine, because a retry could re-send a request that already went out. run_collection_smoke bounds the other side of this: a call runs at most limit requests (25 by default), so one call stays inside a typical client budget and a longer collection is resumed by offset rather than lost to a timeout. It also sends a progress notification per row when the client asks, which a client that resets its timeout on progress (resetTimeoutOnProgress) can use to outlast a slow API.

Naming what the user means

A user points an agent at an entity with a reference line, the text the app's Copy for agent puts on the clipboard:

Vayu <kind> "<name>" (<id>)

<name> is what the app calls the entity, for a person to recognise; the <id> in parentheses is the key every tool takes (requestId, collectionId, runId, inboxId, mockId). Look up the id, never the name: names repeat. An entity the app labels by something other than a name is named by that: an inbox, a mock server and a mock issuer by their port (a mock server also by its collection), a capture by its method and path.

Six kinds belong to another entity, so the line names that owner. A variable is its name in a scope - in environment "<name>" (<id>), in collection "<name>" (<id>) or in globals - and the line never says what it holds, nor whether it is secret. A spec operation is "<METHOD> <path>", the path as the OpenAPI document templates it (/pets/{petId}), then in collection "<name>" (<id>) and, when the document declares one, ("<operationId>"). A graphql operation is its name in the document, then in request "<name>" (<id>): the request's body holds the document, and the line never carries the query text, the variables or a header. A run sample is (<resultId>) of run (<runId>). An element is named by its own name, else its kind (script.pre), then of request "<name>" (<id>) or of collection "<name>" (<id>). A threshold is its budget key (latencyP95Ms, custom.<name>.<stat>), then of run (<runId>) or of request "<name>" (<id>). Look each up through its owner's id; the next section lists the call each feeds.

Most kinds add a tail after the id. in <A / B> places an entity in the collection tree, root first, and is left off at the root. - <detail> describes what the id alone does not: a run's kind, target, start time and status, a trash entry's kind. A " or \ in a name is escaped with a backslash and a line break becomes a space, so a name never ends its own quotes or starts a second line. A reference carries no value: a run's URL is cut to its path, with no query string or credentials, and no header, body, variable, token or secret is ever printed. A run comparison is the one multi-line reference, and the one with no quoted name: a header naming the two run ids, then each run's own line.

Every line below is the app's formatter (app/src/lib/agent-reference.ts) run over one fixture, the entities in app/src/lib/agent-reference.docs.test.ts, which fails when a line here stops matching its output. The run times are shown as en-US in UTC; the app prints the user's own locale and zone. A run exported as a file (POST /export/run-report) carries its line as run.reference with the start in ISO-8601 UTC (2026-10-05T08:10:00Z), since a file is read away from any one locale.

Vayu request "Create order" (req_3f9c1a52-7b0e-4d1a-9c55-0a1b2c3d4e5f) in Checkout / Orders
Vayu example "Created" (exa_2d4f6a81-3c5e-4b79-8a1c-6e8f0a2b4c6d) of request "Create order" (req_3f9c1a52-7b0e-4d1a-9c55-0a1b2c3d4e5f) in Checkout / Orders
Vayu element "Sign payload" (el_b4d6f8a0-2c1e-4a73-9b5d-7f9a1c3e5b70) of request "Create order" (req_3f9c1a52-7b0e-4d1a-9c55-0a1b2c3d4e5f)
Vayu collection "Orders" (col_4a6c8e02-9b1d-4f35-a7c8-1d3e5f708192) in Checkout
Vayu collection "Checkout" (col_8e2d4b17-1c3a-4f60-a9d2-5b6c7d8e9f01)
Vayu environment "Staging" (env_7c9e1b34-5d6f-4a80-b2c3-e4f5a6b7c8d9)
Vayu variable "baseUrl" in environment "Staging" (env_7c9e1b34-5d6f-4a80-b2c3-e4f5a6b7c8d9)
Vayu spec operation "GET /orders/{orderId}" in collection "Orders" (col_4a6c8e02-9b1d-4f35-a7c8-1d3e5f708192) ("getOrder")
Vayu graphql operation "CreateOrder" in request "Create order" (req_3f9c1a52-7b0e-4d1a-9c55-0a1b2c3d4e5f)
Vayu run "Create order" (run_5a7c9e21-4d3b-4a8f-b1c2-d3e4f5a6b7c8) - load test, POST /v1/orders, 10/5/26, 8:10:00 AM, completed
Vayu run "GET /v1/orders" (run_9d1f3b57-2e4c-4b68-a0d1-f2a3b4c5d6e7) - design run, GET /v1/orders, 10/5/26, 9:30:00 AM, failed
Vayu run "Checkout" (run_c3e5a7b9-1d2f-4c40-8e6a-0b1c2d3e4f50) - collection run, collection "Checkout", 10/6/26, 7:00:00 AM, completed
Vayu run comparison base (run_5a7c9e21-4d3b-4a8f-b1c2-d3e4f5a6b7c8) target (run_e8f0a2b4-6c7d-4e91-b3a5-c7d9e1f30415)
Vayu run "Create order" (run_5a7c9e21-4d3b-4a8f-b1c2-d3e4f5a6b7c8) - load test, POST /v1/orders, 10/5/26, 8:10:00 AM, completed
Vayu run "Create order" (run_e8f0a2b4-6c7d-4e91-b3a5-c7d9e1f30415) - load test, POST /v1/orders, 10/7/26, 8:10:00 AM, stopped
Vayu run sample (1042) of run (run_5a7c9e21-4d3b-4a8f-b1c2-d3e4f5a6b7c8)
Vayu threshold "latencyP95Ms" of run (run_5a7c9e21-4d3b-4a8f-b1c2-d3e4f5a6b7c8)
Vayu inbox "port 8099" (inbox_c0d1e2f3-a4b5-4c6d-8e7f-9a0b1c2d3e4f)
Vayu capture "POST /stripe/events" (7) in inbox (inbox_c0d1e2f3-a4b5-4c6d-8e7f-9a0b1c2d3e4f)
Vayu mock server "Orders on port 4010" (mock_1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d)
Vayu mock issuer "port 9100" (issuer_6f8a0c2e-4b5d-4e71-9a3c-5e7f9b1d3a45)
Vayu trash entry "Legacy \"v1\" orders" (col_a1b3c5d7-e9f0-4a2b-8c4d-6e8f0a1b3c5e) - collection

Where the user copies each kind from in the app:

  • request: the request's row menu in the Collections drawer, and its tab's menu.
  • example: the copy button on the example's row in the request's Examples tab.
  • collection: the collection's row menu, and its tab's menu.
  • environment: the environment's row menu in the Variables drawer.
  • run: the run's row menu in History, the run tab's header, and its tab's menu.
  • run comparison: Copy comparison for agent on a load test report's vs-baseline strip.
  • inbox: the inbox's row menu in the Services drawer, the inbox tab's header, and its tab's menu.
  • capture: the copy button in the capture's detail header.
  • mock server: the mock's row menu in the Services drawer, the mock-server tab's header, and its tab's menu.
  • mock issuer: the issuer's row menu in the Services drawer.
  • trash entry: the copy button on the entry in Trash.
  • variable: the copy button on the variable's row in the Variables drawer, for an environment's, a collection's and the globals alike. Feeds resolve_variables and update_environment, update_collection or update_globals for its scope.
  • spec operation: the copy button on an operation's row in a collection's spec sync (the added, changed and removed lists). Feeds get_spec, diff_spec and sync_spec, which match on its method and path.
  • graphql operation: the copy button beside the operation picker in the Query pane of a saved GraphQL request (the picker shows once the document defines more than one operation and one is chosen). Feeds get_graphql_schema's requestId and the envelope's operationName in run_request and update_request.
  • run sample: the copy button in a sample card's header on a load test's Samples tab. Feeds get_run_samples and get_run_report, which join on its resultId.
  • element: the copy item in an element's row menu, in a request's or a collection's Elements list. Feeds the elements argument of update_request and update_collection.
  • threshold: the copy button on a budget's row in the load test config dialog (a custom budget included), and on its verdict in a load test report. Feeds start_load_run's thresholds and get_run_report's verdict.

The command palette's Copy "<tab>" for agent copies the line of whichever of those tabs is active.

Two rules for the cases where the user did not paste one:

  • The request the user means: ask the user for a Vayu reference line, or call get_app_focus. It reports the tab and environment open in the app window right now - activeTab (type, entityId, label), run ({ runId }, set only when the open tab is a run) and activeEnvironment (id, name) - and nothing else: no variable value, header or credential. Read the entity itself with its own tool (get_request for a request).
  • A run the agent started: read it by the runId its start call returned, not by its position in list_runs: the list is newest-first, so a newer run, the user's or another client's, moves that position.

get_app_focus is served from the renderer's last report and answers an error saying the Vayu window is not connected where there is none: the stdio CLI, and the app before its window has published. A tab's label is a saved name or a kind word (Request, Run), never text derived from a URL, because an unnamed request and a design or load run are titled by their resolved URL path in the app and that path can hold a secret variable's value.

The server instructions carry the grammar and both rules in every session, without tool names (the instructions never name a tool; each tool's description is its one contract). They also say that a GraphQL request's schema can be read through Vayu, introspected with the request's own auth and answered as SDL, before a query is written.

Request composition

The engine owns request composition (POST /compose, issue #226): it resolves {{variables}} and walks the collection ancestor chain to resolve inherit auth, then returns the execute-ready payload POST /execute / POST /runs accept unchanged. Composition is pure - nothing is sent - which is exactly what MCP's safety model needs: every execute/load tool composes first, checks the allowlist against the composed (resolved) URL, and only then executes the composed payload - which carries the same allowlist to the engine as targetPolicy, for the URL it is about to send (below).

Four tools compose a stored request by id: run_collection_smoke and run_collection for every request of a collection, start_load_run with a requestId, and run_request with a requestId and no url (issue #2435), which is the single-request replay: the compose body is { requestId, environmentId?, collectionId? }, so the send carries the stored and inherited auth, the collection chain's and the request's own elements, and the stored settings (redirects, protocol, verifySSL, cookies), exactly as the app's Send does. A field the call states beside the id (method, headers, body, bodyType, auth, httpVersion) goes in the compose body's request overlay and replaces the stored field for that send only. With a url, run_request is ad hoc: requestId links the run in History and is never sent to /compose, nothing stored is applied but the collection scope its scripts read (the linked request's collection wins over collectionId at /execute, issue #3461), and the result carries a caveat saying so, because an agent passing both usually means the saved request and would otherwise read a default-auth response as the stored one. A call with neither is refused. Ad hoc, collectionId scopes composition, and the composed answer's collectionId (passed on unchanged by asMcpSend) carries the same scope to /execute, so a script the call adds reads that chain and the names composition deferred past it resolve against it (issue #3461). The by-id branch keeps the ad-hoc gates of the other: the verifySSL: false refusal and the agent-script refusal run first, and the allowlist is checked on the composed URL, not the stored one.

A pre-request script can still change where the request goes after that gate has run: it can assign pm.request.url, and since #2521 a request a pre-request script runs before is composed with its {{names}} written (deferredVariables), so a deferred {{host}} resolves from whatever the script set. The gate on the composed URL cannot see either, so the allowlist also travels with the send:

  • targetPolicy on every send. asMcpSend stamps the session's allowAll and allowlist, as {allowAll, allowedHosts}, beside origin on every POST /execute and POST /runs this server makes (run_request, streaming or not, each run_collection_smoke row, run_collection, start_load_run in both shapes and get_graphql_schema). The engine judges the URL it is about to send, after the pre-request scripts and the residual pass, by the same rule safety.ts applies (exact host, case-insensitive; an empty or still-templated host is refused even under allow-all), and the host of every OAuth 2.0 accessTokenUrl / refreshTokenUrl the request's auth would post to, before any token is fetched. See targetPolicy. A test drives every sending tool by name, and a scan fails on an executeRequest or startRun call that does not go through the helper.
  • A monitored run's policy lists its exempt monitor host. The engine judges a load run's monitor.url against the same targetPolicy (#3121) and exempts nothing, so when start_load_run carries a monitor block whose host the monitor gate passes without an entry (loopback or private, link-local and metadata addresses aside; see Safety), asMcpSend adds that host to allowedHosts (exemptMonitorHost in safety.ts, the gate's own predicate). Nothing the gate refuses is ever added. The entry also admits the run's own requests to that host if a pre-request script steers them there, which is the one place the engine's list is wider than the gate on each composed target.
  • The early gate stays, for the unscripted case. checkComposedTarget refuses off-list hosts before any traffic, exactly as before. The one difference: a URL whose authority holds templates that are all listed in the composed payload's deferredVariables has no host yet - the script chooses it - so it is passed to the engine instead of denied, and is refused here only when the allowlist is empty and allow-all is off. A template composition could not answer is still an unknown host, denied as before; when that host is a whole {{token}} the refusal names the first such variable and the tools that define it (update_collection variables or an environment, resolve_variables to see what is undefined) rather than the generic "may contain unresolved variables" (#2450).
  • The engine's refusal reads as the early one. A buffered answer's refusalCode (or a stream's 400 body, or the smoke row's skip reason) of target_not_allowed becomes the allowlist remedy settingRemedy gives the early refusal; target_host_unknown asks for a resolved URL. The text says the allowlist is applied after the pre-request script and to an OAuth 2.0 token endpoint.
  • deferredVariables describes the composition and is stripped from the payload before it is sent.

What targetPolicy does not cover: a redirect hop a server answers with, and a script's pm.sendRequest, which is refused for MCP-started runs instead (below). A tool call that forwards a preRequestScript is still not sending the composed bytes untouched, but it can no longer reach a host the allowlist did not list, bar the exempt monitor host above, which a script can also steer the run's own requests to.

Scripts: the by-id compose path attaches the collection chain's, then the request's own, script.pre / script.post elements under elements (compose_elements, issue #1514 - the ordered { origin, id, name?, script } part list compose_script_parts built is retired). The renderer's inline path still builds its own ScriptPart[] from its editor state, a different concern (that composer runs client-side against unsaved state, not this server). run_request's ad-hoc preRequestScript / postRequestScript no longer ride inside the inline request object (issue #1517): /execute refuses those two names outright now that elements is the only script source, so the tool reads them, folds each into an ad-hoc script.pre / script.post element, and adds both after the stored ones - alongside any ad-hoc elements argument the agent gave directly - so they run in addition to whatever the composed request already carried, never replacing it. On the by-id branch that takes two compositions: the engine's inline overlay replaces a whole key, so the first, by id, reads the collection chain's and the request's own list, and the second composes again with that list plus the ad-hoc entries as the inline elements. Composition decides from the elements it sees whether a pre-request script runs before the send (#2521), so a name an ad-hoc preRequestScript sets is left for it rather than resolved to the stored value first. A call with nothing ad hoc composes once. start_load_run's ad-hoc postRequestScript / tests folds the same way now (issue #1594): POST /runs reads a single target's step-level elements under requestElements, a key distinct from elements there (see below), so the composed chain rides under that key too - composeLoadRunRequest renames the compose response's elements onto requestElements rather than folding it into a flat tests string.

Scripts an agent supplies are refused while reveal is off (#1834). A script reads every variable the request resolves against, secret ones included, so one the agent wrote could copy a secret into its own output, a variable not flagged secret or the request it sends. With Reveal secrets to agents off, run_request refuses preRequestScript, postRequestScript, tests and any elements entry of a script kind (script.pre, script.post, script.setup, script.teardown, matched case- and whitespace-insensitively), and start_load_run refuses postRequestScript and tests (it has no pre-request script; its run-level elements object carries no script text). The refusal is a ToolArgError from tools/compose.ts::refuseAgentScripts, raised before the call is composed or sent, and names every offending argument and the setting. Nothing else changes: a blank script (empty or whitespace-only) is not refused, because the engine composes and compiles none (is_blank_script_element); extractors, assertions and timers in elements pass (with write access off, what an extractor or a revealed script sets is not stored - see the write toggle below); run_request with a url is an ad-hoc send, where requestId only links History and composes nothing stored, so it carries no script; without a url it sends the saved request by id, and the scripts stored on it and its collections run as stored, which is the same residual as below; and with reveal on every call is as it was. Scripts stored on a request or collection are not affected (see the write toggle below).

One validation script, one name - except where the engine still keeps two. The post-response script is one field in the app - the request builder's Tests tab - and MCP declares it identically on run_request and start_load_run (postRequestScript, with tests accepted as an alias) so a script an agent writes for one reads the same on the other. Both tools now fold it the same way too (issue #1594 caught start_load_run up to #1517's run_request shape): an ad-hoc script.post element, appended to requestElements. start_load_run replaces rather than joins - the composed chain's own script.post elements are filtered out first (tools/compose.ts::composeLoadRunRequest), because with no way to know which assertions the agent meant, running both would add ones they never asked for. tests stays accepted on both as the engine's own spelling for the run tool - a tool's schema refuses a key it does not declare, so removing it would refuse a script written in that spelling. Passing both names is rejected with a ToolArgError rather than resolved by precedence: they are one slot, and dropping either would report a run as validated by assertions that never ran. Under load the script runs against sampled responses (max_response_samples / response_sample_rate), not every one.

How each tool uses POST /compose (tools/compose.ts::composeViaEngine):

  • Variables - the engine resolves URL, headers, and body with the app's precedence (environment > collection chain, leaf→root > globals; enabled only; an unknown name keeps its braces, issue #1009; dynamic variables like {{$guid}} generated per occurrence). MCP hands it raw strings and checks the allowlist against the composed host (and the engine again against the sent one, #2521). start_load_run composes for a run, like the app, so the {{$guid}} family is deferred and the engine generates a fresh value per iteration rather than repeating one across them (issue #995); see variable resolution.
  • Auth - run_collection_smoke and run_request with a requestId and no url compose each saved request by id, so its stored auth applies (inherit resolved against the collection chain); run_request / start_load_run accept an explicit auth block and forward it raw inside the inline request - the engine resolves variables in it (and inherit, when a collectionId scopes the walk) and applies it at execute (oauth2 uses its token cache).
  • Scripts - composing by id attaches the collection chain's + the request's own script.pre / script.post elements engine-side (issue #1514), so a saved request's assertions execute in the design send, the sequential collection run, and now start_load_run's single-target path too (issue #1594 - the composed elements become the run's own requestElements, a step-level pipeline POST /runs now runs per submission), and so does run_request with a requestId and no url. start_load_run does not forward a collection's or folder's script.setup / script.teardown that /compose emits: requestElements is validated as a request's own and refuses them, and they belong to the collection's own run (#3070). An ad-hoc run_request (a url) takes a preRequestScript / postRequestScript instead (folded into elements, above), since an ad-hoc call has no chain to compose from, and they are composed after the stored ones when it sends a saved request; start_load_run takes the same postRequestScript for a URL-only run, folded into requestElements the same way, as described above. Those two are supplied per call, are refused while reveal is off (above), and are not stored - create_request and update_request take the same two names as sugar for a script.pre / script.post element stored on the request itself, which is what lets an agent-authored script outlive the call that wrote it (see Storing a request's elements below).
  • Bodies - body is a string and bodyType names the mode (json | text | graphql | jsonrpc | xml | form-data | x-www-form-urlencoded | binary, default text). The two form modes carry their content as fields, not as a string, so body is written as key=value&key=value and split into the fields rows the engine reads - see the body union. A graphql body may be the bare query document: the engine envelopes it as {"query": ...} and sends application/json, and an envelope written out in full is sent unchanged - on POST. With method GET the same fields travel as query / operationName / variables / extensions query parameters instead, with no body and no Content-Type, so a mutation needs POST rather than the GET a new request defaults to - see the graphql envelope. A jsonrpc body may be the bare call object: the engine adds "jsonrpc":"2.0", plus "id":1 when the call names no id, and a frame that already declares a string "jsonrpc" is sent byte for byte - which is how an agent chooses its own id or sends a notification - see the jsonrpc envelope. An xml body has no envelope at all: it is stored and sent byte for byte and carries application/xml unless the agent set a Content-Type of its own, which is how a SOAP 1.2 endpoint gets application/soap+xml. create_request stores the same shape. Every form field an agent writes is a text part: a form-data file part has no spelling in a key=value string, and a stored one is left alone unless body replaces the whole body.

GraphQL schema. Before writing a graphql body, an agent reads the endpoint's schema with get_graphql_schema: given a saved request's requestId it composes that request exactly as a send would (the same POST /compose, so the same variables and the same auth, inherit walked), or given a url it composes that endpoint inline. It then sends the standard introspection query as a transient POST /execute, so no run row is filed, and answers the schema as SDL. The schema is the request's own, the one the app's editor introspects, rather than a copy the agent was handed. It is fetched live on every call. - File bodies - create_request and update_request store a binary body, one file sent as the whole body: file: {src, contentType?, fileName?} in place of body (a lone file implies bodyType: "binary"). The engine sends a stored path only once the user picks the file in the request editor or it lives under a folder they allowed in Settings > Files, whatever the arguments or the body say (#2356): an agent can name a path, never choose one for the user. The tools that send an ad-hoc request (run_request, start_load_run) refuse a body that names a file (bodyType: "binary" or any file argument) before composing anything, and say to run the saved request by id instead - run_request with requestId and no url, start_load_run with requestId, or run_collection / run_collection_smoke over its collection. Both declare file only so this refusal, which names that route, is the answer rather than the schema's bare Unrecognized key. - Headers as lines (issue #2466) - headers on run_request, start_load_run and get_graphql_schema is an array of {name, value} lines or a string map. Each line is sent as its own header line, in the order given and in the spelling written, so Link, Forwarded or X-Dup beside x-dup are repeated rather than collapsed (Cookie rows are the exception: they go out as one ;-joined line with the jar's cookies, issue #2788); a map holds one value per name and cannot repeat one. Both go to POST /compose as given, which answers lines either way, and a line that is not an object with a string name is refused by its position. The same payload that composes is the one sent: nothing is folded between the two. create_request, update_request and the saved-example tools take {key, value, enabled?} rows instead, for the reason given under the examples bullet above (#3422, #3550). - What actually went out - the engine adds headers an agent never wrote: the body-implied Content-Type (a json body, a graphql body on POST, or a jsonrpc body, sends application/json; a graphql body on GET has no body, so the engine adds no Content-Type for it at all - a text one text/plain, an xml one application/xml, an x-www-form-urlencoded one its own type, and a bodyless POST none), the default headers a send adds - a default User-Agent, a negotiated Accept-Encoding, and a correlation id where one is switched on - and the Cookie line the jar matched for the environment (merged with any Cookie the call typed). A header the call wrote itself always wins over the default of that name, and disabledDefaultHeaders on the payload refuses one outright. run_request and start_load_run take that list as an argument (issue #1337), which is how an agent sends a request with no User-Agent at all rather than one carrying a value it chose; it rides beside the composed payload, because the names say which of the engine's own defaults this send declines and composition neither reads nor rewrites them. run_collection_smoke does not take it - it replays each saved request exactly as stored - and a scenario load run refuses it by name, as it does every other single-target field, because its steps are each composed from their own saved request. So the request an agent composed is not the request that was sent, and asserting on the composed one is how a correct request gets reported as wrong. requestHeaders in the result is the sent record - composed plus everything but the Cookie line, minus a form-data Content-Type libcurl writes itself and minus a blank Content-Type or Cookie row, which is not sent (any other blank header is sent empty and recorded as "", issue #3220) - folded to one value per name (a repeat joined with ", ", Cookie with "; "); requestHeaderLines is the same set unfolded, one {name, value} per line in wire order, a repeated name repeated in the spelling written (issue #2466), and the one to read when a header was sent more than once; and rawRequest is the full wire frame including the Cookie line and libcurl's own Accept / Content-Length. Both keep their shape and every non-credential value as the engine recorded them; read them rather than the request the call sent. Unless the user has turned on reveal, a credential-bearing header's value and every secret value in either reads <redacted> (see Secret values); so do the response's headerLines, the {name, value} rows as received, where each Set-Cookie is a row of its own (issue #2460), and so does each hop's headerLines on redirects, the {status, statusText, headerLines, url, schemeDowngrade} of every 3xx the send followed (always present on the answer, [] when none; headers and headerLines hold the final response only, issue #2461). A hop's Set-Cookie is what the server sent, not what the cookie jar kept. A hop's url is the request it answered, masked as the result's own url is (issue #2949, below), and schemeDowngrade is true when that request went over https and the next over http: libcurl drops Authorization and Cookie there, an API key sent as a header travels. requestHeaderLines (and a stored trace's sentHeaderLines) is masked the same way, every repeated credential line on its own. A postRequestScript reads the same set as pm.request.headers (see scripting.md). - Transport fields - httpVersion rides the inline overlay for both tools, and start_load_run adds followRedirects / maxRedirects (issue #760). They belong here rather than beside the load shape because they describe the request: POST /compose emits all three on a stored request under the never-elided rule, so an agent's value has to be laid over the composed payload the same way a URL override is. A URL-only run has no stored row behind it, which makes this the only way its redirect policy gets stated at all. verifySSL is the one transport field that deliberately does not ride the overlay: run_request refuses verifySSL: false and start_load_run takes no such argument, because a certificate check skipped for one call is recorded nowhere afterwards. It is written onto the saved request instead (issue #795), and every by-id compose then carries it, a run_request by requestId included. - Streaming - run_request takes stream: true for a text/event-stream endpoint (issue #575). tools/call is request/response, so the tool does not stream to the agent: it starts the run, reads the relay for at most streamBudgetMs (default 5000, maximum 60000) collecting at most maxStreamEvents (default 50), and returns those events with which bound it stopped at beside them - completed, capReached or budgetExhausted, plus totalEvents where the completion frame reported it. The three are separate because the follow-up differs: a completed stream is finished, a capped read wants a larger cap, and an exhausted budget means the run is still going, get_run says whether it has finished, and stop_run ends it. The flag is sent on every call, never elided - the two answers have different shapes, so the tool decides which one it is about to parse rather than an engine default deciding for it. An explicit stream decides; without one, a send by requestId follows the saved request's Event stream setting, which every by-id compose carries (#3561), as the app's Send does, and an ad-hoc send buffers. The allowlist gate is unchanged: it runs on the composed URL before anything is sent. - Data rows - run_request takes an optional data object: one row, which binds every {{data.column}} in the URL, headers and body and which both scripts read as pm.iterationData (pm.info.iteration is 0, issue #601). It rides beside the composed payload rather than through /compose, because {{data.*}} survives composition by design - that is what leaves the tokens for the engine to bind. A column the row does not carry is an error naming the token and the row's columns, and nothing is sent. Auth credentials bind as well (issue #642) - before they are encoded, so basic auth base64s the row's values - with OAuth 2.0 the one mode no row can reach, refused by name because its token comes from the token endpoint rather than from the request. The allowlist gate reads the composed URL as always - a {{data.*}} in the path leaves the host knowable and is judged on that host, while a template in the authority is still "unknown host" and denied. run_collection_smoke stays out of it: it runs each request on its own, with no sequence to iterate, so there is no row for it to bind. A whole data set is a run's argument instead: scenario.data on run_collection and on start_load_run's scenario shape (below), or start_load_run's top-level data for a single target (issue #993) - the same rows, the same refusals, bound one per request the run sends off a cursor that wraps rather than one per iteration of a sequence. A single target's rows also name their columns to POST /compose (dataColumns, the union of every row's keys), so a bare {{column}} stays written for the bind and wins over a same-named environment variable, as it does in the app (issue #2956). The two fields are mutually exclusive: data beside a scenario block is refused by name rather than dropped, and so are a top-level dataFileName / dataFileHash / dataFileCastNumbers there - a sequence names its rows' file inside the block. - Protocol - run_request and start_load_run both take an optional httpVersion Zod-enum arg ("auto" | "http1.1" | "http2", default "auto"), mirroring the request builder's Settings-tab picker. run_collection_smoke has no such arg: it replays each saved request exactly as-is, and POST /compose always emits a stored request's protocol. start_load_run with a requestId lays a stated httpVersion over the stored one through the compose body's request overlay, like any other agent-stated field. On a URL-only call there is no saved row behind the request, so httpVersion is forwarded only when the caller actually supplies it. - One post-response script, one name on the wire, not three. Before issue #1514 it was stored as postRequestScript (on a request and on a collection), sent as postRequestScripts / postRequestScript to POST /execute, and as tests to POST /runs - three spellings read_post_request_script read on both routes. The cut-over ended all three: it is stored as a script.post element now (create_request / update_request / create_collection / update_collection's preRequestScript / postRequestScript sugar folds a string into one, issue #1517), and both POST /execute and POST /runs refuse postRequestScripts / postRequestScript / tests outright since issue #1594 gave the single-target load path the same element pipeline the design send already had - elements (run_request) / requestElements (start_load_run) is each route's only script source now, and read_post_request_script itself is retired. MCP still shows the agent a single argument name, postRequestScript with tests accepted as an alias (see One validation script, one name above), and folds it into an ad-hoc element client-side before either route ever sees a legacy field. - Storing a request's elements - create_request and update_request take elements (the whole list) plus preRequestScript / postRequestScript sugar (strings, optional) that fold a script into a script.pre / script.post entry rather than being written to the engine under those two names, which POST /requests / PUT /requests/:id refuse outright since issue #1514. update_request merge-patches elements like every other field when the caller sends it directly: leave it out and the stored list is kept. The script sugar merges at the entry level instead - passing a script alone reads the request's current elements first (GET /requests/:id), replaces or removes just that one kind, and writes the whole list back, so a script written this way never drops the request's other elements; an empty string clears the kind. elements and the script sugar cannot both be given on one call - a caller who states the whole list has already said what belongs in it. The tests alias is deliberately absent here - it is the engine's spelling for an ad-hoc run body, and a stored field answering to two names is a second name to keep in step. Storing an element adds persistence, not execution capability: an agent could already run arbitrary scripts through run_request, and a stored one runs only when the request is later sent. Both tools already declare invalidates: ["request"], so the renderer refetches the row and picks the elements up without a further entity. A collection's own elements - the ones that run around every request below it - are create_collection / update_collection's elements field and the same two script names (issue #759), and carry the same merge and clearing rules. - Load-testing a saved request - start_load_run with a requestId composes it by id, exactly as run_collection_smoke and the app do: variables resolved, stored auth applied through the collection chain, and the chain's + its own elements attached under elements, which the tool renames onto requestElements - POST /runs runs an element pipeline per submission on a single target too now (issue #1594), and reads its step-level elements under that key, distinct from the run-level elements override below. Any field stated explicitly (url, method, headers, body, auth, httpVersion) rides in the compose body's request overlay and replaces the stored one before resolution; an explicit postRequestScript / tests replaces the composed chain's script.post elements in requestElements rather than joining them - with no way to know which assertions the agent meant, running both would add ones they never asked for. Without a requestId the run is ad-hoc and url is required. A saved request's pre-request script runs only when marked inline (config.inline) or this run's own elements.scripts override is "allInline" - left asMarked with no per-element mark, it still never runs, since there is no pre-request replay to defer it to the way script.post gets one. The count of script.pre elements that will not run is reported in the tool's result rather than passing silently, unless the override already covers them. - Scenario runs - a collection as the unit of work (issue #754, reversing #454's deferral). A collection's ordered sequence of requests can be run from MCP in both of the engine's modes, over the one POST /runs route that takes a scenario block: - run_collection posts the block with no mode, which is what selects the design-mode runner: steps execute one at a time, share the environment's cookie jar, honour pm.execution flow control, run their stored pre-request scripts, and repeat once per data row with {{data.column}} bound and pm.iterationData set. It returns the run id immediately - the run continues engine-side - along with the plan's step count and a note on reading get_run_report: its results carries every stored step row (stepsStored; resultsStored / resultsCap say the same of any run). Each of those rows carries that step's request and response bodies inline, under trace (build_result_trace, the same node a single design-mode send stores) - not behind GET /runs/:id/samples, which is the load-run capture route - so a long plan against large responses makes for a large report. That is what the 96 KB total trace budget above bounds: past it a step row keeps its scalars and carries traceOmitted instead of its bodies, non-passing steps last to lose them. - start_load_run takes the same block as an optional scenario argument and posts it with a mode, which hands the plan to the load executor: concurrency is the number of virtual users, each walking the whole plan with its own cookies. Only constant_concurrency (the default), ramp_up and iterations can drive a sequence - capacity and constant_rps are refused with the engine's own reasoning (a knee measured against which step's p99? an arrival-rate executor Vayu does not implement), as is any non-zero targetRps: a scenario run is closed loop by design, whatever the declared mode. - The collection tree is the sequence: there is no step list to send, and recursive: true walks sub-collections in the sidebar's order: at each level the sub-collections and requests are one sibling list, a request runs where it sits and a sub-collection's whole subtree where the sub-collection sits, mirroring collect_requests. The pre-flight allowlist walk is the same walk (scenarioStepRows), pinned to the engine's by recursive-run-order-conformance.json, so the step a refusal names is the first one the run would have reached. - Rows are inline - the engine never opens a file - and its maxScenarioDataRows / maxScenarioDataBytes refusals, and the depth refusal (a cell nested deeper than 100 levels, 400 invalid_run_config or invalid_scenario), are surfaced verbatim rather than re-derived in the schema. dataFileName and dataFileHash (issue #2051) name the file the rows came from - a display name and the SHA-256 of its bytes as 64 lowercase hex, which the schema checks, refusing a name holding a / or \ as a path - and are forwarded as given; the engine refuses either one sent without rows, by name. dataFileCastNumbers (issue #2540), a boolean, says the agent read the file's unquoted numeric cells as numbers; Vayu never converts the rows, it only records the reading, and it is forwarded and refused without rows on the same terms. See Data files. - scenario.iterations is offered on run_collection only. A load run reads the top-level iterations (total passes across all virtual users); the in-block count is the design runner's and the load executor never reads it, so offering it there would be an argument written and never read. - failOnSchemaError makes the bound contract a gate (issue #766), on run_collection only, matching the Run Collection dialog's checkbox. It is run-scoped and top-level, beside the scenario block rather than inside it, and is sent only when asked for: the engine defaults it to false, so a run snapshot carries the key exactly when it changed what "failed" meant. With it on, a step whose response does not match the schema its collection's bound document declares fails - but only a step that passed everything else; one already failing keeps the error that named it. Off, the verdict still rides every step and the report's schemaValidation totals. Note the default is the opposite of run_collection_smoke's, for the reason recorded there. start_load_run refuses the flag on either of its paths, naming the executor: a load run validates sampled responses once the run has drained and never demotes a step, so the gate would decide nothing. It is declared on that tool for the refusal's sake - an argument the tool's schema does not name is refused as an unrecognized key, which says nothing of the surface that honours it. - stopOnError ends an iteration at every errored step (issue #2526), on run_collection only, matching the Run Collection dialog's switch. Top-level beside scenario and sent only when true, like failOnSchemaError. Left off, the engine's default, an errored step (a script that threw, a request that got no response, an unbindable data row) stays errored with its message and the iteration moves on to the next request, as in Postman and Newman; the runner's own refusals end the iteration either way. What an error that ended one cost is counted: scenario.stepsNotRun in get_run_report, and stepsNotRun on the step row that ended it, in its trace - the tool's description and the nextStep it returns both say so. start_load_run refuses it on either path for the reason it refuses failOnSchemaError (declared so the refusal that names run_collection is what an agent reads): no load path reads it. - elements: {timers, scripts} overrides a run's stored timer/script behaviour without editing the collection (issue #1559, exposing the block issue #1495 defines on POST /runs, validate_elements_run_override). timers: "off" silences every timer.* wait for the run; scripts: "allInline" / "allDeferred" forces every script.pre/ script.post element's inline-vs-deferred execution regardless of its own marking; "asConfigured" / "asMarked" (the defaults) leave each element's own configuration in effect. It is top-level, beside scenario rather than inside it, on both tools that read it - the same place RunCollectionDialog's load-test section sends it. run_collection offers elements: {timers} only, since scripts has no reader on the design-mode path it drives. start_load_run offers both keys, on either shape it can start: timers fires on the scenario branch's execute_scenario_run (RunContext::timers_override wired into the same ExchangeInputs a scenario load run does) and, since issue #1594, on a single target's own submission pipeline too (load_strategy.cpp's per-step hooks); scripts reaches the scenario load path's post-run replay and, since #1594, a single target's own inline-vs-deferred dispatch (RunContext::script_element_runs_inline) - the mechanism that makes "allInline" the thing that gets a single target's script.pre to actually run under load (see Load-testing a saved request above). This mirrors RunCollectionDialog's own load-test controls, not the engine's full contract: timers also accepts a {fixedMs} / {minMs, maxMs} override (issue #1498) replacing every timer's own span, and the block also takes includeScriptTime and seed, but no control anywhere in the product - app or MCP - sends any of the three today, so these schemas only name the two enum values "asConfigured"/"off" and "asMarked"/"allInline"/"allDeferred". - The allowlist gate is all-or-nothing here, unlike the smoke matrix's per-request skip: every step is composed by id and gated before the run is created, and one step the allowlist does not cover refuses the whole run with nothing sent, naming the step the way the engine names it (step 1 (request 'checkout', id 'r2')). The refusal names the host and withholds the composed URL, which is secret-resolved and so can carry a secret variable's value or a literal credential in its query or userinfo (#1892). A step that will not compose refuses it too - the engine resolves the same plan before creating the run row and would refuse it for the same reason. The engine holds the run to the same list as well (targetPolicy): a step's OAuth 2.0 token endpoint is judged when the plan is resolved, a 400 with no run row. - Every argument that describes a single target (url, requestId, method, headers, body, auth, httpVersion, postRequestScript, collectionId) is refused by name beside a scenario, as are maxInFlight (in-flight is bounded by the virtual-user count), sloMs/stepDuration (capacity's own fields) and stream (a collection's steps stream by each saved request's own Event stream setting, which a run cannot change). Each would otherwise be an argument an agent believes shaped the run that nothing on this path reads. - maxStreamDurationMs and maxStreamEvents are accepted beside a scenario (#3235), without stream: they are forwarded top-level and bound each step whose saved request streams, falling back to the sseMax* settings cap by cap, while a step that does not stream ignores them. run_collection takes the same two arguments for a design-mode run. Neither tool ever sends stream for a collection - the engine answers it with a 400 there. - Request mutation - a pre-request script's pm.request edits (url, method, headers, body, auth) are applied to the request that is sent, so an agent can sign a request or override the engine-applied auth from run_request (with reveal on; the script itself is refused while it is off), and a saved request's stored pre-request script does the same under run_collection_smoke. The write-back is engine-side (scripting.md), so both tools get it without composing anything extra. A rejected edit comes back as preScriptError in the response. start_load_run did not offer the field at all before issue #1594 - POST /runs ran no pre-request hook on its single-target path. It still does not accept an ad-hoc preRequestScript argument (a saved request's own script.pre element is the only source), and a composed one only mutates the request when it is marked to run inline or this run's own elements.scripts override forces it - see Load-testing a saved request above.

run_request / start_load_run take optional environmentId and collectionId to scope resolution; both are forwarded to POST /compose. Every tool that composes with an environment - those two (start_load_run's scenario branch included), run_collection, run_collection_smoke and get_graphql_schema - picks it by the rule resolve_variables follows, in one helper (resolveEnvironmentId, issue #2480): an omitted environmentId is the active environment, as the app's Send does; "none" is no environment; and an id no environment has is refused with the unknown-id sentence (Error results, below) before anything is composed or sent, where POST /compose alone would degrade it to an empty scope and send every environment token literally. The environment picked is also the one the send's cookie jar, its History row and, with write access on, its scripts' environment writes belong to, so a call that names none lands in the active environment's jar and row exactly as the user's own Send does. clear_cookies keeps its own contract: omitted there means every jar. An unknown requestId is the engine's definitive 404, surfaced as a readable "no saved request with id" tool error.

Cookies are shared with the app, per environment. run_request and run_collection_smoke go through POST /execute, which sends through the engine's cookie jar (issue #301) - so a Set-Cookie an agent collects is sent on its next call, and on the user's next Send in the same environment. That is deliberate: the jar belongs to the environment, not to the caller, and giving MCP a jar of its own would make the same saved request behave differently for an agent than in the UI - a surprise in the harder direction to debug. The state stays visible and resettable from either side: Settings → General → Cookies lists every jar and clears it, and get_cookies / clear_cookies (issue #758) read and clear the same jars over MCP - so an agent can see the session it inherited and drop it rather than only being told it exists. An agent that must not inherit one at all should run in an environment of its own. run_collection shares the jar too - the design-mode runner is the one executor handed it, which is what lets a login step authenticate the steps after it. start_load_run is unaffected either way: a single-target load run never touches the jar, and a scenario load run gives each virtual user cookies of its own.

History. Until issue #226 MCP carried resolve.ts - a full main-process port of the renderer's composition pipeline - because the engine composed only partway. That copy (and its dynamic-variables.ts twin) is deleted; the engine path is the single implementation, and the renderer's remaining resolver is preview-only. Do not reintroduce client-side composition here - a new engine client should call POST /compose.

Variables

The resolution order is stated once rather than reworded per tool: globals < collection chain (root to leaf) < active environment, with a bound data row's bare column names above all three. That is the ladder Variable Resolution defines and the engine executes; before issue #1207 it lived only inside two tool descriptions that happened to mention it, and nowhere a caller about to write a value could ask for it directly.

The model itself is served once, as a resource (vayu://variables/resolution, backed by variable-origins.ts's VARIABLE_RESOLUTION_MODEL), rather than restated per tool. Every variable-writing or -listing tool - get_globals, update_globals, list_environments, create_environment, update_environment, create_collection, update_collection - carries one shared sentence (VARIABLE_PRECEDENCE_SENTENCE) plus that tier's own position in the order and a pointer to the resource; precedenceNote() builds both pieces from one place. The sentence is shorter than the budget guard's repetition limit on purpose (see The size of tools/list is budgeted): it is the one rule restated in every one of those tools. A table-driven scan in tools.test.ts runs over every variable tool's description and fails on one that omits the sentence, so a new variable tool cannot ship silent about where its tier sits.

resolve_variables answers what the per-tier reads cannot: which definition of a name actually wins in a given collection/environment context, and everything it beat. It reports the winning value with its scope and source, then every other definition highest-precedence-first, each labelled outranked (a higher-ranked definition - a later link in the chain, or a tier above - is enabled and wins instead) or disabled (enabled: false). The second is the more common answer to "why is this not the value I set?", and a list built by skipping disabled rows could not give it. A name whose every definition is disabled resolves to nothing at all, not to an empty string: the tool reports resolved: false with no value, because a present-and-empty answer would read as a different fact.

Its context is chosen the way a send's is, by the same code: an omitted environmentId is the active environment, "none" resolves as if none were active, and an id no environment has is refused. So the value resolve_variables reports for a name is the value run_request sends for it in the same context.

Secret values are withheld from resolve_variables's report (valueWithheld: true) the way every other read withholds them, unless the user enables reveal (see Secret values).

The model is duplicated on purpose, and pinned so the copies cannot drift. Neither process can import the other's resolver: the main process emits with rootDir: "electron" and cannot compile a file under src/ (TS6059), and the renderer cannot import from here, because this is a referenced composite project (TS6305). So electron/mcp/variable-origins.ts mirrors app/src/lib/variable-resolution.ts the way compare.ts mirrors src/lib/run-compare.ts (see the file map below), and variable-origins.conformance.test.ts replays the engine's own fixture (engine/tests/fixtures/variable-resolution-conformance.json) through both, so a divergence fails a test rather than surfacing as a wrong answer months later. The fixture supplies a pre-flattened chain, so it cannot exercise the parentId walk; that half is pinned separately, by running collectionChain() and the renderer's walkAncestors() over the same rows - including the malformed ones (a self-parent, a two-node loop, a parent that does not exist) - and asserting they agree.

Call this what it is: a second implementation of the resolution order, kept honest rather than avoided. Importing the renderer's resolver is the option that would have avoided it and the build forbids it; an engine endpoint reporting origins is the other, and it would mean new C++ for a question the engine has no use for (execution needs the winner, never the losers). This does not make MCP a second composition path, which is the split that is load-bearing: resolve_variables reports stored definitions and substitutes no {{tokens}} - POST /compose remains the only place a request is composed.

Data files

A collection's declared data file reaches MCP in two parts (issue #1742). dataSchema is the contract - column names, the file's name, when it was declared - and is the same on every machine, so it rides the engine row. dataFile: { path, fileName, hash } is where that file is on this machine, and comes from the app's renderer (stores/data-file-store.ts, its mirror of the collections list's bindings), which publishes its whole map to the main process over dataFile:locations (electron/data-file-locations.ts holds the copy and rebuilds each payload, keeping only an absolute path with an extension dataFile:read would open). hash (issue #2051) is the SHA-256 of the file's bytes, as 64 lowercase hex. list_collections (its fields: "full" rows; a summary carries no dataFile and hashes nothing) and vayu://collections hash the file as it is at call time (hashDataFile in electron/data-file.ts, behind the same path gates as dataFile:read, streamed and never returned), so an edit made after a run shows up without the app re-reading anything. One of those gates is the grant registry (#2357): only a file the user picked, dropped or opened through the app is hashed, so the digest is no oracle over a path the renderer merely named. A file that cannot be read - moved, deleted, or never granted (a data file picked before grants existed is granted once it is picked again) - is never an error: the row keeps the hash the app last read the file with (picked in the Data tab, or re-read by a run dialog, Send-with-row or the Data tab), or none for a location it has not read since hashes were recorded. A write tool's echoed collection row carries that stored hash too; it does not read the disk.

castNumbers: true (issue #2540) appears on dataFile when the collection's binding reads the CSV/TSV file with Read numbers as numbers on: the app reads an unquoted integer or decimal cell as a number and a quoted one as text. It is absent otherwise, which means every cell is a string. An agent building data rows from the file reads it the same way, so its rows match the ones the app would send, and says so with dataFileCastNumbers: true on the run.

A path is true of one filesystem only, which is why it never reaches an export. The engine stores each collection's specFile and dataFile binding on its row (issue #2765) so a workspace backup carries them, but MCP drops both from every collection row it answers (move_item's renumbered rows included) and names dataFile from the app's record alone, as above. A path may reach MCP because the Electron-hosted server listens on loopback (MCP_HOST): every client that can read the answer runs on the machine the path names, and can open the file with its own access, the way a person would. The stdio CLI runs without the app, so it has no record and never names a path. The rows are never sent: no tool reads the file, so an agent that wants the data opens it itself, and a run still takes its rows inline as data.

Re-running with the same data file. A data-driven run records which file drove it, by name and content hash, never by path or rows, and how it was read (dataFileCastNumbers, present as true only when its numbers were read as numbers): list_runs carries summary.dataFileName / summary.dataFileHash / summary.dataFileCastNumbers on a single-request run and summary.scenario.dataFileName / dataFileHash / dataFileCastNumbers on a collection run, and get_run_report carries all three under metadata.configuration. To repeat such a run, read the run row for the file's name and hash, then list_collections with fields: "full" for the file's current dataFile.path and hash, and compare the two hashes before reading the file and sending its rows - a mismatch means the file has changed since that run (hash the bytes you read yourself to be certain they are the ones you send). Read the file the way the run did - numbers as numbers when it recorded dataFileCastNumbers: true, every cell as text otherwise - and pass the rows with the same dataFileName, dataFileHash and dataFileCastNumbers: data and the three on run_collection, scenario.* or the same four at the top level on start_load_run. compare_runs reports one file read two ways as a data_file difference, because the hash is of the bytes and cannot tell the readings apart. The run tools take rows, never a path: dataFileName is dataFile.fileName, and a value holding a / or \ is refused by the tool schema (pointing at dataFile.fileName) and by the engine alike.

Error results

A tool that fails answers an MCP error result (isError: true) whose text says what went wrong and what to do, and whose structuredContent is the same failure for a machine (#2776):

{ "error": { "class": "policy", "retryable": false, "advice": "Host \"x.example.com\" is not on the MCP allowlist. ..." } }

advice is the result's text. A tool's outputSchema describes its success, and the SDK holds only a success to it, so the error shape is the same on every tool. That includes the errors the SDK answers before any tool runs: an argument its schema check refuses (Input validation error: ...) is classed input, and anything else it catches (an answer its output check refuses) transient, by the wrapper server.ts puts in front of its tools/call handler.

An argument a tool does not declare is refused, never dropped (#3556). Every tool's arguments object is strict (argumentsSchema in app/electron/mcp/tools/kit.ts, which server.ts registers each tool and prompt through), and so is every nested input object: a request's header line, a stored header row, an element, a binary body's file, a variable entry, start_load_run's scenario, monitor and elements, run_collection's elements, a mock issuer's clients and an inbox's response. The answer names the key, with its path when it is nested:

Input validation error: Invalid arguments for tool start_load_run: scenario: Unrecognized key: "iterations"

So a misspelt collection_id on list_runs is an error rather than a list of every run, and nothing reaches the engine. A prompt refuses an undeclared argument the same way, as a protocol error. tools/list advertises it as additionalProperties: false on each of those objects. Four shapes stay open on purpose: an auth block (each mode's members are the engine's), an OAuth 2.0 config, thresholds (a custom.<name>.<stat> budget is a key no schema can name) and every name-keyed map (headers as a map, variables, data rows, an element's config). A row a read returns can be written back as read: a stored header row declares valueWithheld, description, source and type; a variable entry declares valueWithheld and createdAt (kept as stored) and description (written); a file declares unresolved, which is ignored.

class is one of five, set where the error is built (errorResult in app/electron/mcp/tools/kit.ts, which requires one) and mapped in app/electron/mcp/tools/failure.ts:

class retryable What it means Raised by
policy false A rule the user or the endpoint sets refused it; the advice names who can lift it The allowlist, the load and sample caps, write access off, a tool switched off in Settings, Reveal secrets to agents off (agent scripts, clearing a secret flag), Network settings off, an inline file body, verifySSL: false on a one-off send, the authorization_code grant, the engine's target-policy refusal, an engine 403, an endpoint that disallows introspection, no Vayu window to ask (get_app_focus, which the stdio CLI never has)
input false The arguments, or the request they name, are wrong; change them A missing or malformed argument (including one the SDK's schema check refuses), an unknown tool, a URL whose host cannot be determined, a duration or iteration count that is not one, an argument that does not apply to the run, an engine 400, 409 (the id exists, the spec is still bound, the restore needs its parent) or 413, and every other engine 4xx
not_found false An id the call named does not exist An engine 404, and the lookups that find no such run, collection, request, environment, example, inbox or trash entry; worded as below
transient true The engine was reached and the call did not complete; it may already have taken effect, so the advice says what to check first (per tool, below) A client-budget timeout, a cancelled call, an engine 5xx including 507 (disk full) and the busy-database 503, a merge another client's write beat twice (update_environment, update_collection, update_globals: two 412s, nothing written), an engine answer the server could not use, a secret-masking lookup that failed (when its cause is no engine failure, else it is worded as that failure, below), a 5xx from an endpoint get_graphql_schema introspects, and any error nothing above names (Unexpected error: ...)
unreachable true A host the call needs did not answer; retry once it is up An engine that refused the connection, the 503 an engine answers while shutting down, an endpoint get_graphql_schema could not reach

An id that names nothing (#2778) is answered with the missing object and the tool that lists them, on one line, with no HTTP path and no engine JSON:

No run with id "run_x" (it may have been deleted or the id is mistyped). List runs with list_runs.

A tool declares what its id arguments are as notFound (NotFoundDeclaration in app/electron/mcp/tools/contract.ts): the object's noun, the list_* tool, and the argument (idArg) holding the id, with the kinds shared in ID_KINDS (failure.ts). describeFailure words an engine 404 from it and the call's own arguments. A tool taking several kinds (update_request_example takes a request and an example) declares one entry each, and the entry used is the one whose noun the engine's sentence contains ("Example not found"); an idArg that is a list (compare_runs' two run ids) names an id only when the engine's sentence carries it, since nothing else says which was missing. A kind with no list tool (a spec, whose id comes from a collection's binding) ends at the cause. A tool can also word a 404 by the engine's code (notFoundByCode, read from the flat {"error", "code", "hint"} body or the nested {"error": {"code", "message"}} one by engineCode in failure.ts), for a 404 that is not an unknown id. get_live_metrics is the one that does: the engine answers live_expired for a run that is stored but whose live buffer has aged out, and the text is The live buffer for this run expired (kept 60 s after it ends); the run still exists - read get_run_report(runId)., in the not_found class, without the engine's Use /runs/<id>/report hint (the 60 s is the engine's liveRetentionMs default). Its run_not_found keeps the unknown-id sentence above. A 404 with no code (an older engine), a 404 the declaration does not describe, and a tool that declares nothing answer the engine's body instead. A lookup a tool makes itself before it calls the engine (a delete that reads the row to name it in the prompt, a variable scope) words a miss with the same sentence (unknownIdText), so the text does not depend on which step noticed. Every tool with a <kind>Id argument declares notFound or is on the named exemption list in tools.test.ts with its reason.

Every other engine error is Engine error (<status>): <body> with the body on one line - JSON re-serialized without indentation, anything else with its whitespace collapsed - so the text of a 4xx or 5xx does not depend on how the engine happened to format the answer. A 507 and a busy database keep their retry sentence after it.

What a timed-out or cancelled call is told to check (#2777) is a fact about the tool, so each tool declares it as retry (RetryAdvice in app/electron/mcp/tools/contract.ts) and describeFailure writes it. The failure carries only the lead ("The engine did not answer within this client's 130s budget.") and the tail; the advice between them comes from the tool:

retry Tells the agent Declared on
{ check, noun } The call may have completed: call check, find the noun, and do not retry blindly - a retry creates a second one Creates and imports: create_collection, create_request, create_request_example, create_environment, import_document, start_mock_server, start_mock_issuer, start_webhook_inbox
"never-blind" It may still have completed: check run history (list_runs) before retrying Sends and run starts: run_request, run_collection, run_collection_smoke, start_load_run
"safe" Repeating the call is safe Reads and re-applicable writes that do not carry idempotentHint: true: list_request_examples, get_live_metrics, get_mock_activity, get_inbox_captures, update_environment, update_globals, sync_spec, bind_spec, fetch_oauth2_token

A tool annotated idempotentHint: true needs no declaration and is told safe. Any other tool must declare one (tools.test.ts scans the registry), because a tool that declares none falls back to the never-blind wording, which sends an agent to run history for a call that never wrote a run.

Resources

Read-only Vayu data an agent can attach as context (resources.ts):

URI Contents
vayu://runs The most recent 100 runs (first page), newest first; pagination.total / hasMore in the content carry the full count. A resource takes no arguments, so filtering and paging beyond this page is the list_runs tool's job. Masked as list_runs is.
vayu://collections All request collections as a bare array, unpaged, each shaped as a list_collections full row (a declared data-file contract as dataSchema, none as no key; a remembered file as dataFile; secrets withheld the same way).
vayu://environments All environments, secret values withheld as list_environments withholds them.
vayu://variables/resolution The resolution rule set: tier order, disabled/non-string handling, reserved namespaces, and what a script's scoped and merged reads see. See Variables.
vayu://config Engine configuration entries, a URL entry's credentials withheld as get_engine_config withholds them.
vayu://scripting/completions The script sandbox's full API surface (see below).
vayu://scripting/types The same surface as TypeScript declarations - the .d.ts the app's editor loads, so a call's parameters and return type are the running engine's.
vayu://elements/kinds The element registry's catalogue (see below): every kind's category, phases, hot-path class and config JSON Schema.
vayu://run/{runId}/report A run's full report (templated), masked, bounded (the 32 KB body cap and the trace budget) and marked partial while the run is unfinished, all as get_run_report is (readRunReportForAgent, #3557).

The templated report resource has a list callback (enumerates recent runs so each shows in resources/list) and a completion callback (autocompletes run IDs).

The script sandbox surface

preRequestScript and postRequestScript run in the engine's QuickJS sandbox, which is the same sandbox the app's editors target. There is exactly one per-client capability gate inside the sandbox - pm.sendRequest, below - and, with reveal on, an agent can do anything else a script in the app can. With reveal off the agent cannot supply a script to a send or a load run at all (see Scripts an agent supplies are refused, above), though it can still read this surface to understand the scripts stored in the app. What an agent lacked was any way to know that: until issue #233 the entire script surface it could see was the two sentences in those fields' descriptions, so pm.expect chains, pm.response.to.*, the variable scopes and pm.crypto were invisible and simply never attempted.

Two resources, because a name and a signature are different questions. vayu://scripting/completions re-serves GET /scripting/completions (Monaco's own fields projected away) and answers what exists; vayu://scripting/types re-serves GET /scripting/types, the .d.ts the engine generates from the same table, and answers what it takes and returns (issue #760). Both throw rather than serve a partial surface - an agent reading a truncated API list concludes the sandbox cannot do what it can - and neither holds a copy of the surface here, which is the whole point: the app's own quick-reference panel had gone stale before #233 and this is what replaced it.

The element catalogue

vayu://elements/kinds re-serves GET /elements/kinds, the element registry's catalogue (issue #1513): every kind's category, the phases it runs at, its hotPathClass and its configSchema - the same shape the app's generated element forms read (issue #1516). create_request / update_request / create_collection / update_collection's elements argument and run_request's ad-hoc elements argument both name a kind as a bare string rather than an enumerated one, precisely so a kind the engine adds later needs no MCP change - read this resource rather than guessing a kind or its config shape. A property with a default in that schema is run with that value when its key is left out, so an agent omits the key rather than restating it (assert.size with no op compares lte, an extract.* with no scope writes the collection scope; issue #3045). element-kinds.conformance.test.ts pins the resource, the schema's own examples and every kind literal a tool description names to the engine's own fixture, so a kind renamed engine-side without a matching update here fails the build rather than telling an agent to write a kind that no longer exists.

pm.sendRequest is refused for MCP-started runs

The sandbox can send an auxiliary request (issue #302). That would be a hole in the allowlist if it applied here, and the reason is structural rather than an oversight: the allowlist is checked in this server, against the composed URL, before it calls the engine, and handed to the engine as targetPolicy for the URL a send is about to dial (#2521). A request issued from inside a script with pm.sendRequest goes through neither - it is not the send's URL - so it could never be checked: an agent that can write a script would otherwise reach any host, defeating a control the user set in Settings.

Three ways to close that were available, and this is which one and why:

  • Move the allowlist engine-side for script-issued requests. Rejected when this was decided (#302): the allowlist lives in the app's config, and the engine had no channel to it, so it would have needed a second implementation of host matching alongside safety.ts's - two copies of a security check, which drift. #2521 has since added that channel and a second matcher for the send's own URL and OAuth 2.0 token endpoints (targetPolicy), because a pre-request script can retarget those. It still does not reach a pm.sendRequest, and the choice below stays the control for those.
  • Gate the feature off by default behind a setting. Rejected. It adds a knob whose safe position is the only correct one for MCP, and the hole reopens the moment anyone flips it for an unrelated reason.
  • Refuse script-issued requests unless the caller explicitly asks. Chosen. The engine denies pm.sendRequest unless the execute/run payload carries allowScriptRequests: true. The app's own Send and load runs ask for it, each in the one service method that owns that call (apiService.executeRequest and executeStreamRequest - Send's two halves - plus startLoadTest / startScenarioRun); this server never does. The allowlist stays exactly where the user configured it, and the engine gains a capability bit rather than a policy copy.

Denying by default is the load-bearing half: a new tool here, or any future engine client, gets a script that cannot send rather than unchecked egress. An agent cannot set the field either - every tool builds its request from named arguments, and no tool declares allowScriptRequests, so a call naming it is refused as an unrecognized key before any handler runs.

A script that calls pm.sendRequest under MCP throws a message saying why, so an agent is told rather than left with a silently missing global. The completion entry states the same thing, so the surface an agent reads and the surface it gets agree.

vayu://scripting/completions closes that. It re-serves the engine's own GET /scripting/completions - the single source of truth that also feeds Monaco, generated from one table in engine/src/http/routes/scripting.cpp and cross-checked against the runtime by script_completions_test.cpp. Notably it carries pm.crypto.sha256 / .hmacSha256 and the btoa / atob globals, and their documentation states they are synchronous (the sandbox has no event loop, so nothing Promise-based would ever settle).

Each entry is trimmed to label, detail and documentation; Monaco's own insertText, insertTextRules, sortText, filterText and kind are dropped, since snippet placeholders and a CompletionItemKind enum mean nothing outside an editor. The trim is the only transformation - no list of pm.* names is maintained app-side, which is the point: a name the engine adds reaches agents with no second edit, and resources.test.ts fails if the resource ever answers from a local literal instead of the engine. The tool descriptions carry one sentence pointing here, for an agent that never lists resources.

Prompts

Server-provided starting points a user picks in their client (prompts.ts):

Prompt Arguments Produces
summarize_run runId The run report (masked, bounded and marked partial as get_run_report is) + a "summarize p50/p95/p99, errors, health"; tells the model to read partial first and not to call an unfinished run healthy or concerning (#3557).
compare_runs baseRunId?, targetRunId The computed delta, its comparability list (which the prompt tells the model to read first) + "did this regress?". Two runs of different types get the tool's refusal instead, with no delta embedded. An omitted baseRunId resolves the target's pinned baseline through the same resolveBaseline the tool uses - the prompt demanded an id Vayu already knew (#760).
diagnose_errors runId The report (masked, bounded and marked partial as get_run_report is) + an error-focused diagnosis prompt, with the same read-partial-first instruction (#3557).
suggest_load_profile url, goal? Guidance to design a start_load_run (no engine data); tells the model to read get_safety_config first, so a profile is sized to the session's caps and allowlist (#2444).

summarize_run, compare_runs and diagnose_errors each state the engine's one error definition in their text, from error-definition.ts's RUN_ERROR_DEFINITION_SENTENCE (issue #2124), and so does the vayu://run/{runId}/report resource. Of the tool descriptions only get_run_report carries the whole sentence; get_live_metrics, compare_runs, get_run_timeseries and export_run_report carry RUN_ERROR_DEFINITION_POINTER, one line giving the two halves of the definition and naming get_run_report for the rest, because the sentence repeated in five descriptions was most of what tools/list spent on it (#2441). An agent reading errorRate is told what counts: a status outside 2xx/3xx or no response, a 3xx being a success, with the httpErrors / noResponse split beside the count. The fields themselves are the engine's, passed through unchanged (see What counts as an error), including the separate cancelled / cancelledRequests count of requests a Stop cancelled, which is no error (issue #2136); the sentence says so in a clause of its own and names cancelledRequests as where it is reported.

Safety model

Enforced in the MCP layer (safety.ts, config.ts), with two exceptions noted below: the engine applies the allowlist again to the URL a send is about to dial, to OAuth 2.0 token endpoints and to a load run's monitor.url (targetPolicy, #2521, #3121), and script-issued requests are refused engine-side, because this layer cannot see them. Nothing here changes engine behaviour for other clients: a payload without a targetPolicy is unrestricted. All configurable in Settings → MCP and persisted (in the stdio CLI, through the VAYU_MCP_* variables, and a refusal there names the variable - see Configuration).

  • Target allowlist (default empty ⇒ deny all). Network-touching tools refuse off-list hosts with an actionable error. An "Allow all hosts" opt-in bypasses the list (still rejects unresolved {{variables}}); off by default. Entries are hostnames, matched exactly: what you type in Settings is reduced to a host (https://api.example.com:8080/v1 and api.example.com are the same entry), and the request URL is matched by its host whether or not it carries a scheme (localhost:3000/api matches the entry localhost). An IPv6 target is stored and shown in its canonical bracketed form - typing ::1 stores [::1], which is what a URL parses to. A run's monitor.url is a second host and gets its own check, with one deliberate exemption: a loopback or private-network monitor endpoint (localhost, 127.0.0.0/8, 10/8, 172.16/12, 192.168/16, ::1, fc00::/7) needs no allowlist entry, while a public one is checked exactly as the target URL is. Link-local and cloud-metadata addresses are not exempt (#2370): 169.254.0.0/16 (which holds 169.254.169.254, the metadata service on AWS, GCP and Azure), fe80::/10 and AWS's IPv6 fd00:ec2::254 need an allowlist entry like a public host, because a scrape of one reads credentials rather than the user's exporter. The rest of fc00::/7 stays exempt. The allowlist exists to stop an agent generating traffic against third parties it was never pointed at, and a private address, link-local aside, is the user's own network - which is also the feature's own case, since the endpoint a load run wants beside it is the target's own localhost:9100. The test is textual, like the allowlist itself: a DNS name that resolves to a private address still needs an entry, because resolving it here would make the answer depend on the network it was asked on. The engine holds monitor.url to the run's targetPolicy with no exemption of its own (#3121), so the exempt host is added to the run's allowedHosts (see Request composition). The renderer's load-test dialog uses the same classification to tell a local target from a remote one (isLocalHost in src/lib/host-locality.ts, a mirror of isPrivateHost that the main process cannot share); host-locality.conformance.test.ts fails on any divergence. Because the check happens here, before the engine is called, the URL a pre-request script rewrites is not seen by it - the engine applies the same list to it (targetPolicy, see Request composition) - and a request sent from inside a script could not be checked at all, so pm.sendRequest is refused outright for runs this server starts. See The script sandbox surface.
  • Hard caps - max RPS / virtual users (concurrency) / duration / iterations / response samples (maxResponseSamples) on start_load_run; over-cap requests are rejected. With the allowlist, these are the real limits on load, and they cover every field the tool forwards:
    • concurrency and startConcurrency are both held to the virtual-user cap (Max virtual users in Settings). A ramp is seeded with startConcurrency before its first duration check, so capping only the target would bound where a run ends and not where it starts.
    • An iterations run stops on a request count and never reads duration, so no duration cap can bound it. Max iterations is its own setting for that reason (10000 by default). An omitted iterations is sent and compared as the engine's own default of 1000. The schema refuses an unrecognised mode, and the guard still reads one carrying an iterations field as an iterations run, because the engine runs it as one.
    • maxResponseSamples is held to its own cap (Max response samples, 10000 by default) because each response kept for the sampled script and schema replay is a full body in engine memory until the replay has run. An omitted one is judged as the engine's default of 1000, so a cap under 1000 refuses a run that states no count and the refusal says so.
    • An omitted field is judged as the default the tool sends for it (Load defaults), not as "unbounded": an omitted concurrency on a constant run is 100 virtual users, so a Max virtual users under 100 refuses it with the same message a stated 100 gets, and so does an omitted concurrency on a capacity run, whose search climbs to 100 (#2493). An omitted duration is the mode's default (60s, or 300s for capacity) unless maxDurationSeconds is shorter, in which case the cap is sent in its place and the run is bounded by it. concurrency, startConcurrency, iterations and maxInFlight are additionally constrained to positive integers by the tool's own schema, because "unlimited" is an obvious guess to spell -1 or 0 and the engine reads them as an eager per-worker pre-allocation count, a ramp seed, a request budget, and an in-flight ceiling (see the accepted ranges under POST /runs). maxInFlight is the one that bounds work downward, so there is no separate cap setting for it - the enormous value is the one that removes the backpressure the caller asked for; its schema additionally carries the engine's own ceiling of 1000000, so a value this tool accepts is one POST /runs accepts. duration / rampUpDuration are also rejected when they are not durations at all (ms/s/m/h, or a bare number of seconds - the same grammar the engine parses), since the engine refuses such a run with a 400 rather than quietly substituting 60s; a zero duration is rejected here for the same reason the engine 400s it, while a zero rampUpDuration stays legal (an instant ramp).
  • Confirmation - anti-accident, not anti-adversary: it stops a stray tool call from starting load or destroying saved work, but where the client cannot be asked it is agent-side (the caps/allowlist are the enforcement). A question to the person upgrades it to a human decision where the client can be asked. The question is an input_required result: the call does nothing, the client asks, and the call is made again carrying the answer, so a gated tool reads and nothing more before its gate. Eight tools carry it - start_load_run, delete_collection, delete_request, delete_request_example, delete_run, delete_environment, delete_webhook_inbox and purge_trash_entry - through one implementation (confirmDestructive), so the question cannot drift between them. A preview is a successful result that deliberately did nothing, so it emits no mcp:data-changed event either. restore_trash_entry deliberately does not carry it: it puts data back rather than destroying it, so the write toggle alone is its gate (below).
  • Write toggle (allowWrites, default off) - gates every tool in the write category, and while it is off they are not registered at all: they are absent from tools/list, not merely refused by tools/call. A call on one of their names anyway - guessed, or held over from a list fetched while the toggle was on - is answered with the handlers' own refusal, which names the setting to turn on; the SDK would otherwise reject the unregistered name as invalid params (-32602, Tool <name> not found), which tells an agent nothing it can act on. The SDK has no hook in front of its own dispatch, so server.ts captures the tools/call handler it installs and puts the refusal in front of it; the protocol test that calls a withheld name is what holds that to the SDK across an upgrade. The server instructions say the same thing up front, in the sessions where the toggle is off, and name the task families that need write access (saving or deleting collections and requests, environments and globals, an import or a spec bind, clearing cookies, changing engine config) so an agent that sees no write tool does not conclude the MCP cannot save (#2442). They name families, never tools, and protocol.integration.test.ts classifies every write tool into one, so a new write tool fails until its family is in the sentence. Withholding the schema rather than only the call is what makes the toggle free: those tools are 66,077 of the 181,447 bytes (36%) of the tools/list an agent is sent (app host, reveal off, measured at #2441), and on a default install none of them could have succeeded. Write access is a separate grant from reveal: a script stored by a write tool (create_request / update_request / create_collection / update_collection, or an import) is not refused while reveal is off, and runs with the secrets under run_collection_smoke, run_collection and start_load_run. That is a residual of write access, not a gate. A send writes saved data too, through the variables it sets: an extractor in run_request's elements does (its default scope is the collection), and so does an agent's own script once reveal is on. With the toggle off, run_request sends persistVariables: false on both its buffered and its streaming path (#1904): every script and extractor still runs and reports, a value one sets is visible for the rest of that send, and nothing reaches the environment, the collection or the globals. With the toggle on the key is absent and the engine persists as it does for the app's Send. run_collection_smoke and run_collection are not covered: they replay the scripts and extractors stored on the requests and save back what those set, which is the write-access residual above. start_load_run never persists a variable at all. Because the tool set is recomputed per built server (a fresh one per HTTP request), flipping the toggle takes effect on the client's next tools/list - the same timing the per-tool switch below already has. The category is every tool declared category: "write" in tools/*.tools.ts - 28 write tools: create_collection, update_collection, delete_collection, create_request, update_request, delete_request, create_request_example, update_request_example, delete_request_example, move_item, create_environment, update_environment, activate_environment, delete_environment, update_globals, clear_cookies, update_engine_config, set_run_baseline, delete_run, delete_webhook_inbox, clear_inbox_captures, restore_trash_entry, purge_trash_entry, sync_spec, import_document, bind_spec, unbind_spec, clear_oauth2_token. Does not gate run_request / run_collection_smoke / load runs (allowlist + caps). Seven of those need the toggle and confirmation - the six deletes plus purge_trash_entry: the toggle is a single session-wide switch a user flips once to let an agent save a request, which is not consent to destroy a subtree, a run's stored history, or a trashed row for good. clear_cookies and restore_trash_entry take the toggle without a confirmation, for opposite reasons: one ends a session rather than anything saved, the other puts a row back rather than destroying one.
  • Network gate (allowNetworkSettings, default off) - the second key update_engine_config needs for the entries that decide where every request goes and whom it trusts: every proxy* key (proxyMode, proxyUrl, proxySystemUrl, proxyBypass, matched by prefix and case-insensitively, so a proxy key added later is gated the day it ships) and customCaCertificates (#1805). A batch naming any of them without the gate is refused whole, before the engine sees it. The allowlist cannot stand in for it: it checks the host a request names, never the proxy the request leaves through, and a trusted CA is what lets that proxy read TLS. On its own it grants nothing; the write toggle still decides whether update_engine_config is offered at all.
  • Reveal secrets (revealSecretsToAgents, default off) - while it is off, an agent reads no secret through any tool: reads withhold secret variables, auth credentials, credential header values, cookie values and proxy URL credentials, write tools answer through the same projection and refuse to clear a secret flag, and run output reads <redacted> for a secret variable's value and a credential header's value. The server instructions say so; see Secret values.
  • Loopback services carry no gate of their own - start_mock_issuer, stop_mock_issuer, update_mock_issuer, start_mock_server, stop_mock_server, start_webhook_inbox, stop_webhook_inbox and update_inbox_response are execute tools that neither the allowlist nor the write toggle governs. (The two that destroy recorded data, delete_webhook_inbox and clear_inbox_captures, are write tools and do take the toggle - what they end is not the listener but the captures.) The allowlist exists to stop an agent generating traffic against third parties it was never pointed at, and a mock issuer is bound to 127.0.0.1 by the engine with no host to configure - as is a mock server, and as is an inbox, whose bind these tools never send; the write toggle gates saved data, which an ephemeral listener is not (a mock server only reads the examples it serves). Nor would a gate here withhold anything: an agent with localhost allowlisted can already reach POST /mock-issuer/start through run_request, for the same reason the endpoint needs no auth token. The bounds that do apply are the engine's own - at most 8 issuers at once - and the per-tool switch below.
  • Per-tool control - any tool or whole read/execute/write/load category can be switched off; a disabled tool is omitted from tools/list, and calling its name is rejected as invalid params (-32602, Tool <name> not found) - it is unregistered, so the SDK rejects the name before any Vayu code runs. (The write toggle's refusal above is the deliberate exception, and it does not claim a tool the user switched off: that tool would still be off after enabling writes. The rejection in dispatchTool is what any other caller of it gets.) Settings lists every tool whatever the write toggle says, so the switches for write tools stay visible and settable while writes are off - the toggle governs what the agent is offered, not what the user can configure. This and the write toggle are independent, and a write tool needs both: switching the write category on here does nothing while allowWrites is off, and turning allowWrites on re-enables no tool that is in disabledTools. Settings states this on both cards, because a user who flips one switch and sees no change has nothing else to go on.
  • Server on/off - the whole server can be disabled; while off the endpoint does not accept connections. Persists across restarts. Off holds even when it lands mid-start: the bind in flight is closed rather than published (lifecycle.ts).
  • Transport hardening - loopback bind, Host- and Origin-header (DNS-rebinding) validation, POST-only, 4 MB body cap.

Why no auth token on the endpoint: any local process could already reach the engine's REST API on :9876 (or its fallback); the MCP endpoint proxies the same capability behind more guards and adds DNS-rebinding protection. It grants no capability a local process did not already have.

Load defaults

start_load_run resolves every load-shape field the agent leaves out to the value the engine would otherwise use, and sends it explicitly, so the caps, the confirmation preview, the stored run (list_runs rows, get_run_report's metadata.configuration) and compare_runs all read the same numbers (#2437). A stated value is never replaced. A single-target run takes the strategies' defaults, named in run_config and capacity in engine/include/vayu/core/constants.hpp:

Mode concurrency startConcurrency duration rampUpDuration iterations
constant_concurrency 100 - 60s - -
constant_rps 100, none when targetRps paces the run - 60s - -
ramp_up 100 1 60s 10s -
iterations 10 - none (never read) - 1000
capacity 100, the search ceiling the engine's own 300s - -

A scenario run (scenario) takes its executor's own defaults (execute_scenario_load, engine/src/core/scenario_load.cpp): 10 virtual users in each of its three modes, with the same duration, ramp, start and iteration defaults as the table. In every mode an omitted duration is the cap instead when Max duration is shorter. A constant_concurrency run is closed loop at its virtual users. A constant_rps run with a targetRps is open loop and no concurrency is sent; a mode-less call with a positive targetRps resolves to constant_rps. A targetRps beside an explicit constant_concurrency (or any other mode but constant_rps) is not resolved away: it is forwarded and the engine answers 400 invalid_run_config (#2396), so the one rule stays in the engine. capacity's sloMs and stepDuration stay engine-side. safety.test.ts reads both engine files, so a changed default fails the app suite until the table above and the tool's follow it.

Secret values

With Reveal secrets to agents (revealSecretsToAgents, default off) in Settings → MCP off, an agent reads no secret through any tool, resource or prompt (#1805, #1809). Four paths lead to a secret - what is stored, what a write tool answers, what a run recorded, and clearing the secret flag - and each is closed below. Withheld is stated, never a silent omission, so an agent cannot read a missing value as an empty one.

What is stored is withheld as a field the projection replaces:

What Withheld as Read by
A variable whose secret is true (any other value is not a secret) value dropped, valueWithheld: true list_environments, get_globals, list_collections (full rows), resolve_variables, vayu://environments, vayu://collections
An auth credential: token, password, value (an API key's), clientSecret, secretKey, accessKey, sessionToken, accessToken, refreshToken, idToken, secret, authKey, consumerSecret, tokenSecret, clientToken, privateKey, code_verifier, at the top of the block or under config the member dropped, <member>Withheld: true list_requests (full rows), get_request, list_collections (full rows), vayu://collections
A credential in a Postman import's postman source (the auth as Postman wrote it): a v2.1 {key, value, type} attribute whose key is one of the names above, a v2.0 {name: value} member named one of them, and a parameter row (tokenRequestParams, authRequestParams, refreshRequestParams) whose key is one of them or client_secret, client_assertion, refresh_token, access_token, id_token, assertion, or a header or query name from the params row below (Authorization, X-Api-Key, api_key, and the rest: a row can be sent as a header) a row's value dropped, valueWithheld: true on the row; a v2.0 member as above list_requests (full rows), get_request, list_collections (full rows), vayu://collections
A credential in an OAuth 2.0 config's extra request parameter rows (authorizationParams, tokenParams, refreshParams, #2536), by the same key names as the Postman rows above; and, as the export's redact_config_param_rows treats them, a row with no non-empty string key, a row member other than key, value, enabled and sendAs, or a list that is not an array, each when it holds a non-empty string that is not a pure {{variable}} reference the row's value dropped, valueWithheld: true on the row; key, enabled and sendAs stay. A keyless row becomes {valueWithheld: true}, another member <member>Withheld: true, a list that is not one <list>Withheld: true on the config list_requests (full rows), get_request, list_collections (full rows), vayu://collections
The value of a credential-bearing header row in a saved request or example (Authorization, Proxy-Authorization, Cookie, Set-Cookie, X-Api-Key, X-Auth-Token, X-CSRF-Token, or the header the request's API-key auth names, whatever its in says; disabled rows included; an empty value or a pure {{variable}} reference is shown as written) value dropped, valueWithheld: true on the row (a row written back that way keeps its stored value, see what a write tool answers, below) list_requests (full rows), get_request, list_request_examples
A saved request's url and params (#1837): the password of user:password@ userinfo is dropped (the user stays), and the value of a credential-named query or fragment parameter is emptied (?api_key=S&page=2 becomes ?api_key=&page=2); a params row with such a name, disabled rows included, loses its value. Names are SENSITIVE_PARAM_NAMES, matched whole and case-insensitively, plus the key of an API-key auth placed in: "query"; code and key are data, not credentials; an empty value or a pure {{variable}} reference is shown as written. The export's rule (#1804), ported rather than redefined the URL as above, with no marker (an emptied slot written back keeps its stored value, see what a write tool answers, below); a params row value dropped, valueWithheld: true on the row list_requests (a summary's url too, masked on the whole row before the summary is cut), get_request, delete_request's preview and prompt, run_collection_smoke's url on every row (the stored URL for a request that failed to compose; the composed one otherwise, which run output below also masks), get_graphql_schema's endpoint (the composed URL; the SDL is never withheld)
A cookie value value dropped, valueWithheld: true get_cookies (full rows; a summary row has no value)
The userinfo of a config entry whose key ends in url (proxyUrl, proxySystemUrl) stripped from value, the host kept, credentialsWithheld: true on the entry (the value written back unchanged keeps them) get_engine_config, update_engine_config's updated echo, vayu://config
The current side of a spec drift entry's headers, url or params change when it could carry a credential: a header row with a value named by the shared sensitive list or by the request's own API-key auth, whatever its in; a url the saved-request rule above would change, or one the engine's 120-character cut ended before its host did (a cut password has no @ left to find); a params row with a value named by SENSITIVE_PARAM_NAMES or by the request's own API-key-in-query auth (the tool reads the stored request's auth for each entry with a headers, url or params change, only while reveal is off; a request it cannot read has those fields withheld whole when non-empty rather than judged). The engine's line is lossy, so it is withheld whole, and an ordinary change passes as written current dropped, currentWithheld: true diff_spec

What a write tool answers goes through the projection of the read of the same row (echoShape, withholdReorderRows), so writing does not grant reading: create_collection, update_collection, unbind_spec, create_request, update_request, restore_trash_entry, create_request_example, update_request_example, move_item (the renumbered rows), create_environment, update_environment, activate_environment (either direction) and update_globals answer the row they changed with the rows above withheld. The write that would lift the withholding is refused: secret: false over a stored secret: true on a variable of an environment, the globals or a collection is an error naming the setting, because the next read would return the value. A value the read emptied and the agent writes back is carried forward rather than stored empty (#3549): update_request re-reads the row and keeps each credential slot of its url the call still holds as the read showed it (the password after the same user, a credential-named query or fragment pair by name and occurrence), and update_engine_config writes a URL entry repeated as the read showed it as its stored value. Each kept slot is named in a caveat line. A header row of a saved request or example is the same (#3550): create_request, update_request, create_request_example and update_request_example take headers as the rows the read returns, and a row written back with valueWithheld: true and no value keeps the value of the stored row with the same name (case-insensitive) and occurrence, while one with no such stored row (on a create, any) is an input error naming the header. A headers map still replaces the list, one enabled row per name; while reveal is off, update_request and update_request_example read the stored row first and name, in a caveat line, each stored row whose value the read withheld that the write left out. An example is read from its request's list, since there is no by-id read, and written under its version as a request is. So an agent cannot set such a slot to literally empty over a stored value: removing the parameter or the userinfo deletes it, and a proxy URL's credentials go when it is cleared or its address changes. secret: true and every other edit pass, and with reveal on nothing is refused. Removing a variable and creating it again stores the value the agent sent, which is no secret of the user's.

What a run recorded is masked in place with the engine's <redacted> marker, so the record keeps its shape (runOutputShape). A request that references a secret still sends it, so the trace holds the resolved value in whatever encoding it went out in; an agent reads <redacted> there instead:

What Masked as Read by
The value of every secret variable of the workspace (globals, every environment, every collection), and every literal credential a stored collection's or request's auth holds (the members the first table withholds; an empty value or a lone {{variable}} is none), in any string of the output, in its raw, percent-encoded (url_encode, query, and a URL's path, fragment and user info as composition writes them), JSON-escaped and XML-escaped forms; a value under 4 bytes is not masked, and a base64 body (bodyEncoding: "base64", #2458) is searched as the bytes it decodes to, never as its base64 text, where a match is coincidence: each form is matched as UTF-8 bytes and as Latin-1 bytes, the marker replaces the bytes it matched, and the body is re-encoded so it still decodes (bodySize / bodyBytes keep the engine's count; a body with no match comes back unchanged) the value replaced by <redacted> run_request (the response, and the events of a streamed one), get_run_report, get_run (its mode / duration echo; the projection carries no other stored text), export_run_report (the document text), get_run_samples, list_runs, get_inbox_captures, get_mock_activity (each entry's path), set_run_baseline, run_collection_smoke (each row's url, reason, error and failing test lines; every row's url is also withheld as a saved request's is, in the table above, so a credential typed literally into it does not pass), start_load_run's confirmation preview (the planned run and the question that names its target), vayu://runs, vayu://run/{runId}/report, the summarize_run and diagnose_errors prompts
The value of a credential-bearing header (the names above, plus the header any API-key auth block names whatever its in says, including one sent inline: the engine's api_key_header_names) in a header map, a header row list (a response's headerLines, an exchange's requestHeaderLines, a trace's sentHeaderLines and each redirect hop's redirects[].headerLines, #2461, included) and a rawRequest header line, request and response alike <redacted> after the name the same
The value of the query parameter auth wrote into the request at send time, named by the trace's request.authQueryParam (an OAuth 2.0 token or an API key placed in the query; the engine's raw, unencoded name), in the sibling url and in the request line of the sibling rawRequest; and the headers named by request.authHeaders, in the sibling headers, sentHeaders and rawRequest header block, beside the names above (#1835). run_request's answer carries both keys at its top level (#1845), where the record has no url and requestHeaders stands for headers. On run_request's answer the same name masks each followed redirect hop's redirects[].url (#2949), since the hop sits beside the key; a stored trace keeps the hops under response and the key under request, so there a hop's url is masked by the secret forms and the credential-named rule, and by the engine, which blanks the auth-written parameter in the hop URL it records. The authNotice beside them, saying auth sent nothing (a mode Vayu does not execute, #2474, naming the mode; an empty bearer token or API key name, #3203) or that the request's own Authorization header was sent in place of an OAuth 2.0 token (#3202), is a plain string, carries no credential and is not masked <redacted> after the name the same
The value of a credential-named query parameter (SENSITIVE_PARAM_NAMES, the saved-request rule above, whole name and case-insensitive) in the url of a record (a followed redirect hop's url included, #2949) and in the request line of a rawRequest, whether it was typed into the saved URL, came from a Params row or was written by auth: a credential that is no secret variable and no stored auth credential has no form to match, so the name is what masks it (#1909). ?api_key=LIT&page=2 reads ?api_key=<redacted>&page=2; api_key2, an empty value and a lone {{variable}} are shown as written. Only the query between the first ? and the first # is read, so a fragment parameter is not masked here <redacted> after the name every read of run output above, and delete_run's confirmation prompt, whose subject line names the run by its url
The password of a URL's user:password@host userinfo, in the url of a record (a followed redirect hop's and a monitor's included) and in metadata.requestUrl of a run report, the member the engine copies from the run snapshot's url and which is read exactly as url is, so its credential-named query values are masked by the row above. The password is dropped and the user name kept (http://u:LIT@h/p reads http://u@h/p), as a saved request's url is, so the record keeps its shape; a lone {{variable}} password and a URL with no password are shown as written. Only the authority is read, so an @ in the path, query or fragment is not taken for userinfo the password dropped every read of run output above, get_run_report and vayu://run/{runId}/report included
The planned run's auth block, composed with the stored or inherited credential in it as a stored row's: the member dropped, <member>Withheld: true start_load_run's confirmation preview

The masking is the engine's own rule for a run's config snapshot (#1803), applied to what a read can know: the secrets of every scope rather than only the run's, because a run row names its environment but not the collection chain an inline send resolved through, a list reads many runs at once and an inbox capture belongs to no run. A literal credential typed into a stored auth block is no variable, but the engine writes it onto the wire after composing (an API key in: "query" lands in the trace URL and rawRequest), so it is masked as a value too. A credential no stored row holds, such as an OAuth 2.0 token the engine fetched, is masked by where it went instead: the stored trace names the query parameter (request.authQueryParam) and the headers (request.authHeaders) auth wrote, run_request's live answer names them as authQueryParam and authHeaders at its top level (#1845), and the masking reads them per record. run_request passes the engine's top-level authNotice (#2474, #3202) and warnings (#3307, [{code, message}], [] when empty; a cookie named by name only, never a value) through as they came, unmasked, and get_run_report keeps a stored trace's top-level warnings beside its bounded request and response. The parameter is matched on its whole name, case-sensitively, in the URL's query (between the first ? and the first #) and in the request line only, as the engine wrote it: raw, or percent-encoded as encode_query_component writes a key unless the request disabled URL encoding. A pair of that name is masked wherever it appears in the query, the user's own included; api_key leaves api_key2 alone, a body is untouched, and an empty value or a lone {{variable}} is shown as written. The credential-named parameters of the saved-request rule are masked in the same two places by the same bounds, but case-insensitively, as that rule matches them. With URL encoding disabled, a value holding a raw & ends at it. The values are read when the tool is called, so a secret rotated since masks under its new value only. Keys are not touched, nor numbers, so a size the engine reported still describes what it measured. A tool that cuts a body to a byte cap (run_request, get_run_report, get_inbox_captures) masks before it cuts, because a cut through an unmasked secret leaves a prefix no form matches. compare_runs forwards numbers only and has nothing to mask.

Masking fails closed. It needs four reads (the globals, the environments, the collections, every request) to know the values it masks. If any of them fails, the read answers an error naming the lookup that failed and that masking could not complete, and returns none of the result: masking with the reads that answered would hand over every secret the failed one holds. A tool answers it as an error result, a resource or a prompt as a failed request (MaskingIncompleteError). A tool that sends traffic (run_request, run_collection_smoke) has already sent it when it answers so; the run is in list_runs once the engine answers again. With reveal on none of the reads is made.

A tool words that error by the lookup's cause (#2780, maskingIncompleteResult in kit.ts), and a resource or a prompt does the same through maskingOutageMessage (#2854), so its failed request carries the same text. When the engine refused the connection or answered with a failure it classes unreachable or transient, the answer is the same one every other tool gives (Could not reach the Vayu engine ..., Engine error (500): ...), in that class, followed by a sentence that the result is withheld whole until the engine answers; the Reveal secrets setting is not mentioned, since it is not a remedy for an outage. Any other cause, including the Unexpected error fallback and an engine refusal of the lookup itself (a 4xx), keeps the masking message naming the lookup that failed. A resource or prompt read puts its own engine read and the lookups out together and settles both: an outage lookup failure leads even when the read failed first with a bare fetch failed, and a lookup failure that is not an outage yields to the read's own failure (a 404 for an unknown run). A cancelled read says so without a tool call's "may have completed" advice, since a read sent nothing.

An engine refusal's text is masked too. The engine words its refusals to quote no resolved variable value (a header name is quoted as written, with the one byte at fault), but that is the engine's rule to keep, so a tool error built from an engine refusal body (Engine error (400): ..., a restore_trash_entry 404 or 409, the engine's 404 sentence) reads each secret form as <redacted> under the rule above, in its text and in structuredContent.error.advice. The mask is applied in dispatchTool (maskEngineText, kit.ts), keyed on the failure's engineText mark, so an error that holds no engine text (a missing argument, a policy refusal) makes no lookup and an outage needs none. It fails closed like the reads above: when a lookup fails the answer is the masking error and none of the refusal text. With reveal on nothing is masked and no lookup is made.

The stored trace stays raw on purpose: Vayu's own History shows what went over the wire, and the engine's rows are unchanged. Only the MCP read is masked.

The credential lists are the engine's own SECRET_AUTH_KEYS and SECRET_PARAM_KEYS (core/vayu_extensions.cpp), the sets a collection export blanks, and the postman walk is its redact_postman_auth; the header names are the shared sensitive-header list and the parameter names are the engine's is_secret_param_name set, both pinned to the engine's by withhold.conformance.test.ts (sensitiveHeaderNames and sensitiveParamNames in log-redaction-conformance.json). An auth member or row holding one {{variable}} reference and nothing else is shown as written, the way the export keeps it: it names where the secret lives without being it, and the variable it names is withheld on its own terms. An auth block carrying a withheld marker (a <member>Withheld member, top level, under config or in its postman source, a valueWithheld row in that source, or any ...Withheld marker on or in place of a config extra parameter row or list) is refused as auth by every tool that takes one (readAuthArg): stored, it would replace the user's credential with nothing, and sent, it would authenticate with nothing.

The other marker, <redacted>, is what a run's record shows in place of a credential (above), and a request copied out of one carries it back. It is refused as input in the credential slots a read withholds, exactly as the ...Withheld markers are, and only as the whole value (isRedactionMarker in withhold.ts; tools/redacted-input.ts holds the refusals): an auth member (readAuthArg, so every tool that takes auth), the value of a credential-named header (a row of create_request, update_request, create_request_example and update_request_example, or a headers override of run_request, start_load_run and get_graphql_schema; a row written back as valueWithheld: true has no value to judge), the value of a credential-named query or fragment parameter or the userinfo password of a request's url (create_request, update_request, or the url override of run_request and start_load_run), and the value of a variable that is, or is being written as, secret: true (every tool that writes a variable blob). The call is refused before anything is written or sent, and the error says to pass the real value or a {{variable}} reference. A request body, a description, a header or parameter no read withholds, and a value that only contains the text are stored as written, and with reveal on nothing is refused: the marker then stands for nothing.

The server instructions state the withholding rules once, in full, in every session where reveal is off, beside the write gate's sentence and for the same reason, and the run and config resources repeat the rule for their own output. Each tool that carries one of the rows above gets one line in its own description (withheldPointer(config, kind) in withhold.ts: what its result reads in place of a secret, and that the instructions give the rules), so an agent that never reads the instructions still learns that the marker means "withheld", not "missing". The line is empty when reveal is on, and so are the instructions' rules: a session gets the rules exactly when its tools carry the pointer, and with reveal on no description says Withheld or <redacted>. The projection lives in withhold.ts.

A script an agent sends is not a path: it is refused while reveal is off (see Scripts an agent supplies are refused, above). A script an agent stores through a write tool is outside that refusal and still runs with the secrets; see the write toggle.

Safety config

McpSafetyConfig (defaults in parentheses):

Field Default Ceiling Meaning
allowlist [] - Permitted hostnames (empty = deny all).
allowAll false - Bypass the allowlist for any resolvable host.
maxRps 1000 1000000 Cap on targetRps, which only constant_rps carries.
maxConcurrency 200 10000 Cap on virtual users: concurrency and startConcurrency (closed-loop).
maxDurationSeconds 300 86400 Cap on load-run duration.
maxIterations 10000 100000000 Cap on iterations (iterations mode).
maxResponseSamples 10000 1000000 Cap on maxResponseSamples, the responses a run keeps for the sampled script and schema replay; an omitted one is judged as the engine's 1000.
allowWrites false - Enable the data-mutating tools.
allowNetworkSettings false - Let update_engine_config change the proxy and trust-anchor keys.
revealSecretsToAgents false - Lift every withholding in Secret values: reads, write answers and run output.
disabledTools [] - Tool names to hide/reject.

An agent reads these through get_safety_config (#2444), in one call, so it sizes a profile or picks a target inside the limits instead of meeting each cap as a separate refusal. The allowlist is listed in full: it is user configuration, not a secret, and checkAllowlist already prints the whole list on any refusal. The three gates (allowWrites, allowNetworkSettings, revealSecretsToAgents) are on/off only, and disabledTools is reported as a count, because the server instructions name no tool and tools/list is already the authority on which exist. maxResponseSamples is not in the answer; the other four caps are. The server instructions name all four load caps (RPS, virtual users, duration, iterations) without their values.

The renderer never sets these directly: main.ts sanitizes every change (sanitizeSafetyInput - normalizes/de-dupes hosts, holds each cap to a whole number between 1 and its ceiling, trims and de-dupes disabledTools) before applying it live and writing it to disk. The same sanitizer runs over the persisted file on load and over the CLI's VAYU_MCP_* variables, so no path reaches the guards with a cap outside that range.

A mcp-config.json that does not parse (or parses to something other than an object) loads as the locked-down defaults rather than failing the start. The first write over it renames it to mcp-config.json.corrupt-<epoch-ms> in the same folder, so the allowlist and caps in it can be copied back by hand. One copy is kept: corrupting the file again replaces the earlier copy (issue #2433).

The ceilings are MCP_CAP_CEILINGS, mirroring the renderer's LOAD_TEST_CEILING_BOUNDS maxima - the engine's own guards where it has one (concurrency at 10x event_loop::MAX_CONCURRENT, durationSeconds at the per-transfer timeout guard); maxResponseSamples is the engine's run_config::MAX_RESPONSE_SAMPLES itself, since the load dialog sends no sample count. A cap set above its ceiling is held there rather than stored: the value it would admit is one the engine refuses or one no Vayu surface will compose, so storing it shows a guardrail that does not exist. The copy is tied to the renderer constant by config.test.ts, the way MAX_IN_FLIGHT_BOUND is - electron/ may not import src/.

maxRps and maxConcurrency bound different runs, which is why neither is a general "load cap": targetRps exists only in constant_rps (the engine refuses it on every other mode, #2396), so maxRps is inert against a closed-loop run - though the cap is read from any positive targetRps before the engine's refusal, so an over-cap rate on another mode is refused for its size first, and maxConcurrency bounds the virtual users a closed-loop run holds (or a ramp starts from, or a capacity search climbs to) - not the in-flight requests of a rate-paced run, which maxInFlight governs.

Architecture

Everything lives under app/electron/mcp/ and is managed by main.ts alongside EngineSidecar.

File Responsibility
config.ts McpSafetyConfig, safe defaults, input sanitizer, host normalizer.
safety.ts Pure guards: allowlist, load caps, duration parsing. Each takes the session's host so its refusal names that host's remedy.
remedy.ts What a refusal tells the user to do, per host (app or cli): settingRemedy(key, host) for every safety field, engineDownRemedy, engineRestartRemedy, and the tokens (GUARDED_WRITE_SENTENCE, REVEAL_SETTING_TOKEN, ...) plus resolveRemedyTokens that fill a description's tokens per host. The only place either wording lives; the CLI's is built from SAFETY_ENV_VARS.
engine-client.ts Thin fetch client to the engine REST API + SSE metrics snapshot.
compare.ts Pure two-report diff for compare_runs. Mirrored by the renderer's src/lib/run-compare.ts (neither process can import the other's source) and by the engine's run-report export (engine/src/core/run_compare.cpp); all three replay engine/tests/fixtures/run-compare-conformance.json, and compare.conformance.test.ts fails on any divergence, including the order and wording of the comparability list. Reads the status mix in both wire shapes: the renderer's transformed record and the engine's own array of [code, count] pairs (std::map<int, size_t> cannot serialize as a JSON object), which is what this path gets from a raw GET /runs/:id/report.
variable-origins.ts The resolution model the vayu://variables/resolution resource serves, and the winner-plus-shadowed computation behind resolve_variables. Mirrors the renderer's src/lib/variable-resolution.ts and useVariableResolver.ts for the same reason compare.ts does; variable-origins.conformance.test.ts replays the engine's fixture through both and fails on divergence. Resolves no {{tokens}} - see Variables.
http-versions.ts The httpVersion value list the Zod schemas enumerate.
tools.ts Tool registry: TOOLS, spread from the tools/*.tools.ts files in registry order, + dispatchTool, the one dispatch path server.ts and the tests share. Re-exports what callers import from tools/, so ./tools.js stays the registry's one public surface.
tools/<domain>.tools.ts The tool definitions (schemas, annotations, handlers), each file one contiguous run of the registry exported as an McpTool[]: reads, run-request, engine-config, collections, spec, requests, trash, examples, move, environments, variables, cookies, collection-runs, load, runs, connection, oauth2, mock-issuer, mock-server, webhook-inbox, in that order. The order is what tools/list and the Settings catalog show, so a new tool joins the file whose run it extends.
tools/contract.ts The registry's types (McpTool, ToolContext with its required host and the optional progress a call gets only when the client sent a progressToken, ToolResult, UserInput) and MCP_DATA_ENTITIES. A tool's description is a string or a function of the session's safety config, and resolveDescription is the one place it is read (registration, the Settings catalog under the defaults, and the list-changed check).
tools/kit.ts Helpers every tool shares: the strict arguments object (argumentsSchema), result builders, argument coercion (ToolArgError), the write and confirmation gates, and the NOTHING_CHANGED / STARTED_RUNS / INPUT_REQUIRED marks dispatch and server.ts read.
tools/<topic>.ts The helpers one family of tools draws on: compose.ts (request composition, the agent-script gate, load-run payloads), input-schemas.ts, output-schemas.ts, inline-body-bounds.ts, run-housekeeping.ts, request-body.ts, variable-blobs.ts, redacted-input.ts (the refusal of a credential slot written as <redacted>), scenario-runs.ts, cascade.ts, trash.ts, oauth2.ts, mock-issuer.ts, mock-server.ts, webhook-inbox.ts, examples.ts, move.ts, sibling-order.ts (a parent's sub-collections and requests as one list, the third copy of the sibling comparator; sibling-order.conformance.test.ts replays both order fixtures through it), spec-bindings.ts. Imports run contract.ts → kit.ts → topic files → *.tools.ts → tools.ts; nothing under tools/ imports tools.ts.
resources.ts Static + templated resource definitions.
prompts.ts Prompt definitions (build messages from engine data).
server.ts Builds the SDK McpServer; registers tools/resources/prompts; builds each call's context (callContext, including progress when the call carries a progressToken).
server-icon.ts The server's icon, shared/icon_png's 48px rendering inlined as a data URI.
http.ts Streamable HTTP host over createMcpHandler, both eras (Host/Origin checks in front).
client-sessions.ts The bounded Mcp-Session-Id → client-name record that carries the handshake's name across the HTTP host's requests.
in-flight-calls.ts The bounded (Mcp-Session-Id, request id) → AbortController record of the 2025-era requests the HTTP host is serving, so the client's notifications/cancelled reaches the call it names.
cli.ts Standalone stdio server over serveStdio (env-configured).
connect.ts One-click connect: resolves and runs the claude / code CLIs.
store.ts Persist safety config + enabled preference (../json-store.ts).
lifecycle.ts The server's one state (off, starting, listening, failed) and the generation every start and stop takes; main.ts reads the listener, service and start error from it.
index.ts VayuMcpService facade consumed by main.ts, loaded on demand.

Lifecycle & IPC

main.ts starts the server in app.whenReady() (skipped if disabled), stops it on quit, and exposes IPC the Settings panel uses. Every one of those goes through lifecycle.ts, which owns the listener, the service and the last start error as one state; a safety change applies to the service it reports, or is persisted for the service the next first request builds.

main.ts imports this directory by weight. config.ts, store.ts and connect.ts are self-contained (node:fs and node:child_process are their heaviest dependencies), so they are ordinary static imports. Everything reachable from index.ts - the SDK, zod, the registry and its 80 schemas built at module scope - is loaded by a cached dynamic import() instead, inside the lifecycle's service factory (reached only by a listener's first request, after the enabled check) and inside the two IPC handlers that need the tool catalog. The main process is unbundled, so a static import here is evaluated before app.whenReady and cost every launch ~250-300 ms ahead of the window, MCP switched off or not (#1145). A disabled launch now evaluates none of it; opening the Settings tool list is what pays for the registry. graphql is not part of that load: get_graphql_schema imports it on its first call.

The IPC surface:

IPC handler Purpose
mcp:status { running, url, enabled, error?, corruptCopy? }; error is { code, message } while enabled and the last start failed (EADDRINUSE, EACCES, other); corruptCopy is the path an unreadable mcp-config.json was kept at once a change has replaced it.
mcp:getSafety Live McpSafetyConfig, or the persisted one when off.
mcp:updateSafety Sanitize, apply live, persist; returns the resolved config.
mcp:setEnabled Start/stop the server, persist the preference; returns the status, and a retry (true) re-attempts a failed bind.
mcp:getTools IPC-safe tool catalog (name/description/category).
mcp:connectClient Run a client's add-CLI (claude / code); refuses with reason: "not-running" while no listener is up.

One channel runs the other way, main → renderer:

Channel Purpose
mcp:data-changed A successful call changed engine data; invalidate its queries.

And two run renderer → main for MCP's sake:

Channel Purpose
dataFile:locations The whole map of bound data-file paths, on launch and on every change (see below).
app:focus The open tab (type, entity id, label) and active environment (id, name), whole, on launch and on every change; get_app_focus reads the copy electron/app-focus.ts rebuilds field by field.

The UI reflects MCP writes live. An MCP call mutates the engine from the main process, which no renderer query can observe (refetchOnWindowFocus is off app-wide), so a request an agent created used to stay invisible in the collection tree until some unrelated mutation happened to refetch the lists. Each tool declares the data families it changes (invalidates in tools/*.tools.ts) and dispatchTool - the single dispatch path - sends one mcp:data-changed per family after a call that did not return an error. (The rows the engine's change feed covers reach the renderer that way too, from any writer: see the stdio CLI. This channel is what carries the rest, and a write it and the feed both report is invalidated twice, which costs a refetch and nothing else.) The event names a family (collection, collectionRow, request, environment, run, cookie, config, service, oauth, clientCertificate, variables) plus the collectionId / requestId / runId / inboxId / mockId the call itself named; it carries no engine data, so the renderer still reads every row through its query layer. The five hints are read off the call's own arguments at the dispatch chokepoint, which is what keeps a new write tool from having to remember an emit of its own - every tool in the registry spells them the same way. They are hints, not identity: requestId on a run event is the saved request a design run was linked to, while runId is the run itself, and only the tools that rewrite or remove an existing run (stop_run, set_run_baseline, delete_run) name one - a runner's new run has no per-run cache to drop yet. inboxId and mockId are the same shape for the service family: the tools that act on an existing listener name one, and start_webhook_inbox / start_mock_server cannot, since the engine assigns the id. Both exist because their per-id cache has to be dropped rather than refetched - a cleared capture list would union its destroyed rows straight back, and a stopped mock's route table has no live id left to refetch from. service is deliberately one family covering inboxes, mock servers and issuers, because the surfaces that read them - the Services drawer and the Dock's running-services count - ask "what is listening" rather than "which kind". oauth (issue #760) carries no hint of its own even though a cache key exists: an agent names the key it clears, but the key a fetch_oauth2_token writes under is derived engine-side and appears only in the answer, so a hint would be present for one tool and absent for the other - the shape that leaves a stale row exactly when it matters. The family is invalidated at its prefix instead. variables (issue #1916) is declared by the three design-mode runners - run_request, run_collection_smoke and run_collection - because a script or extractor that sets a variable has the engine write it back to the environment, globals or collection row once the send finishes. It carries no hint: the event cannot say which of the three scopes moved. start_load_run persists nothing and stays run alone. collectionRow (issue #2546) is declared by create_collection, update_collection and unbind_spec, the writes that touch one collection row and nothing beneath it; the renderer refetches the collections and their compositions and no request list. Every other collection write (delete_collection, move_item, import_document, bind_spec, sync_spec, the two trash tools) declares collection, which refetches every request list, because what it changes reaches past the collection it names. The two trash tools also declare environment (issue

2970): its renderer invalidator takes the trash list beside the environments,

the globals and every composition, so a delete_environment reaches an open Trash drawer and a restored environment reappears in the Variables view. A saved example needs no family of its own (#2971): delete_request_example declares request, whose invalidator takes the trash list and the named request's detail key, under which the Examples list sits, so the drawer and an open Examples panel both refetch. A restored example reaches the panel through the trash tools' collection family, whose invalidator takes requests.all (the Examples key sits under it); their request family names no row. A client certificate does need one (#2973): the Settings card lists live entries only and nothing else a trash tool declares reaches clientCertificates.all, so the two trash tools also declare clientCertificate, whose renderer invalidator refetches the registry. No tool writes that family on its own; it is not folded into config, whose invalidator would refetch every config and request-default read for it.

One field on the event is not a hint at all. startedRun rides the run event of the two tools that create a run - start_load_run and run_collection - and says that the run is live, naming it and which of the renderer's two run services owns its stream ({runId, kind: "load" | "collection"}, issue #1419). It is read from the engine's 202 answer rather than from the call's arguments, because a run has no id until the engine has given it one, and an answer carrying no runId announces no run. Everything a run does in the background - the taskbar/Dock progress bar, the keep-awake hold and the finished notification - lives in those services and begins when one is told to watch a run, and before this field existed only a renderer surface ever told them: a run an agent started painted nothing and said nothing until its dashboard tab was opened. useRunWatchers reads the field and enters the same startMonitoring path the dashboard does, so the main process still tracks no runs of its own. Both kinds are the exception while another run is live in the app (#3351, #3381): the engine runs the agent's run as asked, the user's run keeps the dashboard and the stream, the app attaches no live view for the agent's run, and says so in one info toast whose View run opens the run. Its History row updates as usual. The tool's answer is the same either way. run_collection_smoke sends its requests one at a time through POST /execute and has no run to watch, so its run event carries nothing extra.

The renderer side, including which query keys each family maps to, is in docs/app/state-management.md.

Declaring the families per tool rather than deriving them from category is deliberate: an execute tool writes a run row and refills the cookie jar without being a "write", and the field is required, so a new tool cannot ship silently invisible to the UI.

The panel (app/src/modules/settings/main/panels/McpSettingsPanel.tsx) is a registered app-settings panel; it talks to window.electronAPI directly since MCP config is app-level, not engine-level.

mcp:getSafety answers from the persisted config whenever the server is not running (switched off, or a failed port bind) rather than from the defaults, and the panel shows an error with a Retry instead of substituting defaults when a call fails. Both exist for the same reason: each control commits a whole field computed from what is displayed - adding a host persists the displayed allowlist plus the new entry - so a placeholder shown here would be written over the real config by the very next edit.

An unreadable mcp-config.json looks, on screen, like a config nobody ever set, so the panel says otherwise: once the first change has set the old file aside (corruptCopy in mcp:status, re-read by the panel after each change), a warning above the cards gives the copy's full path.

Configuration

The Electron-hosted server reads config from Settings. The stdio CLI reads it from environment variables:

Variable Default Meaning
VAYU_ENGINE_URL http://127.0.0.1:9876 Engine base URL. Set it to the address the Dock shows when the app fell back to another port (#2118); the Electron-hosted server follows the app's port by itself.
VAYU_VERSION 0.0.0 Version reported to clients.
VAYU_MCP_ALLOWLIST (empty) Comma-separated hostnames.
VAYU_MCP_ALLOW_ALL false true bypasses the allowlist.
VAYU_MCP_MAX_RPS 1000 RPS cap.
VAYU_MCP_MAX_CONCURRENCY 200 Virtual-user cap.
VAYU_MCP_MAX_DURATION_SECONDS 300 Duration cap.
VAYU_MCP_MAX_ITERATIONS 10000 Iterations cap (iterations mode).
VAYU_MCP_MAX_RESPONSE_SAMPLES 10000 Cap on maxResponseSamples, the responses kept for the sampled replay.
VAYU_MCP_ALLOW_WRITES false true enables the data-write tools.
VAYU_MCP_ALLOW_NETWORK_SETTINGS false true opens the proxy and CA config keys to writes.
VAYU_MCP_REVEAL_SECRETS false true lifts the secret withholding (reads, write answers, run output).
VAYU_MCP_DISABLED_TOOLS (empty) Comma-separated tool names to disable.
VAYU_LOG_DIR (unset) Also write mcp_<stamp>.log there (#1558).

What a refusal names in a CLI session (#2439). Each refusal tells the user how to lift it for the host serving the session (remedy.ts); the CLI's sentence is "set VAR=true in the environment of the MCP server and restart it", and the config is fixed for the process, so a restart is part of every one.

Refusal Names, in the CLI Names, in the app
Host not on the allowlist (or the list is empty) VAYU_MCP_ALLOWLIST Settings → MCP, Target allowlist
targetRps, virtual users, duration, iterations, response samples cap the matching VAYU_MCP_MAX_* Settings → MCP, the cap's field
Writes disabled (data writes and engine config) VAYU_MCP_ALLOW_WRITES Settings → MCP, Write access
Proxy or CA config key without the network gate VAYU_MCP_ALLOW_NETWORK_SETTINGS Settings → MCP, Network settings
Script, or secret: false, while reveal is off VAYU_MCP_REVEAL_SECRETS Settings → MCP, Reveal secrets
A tool switched off VAYU_MCP_DISABLED_TOOLS Settings → MCP, Tools
Engine unreachable start vayu-engine, or VAYU_ENGINE_URL make sure the Vayu app is running
verifySSL: false on a one-off send add the authority to the engine's customCaCertificates through update_engine_config, which needs VAYU_MCP_ALLOW_WRITES and VAYU_MCP_ALLOW_NETWORK_SETTINGS Settings > Network & connectivity
A binary body's file path no setting: the stdio server has no request editor to pick a file in and nothing that allows a folder, so only a folder the engine already allows works the request editor, or Settings > Files
A collection's remembered data file (dataFile) never present: dataFileLocation is absent on stdio, so no path is remembered; ask the user for it the app remembers the path
What sync_spec's safe policy declined no setting: a person ticks it under Collection -> Spec -> Sync in the desktop app Collection -> Spec -> Sync

The server instructions' write and reveal gate sentences read the host the same way, and so do the tool, resource and prompt descriptions. A description is built at module load or, for a tool whose wording depends on the session (the withholding pointer, #2441), from the config at registration; either way it does not know the host, so it names its remedy with a token from remedy.ts (GUARDED_WRITE_SENTENCE opens each of the write tools' gates, REVEAL_SETTING_TOKEN ends each withheld-output sentence in withhold.ts, and the Files, authority, data-file, proxy and Sync remedies above have one each). server.ts fills the tokens in per session: the whole tools/list answer (a tool's description, its parameters' descriptions and its output schema) and each resource's description. toolCatalog(), which feeds the app's Settings tool list, always resolves for app, and dispatchTool resolves a token in a refusal's text (INLINE_FILE_REFUSAL, INSECURE_TLS_REFUSAL). Only tokens remedy.ts defines are replaced, so braces in a user's own text pass through. remedy.test.ts iterates SAFETY_ENV_VARS, so a safety field added without a variable fails there, and server-host.test.ts drives each refusal through the real dispatch for both hosts and asserts a CLI message never says "Settings" or "Vayu app". It also lists every tool (parameter descriptions included), resource and prompt for a CLI session with writes on and off and fails on either phrase, or on a token left unresolved, naming the tool.

Both entry points sanitize their input through the same function (sanitizeSafetyInput in electron/mcp/config.ts), so the environment is held to exactly the rules Settings is held to:

  • A malformed cap falls back to its default, never to "no cap". VAYU_MCP_MAX_RPS="1,000" is not a number, so the 1000 default applies and still refuses an over-cap run. The CLI names what it dropped on stderr: [vayu-mcp] ignoring malformed VAYU_MCP_MAX_RPS="1,000" (using default 1000). Non-positive values (0, -5) are treated the same way; fractional values are floored.
  • A cap above its ceiling is named too, through its own channel. It did not fall back - it is in force, held at the ceiling - so the CLI says which value actually applies rather than which default did: [vayu-mcp] VAYU_MCP_MAX_CONCURRENCY="50000" is above the maximum of 10000; running with 10000. Without it the operator believes the policy is 50000 and learns otherwise from a refused run. Flooring alone is not reported: 999.7 becomes 999 and names no maximum, because it came near none.
  • Allowlist entries are reduced to a bare hostname, so https://api.example.com and api.example.com:8080 both match the api.example.com the guard compares against. Entries are de-duplicated.
  • The two opt-in booleans stay off for any value other than the exact string true.

Design notes

Rationale behind the load-bearing decisions.

TypeScript sidecar over in-engine C++

MCP could have been hosted inside the C++ engine (zero hop, single binary). The deciding factor: there is no official C++ SDK, so in-engine would mean owning the protocol in C++ or betting on a pre-1.0 community lib - right as the spec churns (the 2026-07-28 RC removed the GET stream endpoint and protocol-level sessions). The official TS SDK absorbs that churn, Node is already the Electron runtime, and the engine stays untouched (keeping it AGPL-clean). The accepted tradeoff: MCP is up when the app is open, not engine-only - covered later by the stdio CLI for headless use.

A fresh server per request, and how the push gap closed

The HTTP host builds a fresh server per request, which keeps Settings changes live for free. Under the 2025-era protocol that cost the host its server→client channel: no held-open stream, so a confirmation question and tools/list_changed could not reach an HTTP client. The 2026-07-28 revision is built for per-request serving and closes the gap without sessions: a question travels in-band as an input_required result that the client retries with the answer, and change notices travel on a subscriptions/listen stream the client opens. createMcpHandler serves both eras from one factory, so a 2025-era client keeps what it had and a 2026-07-28 client gets both (see What is live on each transport). A stateful 2025-era server - real sessions, a GET stream each, servers mutated on toggle - is not built: it would grow the mechanism the spec retired. What the host does keep for that leg is an abort handle per request in flight, so a cancel reaches a call whose server it cannot reach, and nothing else.

The size of tools/list is budgeted

Every session pays for the whole tools/list answer before it does anything, so its size is held by tool-list-budget.test.ts, which builds the real registry through the real server (app host) for each writes-off/on and reveal-off/on pair. Measured at #2441 (reveal off): 115,370 bytes with writes off, 181,447 with writes on, down from 136,705 and 211,549; the caps sit about 5% above the measured sizes. #2562's OAuth parameter lists grew the writes-off list to 121,210 (reveal off) and 118,484 (reveal on), and those two caps were re-set to that plus 5%. The envelope schema on the five paged reads (#2445) added about 2.9 KB to each pair: 127,059 / 124,333 bytes with writes off and 194,425 / 190,028 with writes on (reveal off / on). The loose schemas on the 23 other object-rooted reads added 7,866 bytes more to every row, about 340 bytes a tool: 134,925 / 132,199 with writes off and 202,291 / 197,894 with writes on, under caps of 136,300 / 133,600 and 204,400 / 199,900. get_safety_config (#2444) added about 370 bytes a row: 136,673 / 133,947 with writes off and 204,039 / 199,642 with writes on, and the writes-off caps went to 137,100 / 134,400. Master then drifted past every cap (137,599 / 134,873 and 204,965 / 200,568), and the paged whole-list reads (#2443) - the envelope schema on list_collections and list_requests, q / limit / offset and fields on the four lists, and their page and summary sentences - added about 4,590 bytes a row: 142,190 / 139,464 with writes off and 209,556 / 205,159 with writes on, under caps of 143,600 / 140,900 and 211,700 / 207,200. The same file fails on a sentence of 150 or more characters that more than three descriptions repeat (a rule that long belongs in the server instructions, with a one-line pointer in the tool: the withholding rules and the error definition moved that way, and VARIABLE_PRECEDENCE_SENTENCE stays under 150 so its deliberate repetition passes), and on any Withheld or <redacted> in a description of a session with reveal on. A tool that adds an output schema or a long description lands under the caps or raises them in its own diff.

Deferred

  • vayu mcp bin - package the stdio CLI as a first-class command (#693).
  • Hosted MCP for Vayu Cloud - OAuth-gated, remote.

References