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, andmcp:statusreports 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 firstPOST /mcpthat 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
fetchclient (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" } }
}
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
initializehandshake 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
initializehandshake) is served statelessly by the same factory, on an event stream that carries the one answer. There is no session:GETandDELETEare405.
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:
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 eachinitializewith anMcp-Session-Idheader 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_runrequires confirmation - a question to the person when the client can be asked, otherwise aconfirmed: trueflag (see What is live on each transport) - and enforces the RPS / virtual-user (concurrency) / duration caps. Incapacitymode 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;sloMsandstepDurationare that mode's own two fields, andget_run_reportreturns the search's findings undercapacity, including each level'serrorPctandsamples(the completions its p99 was read from; 0 means it measured nothing), thekneeErrorPctand themaxErrorPctlimit a level breaches above, beside the p99s. Aplateaustop also carriessaturationConcurrency,saturationRpsandsaturationP99Ms, 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'sshapeobject carries the same fields.get_live_metricsis a bounded snapshot (SSE read with a time budget), not a stream -tools/callstays 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 carriescompletedbeside 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'ssuccess_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,saveTimingBreakdownandcomment, 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) andmaxResponseSamples(max_response_samples, 0-1000000, engine default 1000; 0 keeps none) bound the responses kept forpostRequestScript, stored scripts and schema checks, whose outcome is the report'stestValidationandschemaValidation. They do not feedget_run_samples, which reads the errors, the completions at or aboveslowRequestThresholdMsand 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 oneRunContext, andcommentis lifted into the run summary and the report'smetadata.configurationwhichever produced the run. Bounds mirrorvalidate_run_config, so a value the schema accepts is onePOST /runsaccepts, 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 throughPOST /composebeside 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.maxRedirectsis bounded 0-100 here becausePOST /runshas no guard of its own and the value becomes the redirect limit, where a negative means unlimited. The tool exposes no per-runtimeout, and that is not an omission:POST /runsaccepts one, but a run started here takes the timeout of the request itself. A run started byrequestIdsends with the stored request's owntimeoutwhen it states one (issue #2937), becausePOST /composewrites it into the payload the run is started from; otherwise, and for an ad-hoc target, it takes thedefaultTimeoutsetting (resolve_request_timeout_ms), whichupdate_engine_configchanges - the run's OAuth 2.0 token fetches and everypm.sendRequestits 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_specsays what a collection is bound to,diff_specsays what a re-fetched document would change about it,sync_specapplies the part of that a caller with no opinion should apply,bind_specbinds one,export_specwrites it back out as a document, andunbind_specdetaches it.bind_spectakes 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.hpprulePOST /specs/matchpreviews with. So a document an agent sends as bytes reports coverage and validates responses, with no OpenAPI reader on the agent's side, andPOST /specs/exportowns 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 byoperationIdand a surviving one claims the wrong operation rather than none. The tool result reportsclearedbesidestampedfor that reason - it is the half a caller would otherwise discover from a later run.unbind_specstill leaves stamps alone, so unbind-then-rebind of the same document costs nothing. import_documentis 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/applytakes 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 samecore::read_documentthat answers what a stored document declares - so the tool sends bytes and options and nothing else, and detection is by content rather than by aformatargument a caller could get wrong.POST /importis the parse, the flattening andPOST /import/applyin one call: the tree lands atomically, and the globals a Postman globals export carries are merged afterwards rather than written over, becausePOST /globalsreplaces the whole set and must not run in front of a write that can still fail. The caveat sentence namesmeta.skippedfor the reasondiff_specnamesuserTouched: an import that dropped a WebSocket request, an unsupported body or an operation'sdefaultresponse looks exactly like one that had none. A Postman script that calls an API Vayu does not run (require()of anything butcrypto-js,uuid,lodash,moment,csv-parse/lib/sync,xml2js,chai,ajvandtv4, a bundled library such ascheerio) imports and throws at first run, someta.unsupportedScriptApis(issue #2576;[{request, names}], absent when empty) names those requests in both tools' result,metariding 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_specis 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-entrydraftis dropped - it is what an apply would write, andPOST /specs/syncre-reads it off the document it stores rather than being handed it, so nothing on either side of the tool consumes it; the renderedcurrent/nextpair, which is what says what moved, survives. Each bucket is capped at 50 entries whilesummarykeeps the engine's true totals, so a document that renamed every operation comes back described rather than whole. Thedeclinedbucket (issue #3031) is the operations whose request the user deleted: shaped likeadded, counted insummary.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_spectakes no rows, and the person brings one back in the app. And a field flaggeduserTouchedis 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_specapplies a drift, and does not let the agent choose which of it (issue #871). It sendspolicy: "safe"and nothing else: the engine works out the rows fromcore::safe_spec_apply, the same function whose answerdiff_specreports per entry assafe/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 importsrc/, 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, anddefaultSelectionnow 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'sskipped(requests untouched, fields not written, deletions not made, declined operations not re-created) is named in the caveat sentence fordiff_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_runis the status read (#2436). The engine answersGET /runs/:id/reportfor a run that has not finished with the numbers accumulated so far: a load run's live counts (nolatencyblock and noresults[]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_reporttherefore adds top-levelpartial: trueand anotewhenmetadata.statusispendingorrunning(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_runis the cheap read for "is it done":terminalcomes from the status, never fromendTime. Both reads classify the status through one function (classifyRunStatus, derived from the five statuseslist_runsfilters on), and a status outside them is treated as unfinished by both, never as finished (#3339):get_runanswersterminal: false,unknownStatus: trueand anextStepsaying the status is not one Vayu recognises (read again, orstop_run, which bounds the polling), andget_run_reportmarks the reportpartial: truewithunknownStatus: trueand anotenaming the status.unknownStatusis 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 nometadataobject is handed back as it came. The engine storesend_timeasstartTimeon a row that has not started (a seed kept for a run a crash kills) and as0on a running load or collection run (#3340), but emitsendTime: nullfor apendingorrunningrun (#2953), soget_run,list_runsand 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 insidesummaryand not to be read as the top-levelpartial(#2895):summary.partial: trueis 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) whilelatencyis absent, not zero (#2938), andpeakConcurrencyandavgQueueWaitMsare absent, not recorded (#2963);summary.summaryMissing: trueis 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 nolatencyblock,peakConcurrencyoravgQueueWaitMsis written. Both are absent otherwise, never false; the tool description andoutputSchemaname them, and a failed run'sget_runnextSteppoints at them. The app draws the same two reports as a notice and "not recorded".progressiselapsedMs / plannedDurationMsclamped to 0..1 for a run whose storeddurationparses and whose mode is notiterations, and null otherwise rather than a guess. The poll interval in itsnextStep, and in thenextStepthe three start results carry (start_load_runfor 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_reportcarries 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, undercoverage. 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_requestandget_run_reportwere raw passthroughs, and no engine cap covers this case:maxResponseBodyBytesbounds load runs only ("Design-mode sends are not affected"),maxTraceBodyBytesis 5 MB, sized for the database and a human reading one full trace, andmaxDesignResponseBodyBytes(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: truebeside the full size, inbodySizeon arun_requestresponse andbodyByteson a stored trace node, andrawRequestTruncated/rawRequestBytesfor a cut wire message - whose headers are always kept whole, since theCookieline libcurl attached appears nowhere else. A cutbodyRawcomes back with its parsedbodyasnull, because the two carry the same payload and an intactbodywould return in full exactly what was just dropped. QuotebodyRaw, notbody:bodyRawis the received text, whilebodyis 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'sbodyEncodingis always present,"utf8"or"base64", and a stored trace's response node carriesbodyEncoding: "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'scap_base64_node_bodyrule), so the prefix still decodes;bodySizeandbodyBytescount decoded bytes andbodyEncodingis kept. Both tool descriptions tell the agent to decode such a body rather than read it as text.bodyCappedon arun_requestresponse is not this (issue #1157): it is the engine's own flag, always present, saying it stopped reading the response atmaxDesignResponseBodyBytes, sobodySizeis the prefix it read and re-sending returns the same amount - only raising that config entry changes it, wherebodyTruncatedsays 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 throughbuild_result_trace, so they carry no trace node at all, and its captured bodies live behindGET /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/reportreturns up to 100 rows for a single-request run (every stored step for a scenario run, bounded bymaxScenarioStoredSteps) 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. Soget_run_reportalso 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 carrytraceOmitted: truein place of their trace, withtracesOmittedandtraceBudgetByteson the report. Non-passing steps spend the budget first, matchingScenarioStepStore::add's own rule forstepsStored, 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'sstreamflag consumes each response as atext/event-stream(issue #576), withmaxStreamDurationMsandmaxStreamEventsbounding one stream. Both caps are forwarded verbatim on thethresholdsprecedent - their ranges are the engine's, and re-deriving them here would be a second copy to keep in step (shared withrun_collection, where they need no flag, #3235) - and the tool states nostreamof its own when the agent named none: a run byrequestIdkeeps 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 nostreamkey, 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'sstream.cappedis what answers that. The report'sstreamsection also carries the per-completion event distribution, a derivedeventsPerSecondandtimeToFirstEvent(issue #3234), the wait from submit to each stream's first event, whichtimingBreakdown.phases.firstBytedoes not measure: it ends at the response headers.start_load_run'smonitorblock scrapes the target's own metrics endpoint for the life of the run (url, optionalintervalMsandformat, and theseriesnames 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 amonitorsection carrying per-series min/max/avg, the sample count, and the missed scrapes split by cause:failures(no 2xx answer, the latest cause inlastError) andnoMatchScrapes(answered, but none of the names matched; a Prometheus name is matched bare, so a{label="..."}filter is a400). The block is forwarded verbatim: its value ranges are the engine's (validate_run_config), andmonitor.series' ceiling is themonitorMaxSeriessetting, 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 holdsmonitor.urlto the run'stargetPolicytoo (#3121), so a loopback or private host that decision exempts travels in theallowedHoststhe 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_runstakesbaseRunIdoptionally. Omitted, it resolves the run pinned as the baseline for whatever saved request the target ran -GET /runs/:idfor therequestId, thenGET /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 norequestId, so it resolves through theconfigSnapshot.scenario.collectionIdthe sameGET /runs/:idcarries instead (collectionId=<id>in place ofrequestId=<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'sbaseline: trueresolves the same way. Two runs of different types are refused too (#2438): arun_typeentry incomparabilitymakes the tool an error naming both runs, their types andlist_runs'typefilter, with no deltas, because a load test's throughput against a collection run's is not a regression either way. Thecompare_runsprompt 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 adirection-lower-is-better,higher-is-betterorneutral(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 isnullon that side, withdeltaandpctChangenulltoo (#2904):summary.summaryMissing(a failed run with no summary) nulls that run'ssummary.*metrics and its latency,summary.partial(reconciled after a crash) its latency alone. A zero there would read as a measurement. The result also carriescomparability(#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.baseandtargetare the two values already formatted ("20 s"against"3 s, stopped"). The codes, always in this order:run_type(#2438;design,loadandscenarioshown as the app names them,Send,Load testandCollection run; a collection's load run isloadtoo, so it compares with a single request's load run without this entry),mode,concurrency(virtual users; for aramp_uprun its start level and ramp time too),target_rps,duration(the runs' measuredsummary.testDuration, in seconds, more than 2x apart),status(any two differing run statuses, such asStoppedagainstCompleted),http_version(autois 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 wayget_run_reportis),compression(the same fact ascompressionNegotiationDiffers, which stays) andexpect_continue(#2516;Expect: 100-continueallowedornot allowed, an absent key reading asnot allowed). When both reports carrymetadata.runType, amode,concurrencyortarget_rpsonly one of them recorded is a difference, its missing sidenot recorded; a report with norunTypeis 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_runstakes the engine's own filters (type,status,requestId,collectionId,qover the stored config,baseline) pluslimit/offset, so finding one run is a query rather than a scan of 100-row blobs. Order is fixed newest-first -GET /runstakes no sort parameter, and the app's oldest-first view sorts client-side.collectionIdmatches a collection run and a load run over a collection (both storescenario.collectionId), never a single-request design or load run. The filters are Zod enums rather than passthrough strings because the engine ignores atypeorstatusit cannot parse: forwarded raw, a typo would answer the unfiltered page and read as "nothing matched anywhere".set_run_baselinewrites the pincompare_runsalready resolved but nothing could set (the write half #472 never shipped), anddelete_rundeletes a run and everything recorded against it behind the same write toggle + confirmationdelete_requestuses. 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_timeseriesandget_run_monitordefault 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 withGET /runs) and 1000 for the two series, well under the engine's 50000. Alimitpast 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.nextOffsetis theoffsetto read next (null on the last page) andpagination.notesays the same in words, present only whilehasMoreis true. The same holds forlist_runsandget_inbox_captures, and all five declare the envelope as theiroutputSchema. - The whole-list reads page in the engine and summarise here (#2443).
list_collections,list_requests,get_cookiesandlist_trashforwardq/limit/offsetto the engine's paged list routes (50 rows by default, 500 max, refused above) and answer the same envelope, with the samenextOffset/note. The first three answer a summary row by default and the whole row withfields: "full". The summary is cut on this side rather than by the engine'sGET /requests?fields=summary, because withholding must see the whole row first: a request'surlis masked by reading itsauth(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 bylimit. 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 andvayu://collections- keep calling them. update_engine_configreads the config back after applying and flags any changed key that needs an engine restart to take effect underrestartRequiredin its structured result (read from each entry's typedrequiresRestartfield, 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_collectiongives it acollectionIdto file new requests under, andupdate_request/delete_requestlet 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, andPUT /collections/:id/PUT /requests/:idkeep everything else stored, so a patch naming justnamecannot blank a url, an auth block or a script. A patch naming nothing is refused rather than sent as a write that changes nothing, andbodyTypewithoutbodyis refused too (the blob and its denormalized column move together or the two disagree about what the request sends).update_collectioncarries a collection's own state - name, description, variables, auth, both scripts - and never its position: re-parenting ismove_item's job (below), because a move is a batch. The destination's siblings renumber with it, andPOST /reorderis the write path that commits the whole batch or none of it; aPUTwrites one row. delete_collectioncascades, so it reads the subtree first:GET /collectionsgives it every descendant throughparentId, oneGET /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_requestreads 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_environmentopens since #2970 and the onedelete_request_exampleopens 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 iskind: "clientCertificate", named by its target, a root withparentIdnull and both counts 0.list_trashanswers a page ofGET /trash(#2443), each entry unchanged - roots only, withcollections/requestscounting what each entry's delete took (what a restore puts back) andpurgeCollections/purgeRequestscounting what a purge would destroy under it (#3449), an environment entry carryingvariables, an example entry carrying its request asparentId, and a request or example entry carrying its owner's name asparentName, exactly as the route documents.restore_trash_entryis 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 reportsreparentedToRootin 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, andactivate_environmentis 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_entryis the Trash's own hard delete and is gated exactly likedelete_collection: it reads the entry offGET /trashfirst, 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 withentryId, not a bareid(#2446: anidbesiderequestId/runId/environmentIdreads as "the id of something else"). A call that sends onlyidis 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_requestcarry the request'sauthblock 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. Theauthinput is the same schemarun_requesttakes rather than a copy of it - one definition, four descriptions - which is what lets an agent read a request'sauthoverget_request(orlist_requestswithfields: "full") and write it back verbatim. Itsmodeis 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 omittingauthkeeps what is stored. Anapikeyblock places the key within(header, the default, orquery); a Postman-styleaddTois 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 onlymaxRedirectscannot hand a storedfollowRedirects: falseback 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:nullonupdate_requestresets it to "no timeout of its own", so the request sends with thedefaultTimeoutsetting again, where an absent key keeps the stored value;create_requesttakes it absent ornullfor none. ForverifySSLthat rule is a security rule rather than a convenience: a defaultedtrueon 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_requestalso carriesmockResponseMode/mockExampleId(issue #481 phase 3), the same setting the Examples tab's mode picker writes:fixedis refused before the engine is called when it names nomockExampleId, exactly like the bodyType-without-body refusal above, and the change only takes effect the next timestart_mock_serverruns - 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) clearsmockExampleIdengine-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 afixedmode pointed at an example that never existed. - A skipped certificate check has to leave a record (issue #795). The
stored
verifySSL: falseis writable over MCP; a per-call one is not.run_requestdeclaresverifySSLonly so thatfalseis 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 withverifySSL: falseand running that.start_load_run,run_collectionandrun_collection_smoketake 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_requestreads back and the user can undo, while an argument on one send is visible only inside the agent's own transcript. TheallowInsecureTlssafety 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_examplesreads 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. Theorigincolumn 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 claimimportwould hand its own example to the next sync to overwrite, and one that could claimusercould pin a stale imported row against the document it came from - neither is the agent's call, socreate_request_examplealways storesuserand the update tool cannot restate it.headerson 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 - severalSet-Cookielines are several rows - which a map cannot hold, so the rows are forwarded in order, a repeated key kept andenableddefaulting to true; the map is the short spelling, one value per name. A row that is not an object with a stringkeyand a stringvalueis refused by its position, unless it is a row as read withvalueWithheld: trueand novalue, 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) andsource(body-modeon the Content-Type row the app's Body panel or an importer wrote,legacy-defaulton a row the engine's repair pass disabled), forwarded as given, a kept row's included - a row written back without itssourceis 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}, unlikerun_request's{name, value}lines, because they are the rows the engine stores andlist_request_examplesreturns, not a request in flight. Bodies are bounded on the way out for the reasonget_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, flaggedbodyClippedwith its stored size inbodyBytes; once the list has spent 96 KB the remaining bodies are dropped withbodyOmittedand counted inbodiesOmitted, every row's scalars kept.bodyClippedis not the engine'sbodyTruncated, which says the response was already cut when it was captured - two different facts, so two different names.delete_request_examplesays what the delete leads to byorigin(#2971): auserexample goes to the Trash, so its description, preview and prompt namelist_trashandrestore_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_collectiontake thevariables,authandelementsthat shape every request below them - the same list the composer walks (compose_elementsruns the chain's elements before the request's own, issue #1514).preRequestScript/postRequestScriptstay as sugar on these two tools (issue #1517): a non-empty string folds into ascript.pre/script.postentry and an empty one removes it - never sent to the engine under those two names, whichPOST /collections/PUT /collections/:idrefuse outright now thatelementsis the only script source.variablesusesupdate_environment's input and its rules unchanged, includingremoveVariablesand 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 explicitelements(which needs the stored list to fold the sugar into without dropping the collection's other elements) - passingelementsdirectly, like a plain rename, sends onePUTand nothing else. A collection never inherits auth (#3445): both tools'authschema omitsinheritand 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_runand the request tools keepinherit. move_itemis a bounded move, not a reorder (issue #759). It maps toPOST /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 throughPUT /collections/:id's ownparentId. ThatPUTholds 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 isitemId): a destination, andfirstorlastamong 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, oneorderspace (#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 bytree-order-conformance.json), solastlands past every child of either kind andfirstahead of them all. The batch states that list's whole arrangement, each row under its owntype, rather than leaning on the engine'snormalizepass, 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 storedorderactually 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 withspecOperation: null, and the operation is declined at the binding it left (#3446, asdelete_requestdeclines it), so that collection's nextsync_specdoes not create it again.update_environmentfetches the environment and merges the supplied variables (PUT /environments/:idreplaces the whole variables blob), so partial updates preserve untouched variables and the name. The write is conditioned on the version it read (#2433): thePUTcarriesIf-Match: W/"<updatedAt>"from the row the list answered, so a change the app or another client made in between is a412rather than a silent loss. On a412the tool reads the row again, merges the same arguments onto it and writes once more; a second412is answered as atransienterror saying nothing was written, and repeating the call merges into the latest version.update_collectiondoes the same whenever it reads (a variables or script edit); a call naming only stated fields reads nothing and sends noIf-Match.update_requestdoes the same whenever it reads (a script edit, a header row written back withheld, or aurlorheaderswhile secrets are withheld, #3549, #3550), and so doesupdate_request_example(a header row written back withheld, orheaderswhile secrets are withheld, #3550). Overwriting an existing variable changes its value only - itssecret,type,createdAtand enabled/disabled state are preserved, so a rotated secret stays masked and a disabled variable stays disabled. The answer is the stored row, withheld aslist_environmentswithholds it. It is aPUT, not aPOST: since #95 the engine'sPOST /environmentsis create-only, and since #97 it rejects a body carrying anidoutright.create_requestandcreate_environmentstayPOSTs for the same reason - they create, and let the engine assign the id. No tool here sends anidin a body: on thePUTthe path is the identity, a bodyiddisagreeing with it is a400, and on thePOSTanyidat all is one.- The variables an agent writes are the flags it did not state (issue #758).
update_environmentandupdate_globalstake 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 carriesvalueWithheldandcreatedAt, accepted and kept as stored, #3556), which is what makessecretandenabledreachable 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 avalue, so{secret: true}against a mistyped name is an error instead of a new empty secret variable; and a name in bothvariablesandremoveVariablesis refused, because "set it and delete it" has no correct order and guessing one would apply half the call and report success.removeVariablesis 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 invariablesis refused by the engine with a400naming the key (#3251); a legacy such key already stored is removed withremoveVariables, spelled exactly as stored, and until it is every write that merges the blob fails on it.secretmasks 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 withsecret: falseis refused while reveal is off, since the next read would return the value;secret: trueis always accepted. - Activation is one write, and
"none"is the other direction.activate_environmentsendsisActive: trueand 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 writetrueto, so"none"reads the list to find the row holding the flag and writesisActive: falseto it - and when nothing is active it writes nothing, says so, and emits no data-changed event. The app follows either direction:useActiveEnvironmentRestoreadopts whatever the engine reports, including a clear it has seen the engine hold a selection before. update_globalshas to read first. Globals is the one resource with no create/update split - one row, one id - soPOST /globalssaves the blob whole and an absentvariablesmeans{}, not "keep". The tool readsGET /globalsand posts the merged result under the version it read (If-Match: W/"<updatedAt>", #2988), the conditioned read-merge-writeupdate_environmentdoes for the same blob-replacement reason, with the same one re-read on a412and the sametransientanswer on a second. An engine that never saved any globals answersupdatedAt: 0, andW/"0"is a version like any other, so a first save is conditioned too.clear_cookieshas three scopes, not two. OmittingenvironmentIdclears every jar, passing an id clears that environment's, and passingnullclears 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'sapiService.clearCookiessends the same three). No confirmation gate: nothing saved is lost, only session state a re-login restores - which is why it is awritetool for the toggle and not one of the confirm-gated deletes.run_collection_smokeruns 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 atestsnode -total,failed, and the failingname: messagelines (issue #733) - so a row that fails on its tests says which, rather than leaving an agent withok: falsebeside a200. 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, whilefailedstays the true count. A response that ran no assertions carries notestsnode: 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 aserror,"<errorCode>: <errorMessage>"(issue #3552), the field a thrown send already uses, masked with the rest of the row; an answer with noerrorCodeleaves it unset. For a collection bound to an OpenAPI document each row also carries aschemaverdict (issue #681) and folds it intookthe waytestResultsfolds: 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: falseunfolds it (issue #720): the verdict still rides every row, it just stops decidingok- useful against a document known to lag its API. It defaults to true here, where the same-named flag onPOST /runsdefaults to false, because this tool has folded since #681 and an agent reading its matrix would otherwise start seeing contract failures pass.run_collectionoffers 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 noschemafield 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 unlessrecursive: true:GET /requests?collectionId=serves direct requests only, while collections nest viaparentId, 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 whosetotalsilently excludes nested folders reads as a whole-collection pass. The note names both ways out:recursive: truehere, andrun_collectionwithrecursive: true(preferred for a large tree: one stored run with a run id).recursive: truewalks the tree through the same functionrun_collection's pre-flight does (walkCollectionRequests,scenario-runs.ts), so the rows come in the sidebar's order (#2535) and each names itsfolder, the collection names from the root down joined by/; a recursive run has nothing left out, so it carries no note, and a failedGET /collectionsis the engine error, with nothing sent. An OpenAPI import files its operations under sub-collections (grouped by tag or by path, permeta.folderStrategy), so a direct-only smoke of its root answerstotal: 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 torun_collection(one stored run with a run id, read withget_run_report), leaving the smoke for a bounded pass/fail matrix. A call runs one page (#2451):limitrequests (default 25, max 100; a larger value is refused, not clamped, like every bound in this registry) starting atoffset. The list - the direct requests, or the whole expansion of arecursiverun - 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,failedandskippedkeep their meaning as the counts of the rows run in this call; the result addsrequestTotal(the list's size, before the cut),hasMore, and - only whilehasMoreis true -next: {offset}, theoffsetthat resumes. Whenever the call did not run everything in scope the result's ownnotefield 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. Anoffsetat or pastrequestTotalruns nothing and the note says so (hasMorefalse). A call that ran everything carriesrequestTotalandhasMore: falseand 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 withcancelled: true,hasMore: trueandnext.offsetset tooffsetplus 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, andnext.offsetpoints 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 (anotifications/cancelledfor 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 aprogressToken(#2451) the call reportsnotifications/progress-0/totalbefore the first request, then one per row on every path (sent, skipped off the allowlist or failed to compose), with a message of the form3/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'surl,errorand 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'sresetTimeoutOnProgress): a singlePOST /executemay 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_tokenacquires (or force-refreshes) a token for a config and caches it engine-side,get_oauth2_token_statussays whether an entry exists and whether it has expired, andclear_oauth2_tokendrops one. The config is the same block a saved request'sauthcarries, so it can be copied out ofget_requestverbatim; the cache key is the engine's (accessTokenUrl+clientId+credentialsId+ username + the extra parameter rows the engine would send, a credential-named row such asclient_assertionby its name alone, so the key never carries a secret), so configs differing only in scope share an entry and a distinctcredentialsIdis 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 explicitaccessTokenWithheld, because an agent that finds no token and is not told why concludes the acquisition half-failed. And theauthorization_codegrant is refused before the engine is called, not merely because the browser exchange is one MCP cannot drive:acquire_tokenanswers 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 coversrefreshTokenUrlas well asaccessTokenUrl- 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_issuerstands up a local OAuth 2.0 issuer and returns itsissuerId,tokenUrl,authorizeUrlandsigningKey, so the agent can point a request'soauth2auth at the token URL,run_requestit, and assert on what the target received - offline, with no real provider's 2FA prompts or rate limits in the loop.expiresInSecondsplusissueRefreshTokensis how the 401-then-refresh path is exercised, andfailureModeis how retry handling is. No allowlist entry is needed and none is checked: the engine binds every issuer to127.0.0.1and 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, 60sslowMs, 32 clients, 8 concurrent issuers) stay engine-side rather than being restated in the tool schema, for the same reasonmonitor'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, afailureModefrom 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_issuermerge-patchesfailureModeandslowMslive (issue #757), so an agent can mint a token against a healthy issuer, flip it toserver_errorto 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 refusesport,clients,claimsandissueRefreshTokenswith "stop it and start a new one", so the tool does not offer them at all rather than offering a call that always fails.expiresInSecondsis 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 answers200- which would report a change that did not happen (theupdate_inbox_responseprecedent). - 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_serverbinds a listener that answers each request's example - status, headers, body - and returns itsmockIdand base URL,get_mock_routeslists what it will serve, andstop_mock_serverfrees the port.latencyMsanderrorRatePctare how a client's timeout and retry handling get exercised;0and100percent 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 answers501, a path matching nothing answers404, and a collection with no mappable requests serves nothing at all. Loopback-only for the same engine-side reason as an issuer -mock_server.cppstarts every listener on127.0.0.1with 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 leaveslist_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 atstaleTime: Infinityand astop_mock_serverevent carries themockIdso that cache entry is dropped rather than refetched into a404. Each row'smode,exampleNameandhitsare 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_activityis 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 withoffsetin the{data, pagination}envelope the other paged reads answer (the engine route takeslimitalone and keeps 200 entries, so the tool reads that whole ring and slices it) and, like the route table, is discarded outright onstop_mock_serverrather 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 a400naming it (allowedOrigins[1]) - and the start result andlist_mock_serversecho the canonical list. Fixed for the mock's life, likelatencyMs. - The webhook-inbox tools are the assertion half an agent testing a webhook
needs (issue #756):
start_webhook_inboxstands up a local inbox and returns its URL,get_inbox_capturesreads back what arrived - method, path, query, headers, body, caller address - andupdate_inbox_responsechanges what the sender sees, live, so one inbox can answer200for the first trigger and503for the next. Loopback-only, and not by policy alone: the engine'sbind/confirmNonLoopbackpair is never emitted byinboxStartPayload, 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 intools.test.ts. A stop is not a delete:stop_webhook_inboxfrees the port and leaves every capture readable, whiledelete_webhook_inboxdestroys them and therefore takes the write toggle and a confirmation whose prompt names how many captures go with it (read fromGET /inboxfirst, the waydelete_runreads the run).clear_inbox_capturesis the middle case - recorded data destroyed, listener kept - so it takes the toggle without the confirmation. No live stream:GET /inbox/:id/liveis single-watcher (a second is a409) and the app's own inbox tab may hold it, so MCP pollsget_inbox_capturesinstead - the same bounded-snapshot postureget_live_metricstakes. Capture bodies are cut to 32 KB for the result with the engine's ownbodyTruncated/bodyBytesdisclosure kept intact (a body that is not valid UTF-8 carriesbodyEncoding: "base64", is cut in decoded bytes so it stays whole base64, and is masked in its bytes like any other base64 body, #3109), sinceinboxMaxBodyBytesreaches 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 andlist_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
AbortSignalthe SDK hands each call fires when the client cancels it, and it is threaded into the enginefetchfor 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 thenotifications/cancelleditself, 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 byMcp-Session-Idand 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 /executewaits on a third-party server, so its budget is derived from the engine's owndefaultTimeoutsetting (read per call fromGET /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 whenauth.modeisoauth2(the token fetch has the same bound), plus thescriptTimeoutsetting (60s when unreadable) for every enabledscript.pre/script.postelement, because one call runs them in sequence. A request with neither keeps exactly the setting plus 10s. That way the engine's ownTIMEOUTerror, 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_smokebounds the other side of this: a call runs at mostlimitrequests (25 by default), so one call stays inside a typical client budget and a longer collection is resumed byoffsetrather 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:
<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_variablesandupdate_environment,update_collectionorupdate_globalsfor 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_specandsync_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'srequestIdand the envelope'soperationNameinrun_requestandupdate_request. - run sample: the copy button in a sample card's header on a load test's Samples tab. Feeds
get_run_samplesandget_run_report, which join on itsresultId. - element: the copy item in an element's row menu, in a request's or a collection's Elements
list. Feeds the
elementsargument ofupdate_requestandupdate_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'sthresholdsandget_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) andactiveEnvironment(id,name) - and nothing else: no variable value, header or credential. Read the entity itself with its own tool (get_requestfor a request). - A run the agent started: read it by the
runIdits start call returned, not by its position inlist_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:
targetPolicyon every send.asMcpSendstamps the session'sallowAlland allowlist, as{allowAll, allowedHosts}, besideoriginon everyPOST /executeandPOST /runsthis server makes (run_request, streaming or not, eachrun_collection_smokerow,run_collection,start_load_runin both shapes andget_graphql_schema). The engine judges the URL it is about to send, after the pre-request scripts and the residual pass, by the same rulesafety.tsapplies (exact host, case-insensitive; an empty or still-templated host is refused even under allow-all), and the host of every OAuth 2.0accessTokenUrl/refreshTokenUrlthe request's auth would post to, before any token is fetched. SeetargetPolicy. A test drives every sending tool by name, and a scan fails on anexecuteRequestorstartRuncall 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.urlagainst the sametargetPolicy(#3121) and exempts nothing, so whenstart_load_runcarries amonitorblock whose host the monitor gate passes without an entry (loopback or private, link-local and metadata addresses aside; see Safety),asMcpSendadds that host toallowedHosts(exemptMonitorHostinsafety.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.
checkComposedTargetrefuses 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'sdeferredVariableshas 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_collectionvariables or an environment,resolve_variablesto 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's400body, or the smoke row's skip reason) oftarget_not_allowedbecomes the allowlist remedysettingRemedygives the early refusal;target_host_unknownasks for a resolved URL. The text says the allowlist is applied after the pre-request script and to an OAuth 2.0 token endpoint. deferredVariablesdescribes 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_runcomposes 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_smokeandrun_requestwith arequestIdand nourlcompose each saved request by id, so its stored auth applies (inheritresolved against the collection chain);run_request/start_load_runaccept an explicitauthblock and forward it raw inside the inline request - the engine resolves variables in it (andinherit, when acollectionIdscopes 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.postelements engine-side (issue #1514), so a saved request's assertions execute in the design send, the sequential collection run, and nowstart_load_run's single-target path too (issue #1594 - the composedelementsbecome the run's ownrequestElements, a step-level pipelinePOST /runsnow runs per submission), and so doesrun_requestwith arequestIdand nourl.start_load_rundoes not forward a collection's or folder'sscript.setup/script.teardownthat/composeemits:requestElementsis validated as a request's own and refuses them, and they belong to the collection's own run (#3070). An ad-hocrun_request(aurl) takes apreRequestScript/postRequestScriptinstead (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_runtakes the samepostRequestScriptfor a URL-only run, folded intorequestElementsthe same way, as described above. Those two are supplied per call, are refused while reveal is off (above), and are not stored -create_requestandupdate_requesttake the same two names as sugar for ascript.pre/script.postelement 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 -
bodyis a string andbodyTypenames the mode (json|text|graphql|jsonrpc|xml|form-data|x-www-form-urlencoded|binary, defaulttext). The two form modes carry their content as fields, not as a string, sobodyis written askey=value&key=valueand split into thefieldsrows the engine reads - see thebodyunion. Agraphqlbodymay be the bare query document: the engine envelopes it as{"query": ...}and sendsapplication/json, and an envelope written out in full is sent unchanged - onPOST. WithmethodGETthe same fields travel asquery/operationName/variables/extensionsquery parameters instead, with no body and no Content-Type, so a mutation needsPOSTrather than theGETa new request defaults to - see thegraphqlenvelope. Ajsonrpcbodymay be the bare call object: the engine adds"jsonrpc":"2.0", plus"id":1when 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 thejsonrpcenvelope. Anxmlbodyhas no envelope at all: it is stored and sent byte for byte and carriesapplication/xmlunless the agent set a Content-Type of its own, which is how a SOAP 1.2 endpoint getsapplication/soap+xml.create_requeststores the same shape. Every form field an agent writes is a text part: aform-datafile part has no spelling in akey=valuestring, and a stored one is left alone unlessbodyreplaces 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 itsdynamic-variables.tstwin) 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 callPOST /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:
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 apm.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.sendRequestunless the execute/run payload carriesallowScriptRequests: true. The app's own Send and load runs ask for it, each in the one service method that owns that call (apiService.executeRequestandexecuteStreamRequest- Send's two halves - plusstartLoadTest/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/v1andapi.example.comare the same entry), and the request URL is matched by its host whether or not it carries a scheme (localhost:3000/apimatches the entrylocalhost). An IPv6 target is stored and shown in its canonical bracketed form - typing::1stores[::1], which is what a URL parses to. A run'smonitor.urlis 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 holds169.254.169.254, the metadata service on AWS, GCP and Azure),fe80::/10and AWS's IPv6fd00:ec2::254need an allowlist entry like a public host, because a scrape of one reads credentials rather than the user's exporter. The rest offc00::/7stays 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 ownlocalhost: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 holdsmonitor.urlto the run'stargetPolicywith no exemption of its own (#3121), so the exempt host is added to the run'sallowedHosts(see Request composition). The renderer's load-test dialog uses the same classification to tell a local target from a remote one (isLocalHostinsrc/lib/host-locality.ts, a mirror ofisPrivateHostthat the main process cannot share);host-locality.conformance.test.tsfails 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, sopm.sendRequestis refused outright for runs this server starts. See The script sandbox surface. - Hard caps - max RPS / virtual users (
concurrency) / duration / iterations / response samples (maxResponseSamples) onstart_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:concurrencyandstartConcurrencyare both held to the virtual-user cap (Max virtual users in Settings). A ramp is seeded withstartConcurrencybefore 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 omittediterationsis sent and compared as the engine's own default of 1000. The schema refuses an unrecognisedmode, and the guard still reads one carrying aniterationsfield as an iterations run, because the engine runs it as one. maxResponseSamplesis 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
concurrencyon 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 omittedconcurrencyon acapacityrun, whose search climbs to 100 (#2493). An omitteddurationis the mode's default (60s, or 300s forcapacity) unlessmaxDurationSecondsis shorter, in which case the cap is sent in its place and the run is bounded by it.concurrency,startConcurrency,iterationsandmaxInFlightare additionally constrained to positive integers by the tool's own schema, because "unlimited" is an obvious guess to spell-1or0and 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).maxInFlightis 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 of1000000, so a value this tool accepts is onePOST /runsaccepts.duration/rampUpDurationare 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 a400rather than quietly substituting 60s; a zerodurationis rejected here for the same reason the engine400s it, while a zerorampUpDurationstays 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_requiredresult: 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_inboxandpurge_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 nomcp:data-changedevent either.restore_trash_entrydeliberately 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 fromtools/list, not merely refused bytools/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, soserver.tscaptures thetools/callhandler 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, andprotocol.integration.test.tsclassifies 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 thetools/listan 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 underrun_collection_smoke,run_collectionandstart_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 inrun_request'selementsdoes (its default scope is the collection), and so does an agent's own script once reveal is on. With the toggle off,run_requestsendspersistVariables: falseon 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_smokeandrun_collectionare 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_runnever 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 nexttools/list- the same timing the per-tool switch below already has. The category is every tool declaredcategory: "write"intools/*.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 gaterun_request/run_collection_smoke/ load runs (allowlist + caps). Seven of those need the toggle and confirmation - the six deletes pluspurge_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_cookiesandrestore_trash_entrytake 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 keyupdate_engine_configneeds for the entries that decide where every request goes and whom it trusts: everyproxy*key (proxyMode,proxyUrl,proxySystemUrl,proxyBypass, matched by prefix and case-insensitively, so a proxy key added later is gated the day it ships) andcustomCaCertificates(#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 whetherupdate_engine_configis 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_inboxandupdate_inbox_responseareexecutetools that neither the allowlist nor the write toggle governs. (The two that destroy recorded data,delete_webhook_inboxandclear_inbox_captures, arewritetools 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 to127.0.0.1by the engine with no host to configure - as is a mock server, and as is an inbox, whosebindthese 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 withlocalhostallowlisted can already reachPOST /mock-issuer/startthroughrun_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 indispatchToolis 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 whileallowWritesis off, and turningallowWriteson re-enables no tool that is indisabledTools. 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 the1000default 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.7becomes999and names no maximum, because it came near none. - Allowlist entries are reduced to a bare hostname, so
https://api.example.comandapi.example.com:8080both match theapi.example.comthe 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 mcpbin - package the stdio CLI as a first-class command (#693).- Hosted MCP for Vayu Cloud - OAuth-gated, remote.
References¶
- MCP TypeScript SDK · Streamable HTTP transport
- Client docs: Claude Code · Codex · Cursor
- Engine API surface:
api-reference.md· Threat model:SECURITY.md