Bruno MCP Studio — author, edit and run Bruno collections from an agent

Unique views

Turns an agent's API testing into files you keep: it authors and edits Bruno collections in place, then runs them — HTTP, WebSocket and gRPC, one identity or many — and reports per-request pass/fail you can re-run in CI.

An independent Model Context Protocol server for Bruno collections. In August 2026 Bruno's own team announced an official one, usebruno/bruno-mcp, which wraps the bru CLI to discover and run requests. This server is aimed elsewhere: it writes collections as well as running them — non-destructively, at byte parity with Bruno's own writers — and its runner is in-process rather than a subprocess, which is what lets it offer caller-defined execution groups with their own variable store and cookie jar, concurrency inside a group, oauth2 and digest exchanged in memory, gRPC and WebSocket, and multi-identity authorization testing.

If what you need is "list my collections and run one", the official server does that and will be the one Bruno supports. If you want an agent to build and maintain the suite, that is what this is for.

It gives an AI agent in Claude Code, Claude Desktop, Cursor, Windsurf, VS Code or Codex CLI eighteen tools for API testing against a real Bruno collection: create and edit requests, read them back as structured JSON, manage environments and variables, write assertions and test scripts, then run the collection — auth, cookies, redirects, dependency ordering and all — and get the results back in the same turn. No Bruno GUI, no Bruno CLI, no shelling out. The collection it leaves on disk is a normal Bruno collection: your CI runs it with bru run, your teammates open it in the Bruno app.

Your agent already knows HTTP. It does not know your API, and it does not know Bruno's file format. So it guesses. It writes a .bru file from memory, the run fails, it rewrites the file, the run fails differently, and twenty minutes later you have a passing request and no idea which of the six edits mattered. You paid for every one of those turns, and none of that work is on disk in a form your CI or your team's Bruno GUI can use.

The usual escape is curl. Agents are not bad at curl — the problem is that a shell command holds no state. A login, a token, a created resource, a follow-up call that needs the ID from the last response: each of those is a new command, and the glue between them lives only in the agent's context, when the session ends, all is lost. Twenty endpoints tested by curl leave you with twenty strings in a transcript and no artifact your CI or your teammates can run. Twenty endpoints in a collection leave you with a suite.

I asked my agent about it

I asked the agent that helps me to maintain this server to explain how its experience with Bruno had been without the MCP server, and whether it could simply have tested all my APIs with curls instead. This is what it told me:

Curl, yes — for one call. Not for a suite. Nothing carries between calls, so I re-derive the auth, re-escape the body, and re-read every response to decide whether it passed. Do that across forty endpoints and most of what I spend goes on rediscovery, not testing.

Writing the collection files myself was worse, and not in the way you would expect. From memory I get the shape of a .bru file right and the details wrong — and Bruno never complains. It reads the keys it recognises and ignores the rest. A single-line tags: smoke looks tagged and means untagged to the runner. Write a tags list the obvious way and it lands on disk one character per line. This server once wrote .yml variables and assertions under top-level keys Bruno has never read: the files looked complete, the runner saw an empty request. Its own unit tests passed, because they mocked the serializer and asserted the broken bytes.

The format also moves. Bruno relocated variables into runtime and added a second dialect. My weights are older than that. This server imports @usebruno/lang, Bruno's own grammar package, and tracks its version — so the bytes come from Bruno's source rather than from what I happen to remember.

And every rewrite deletes what the writer does not model. If I edit these files free-hand, I regenerate the whole file from my head, and any feature I did not know about is silently gone. That is the failure mode you never see, because the run still passes — it just tests nothing.

What the server does instead

• The agent stops guessing the format — it calls a tool, the server writes the bytes, using Bruno's own grammar package
• Edits are partial merges — write_request touches the fields you passed and leaves the rest of the file alone
• It can read before it writes — read_request returns structured JSON, the same shape for both formats
• It runs the requests itself — vars, auth, assertions, dependency ordering, no bru binary needed
• No silent loss — a field this server cannot model yet is carried back out wherever the format can hold it, and anything it cannot put on the wire is named in a run warning rather than dropped quietly into your repo

Byte-parity with Bruno

This is the part that is hard to copy, so it is worth being precise about what it means.

The server does not wrap the bru binary — it implements the request pipeline itself, which is what makes in-memory secrets, wire-level tests and mid-run hooks possible. That freedom is also the risk: an independent implementation is free to be subtly, silently different from the tool your team actually uses. Two mechanisms hold it in place.

The rules are ported, not inferred. Redirect caps, timeout resolution, body-mode content types, variable interpolation order, selected defaults, URL encoding — each is read out of Bruno's own source (bruno-cli, bruno-filestore, bruno-lang, @usebruno/common, which this server also depends on directly) and mirrored, including the parts that look like bugs. Where the two dialects disagree with each other, each is mirrored on its own terms rather than unified into something neither Bruno reader would produce.

A drift gate proves it. Every file this server writes is parsed back with Bruno's own reader, per dialect, in the test suite. Asserting our bytes against our own expectations can only prove we are self-consistent; asserting them against the reader that Bruno itself uses is the only thing that catches the case where our output stops being Bruno's input. It has caught real ones — a file body that parsed cleanly and would have been sent with no body at all, for instance.

The claim, then: run behaviour matches bru run, and every divergence found so far is closed. What keeps it closed is a test rather than a promise. Find one anyway and it is a bug worth an issue.

The contract

One collection, three consumers: your agent, your CI, and your team's Bruno GUI.

Both Bruno formats work and the server detects which one you have: .yml (opencollection) and .bru (legacy).

Requires Node.js >= 22. CI tests 22.x and 24.x.

Which Bruno MCP server should I use?

There are several, they do genuinely different jobs, and the honest answer is not always this one. Every row below was read out of that project's own README or source, August 2026.

Pick one of the others if: you want the server Bruno itself maintains, and whatever support and longevity that implies (usebruno — the official one, and the reasonable default for "discover and run" once it ships); you want an agent to understand a large existing collection without any risk of writing to it, and search it by intent (dmpv, first published July 2026 and at 0.x — new, and interesting); you already have the bru CLI in your image and only ever need "run this collection" (hungthai1401); or you want the agent to call your API through your existing requests as if each were a native tool (djkz).

Pick this one if: you want the agent to write the collection and not just read or run it, you are on .yml opencollection format, you need the run to happen without installing the Bruno CLI, or you care that what lands in your repo is byte-comparable to what the Bruno app writes.

On the fork parent specifically, since this project owes it its existence: macarthy/bruno-mcp registers eight tools — create_collection, create_request, create_environment, create_crud_requests, create_test_suite, add_test_script, list_collections, get_collection_stats. It writes .bru files and does not read a request back, run anything, or expose an edit tool; a updateRequest helper exists in its src/bruno/request.ts but no MCP tool reaches it.

Features

Authoring

• Collections — create and organise them, or discover the ones Bruno already knows from its workspace.yml. A collection this server creates is written to disk and not registered in that file, so list_collections will not show it and the Bruno GUI will not list it until someone opens it there once — everything else takes the path directly
• Requests — every HTTP method, with headers, query and path params, bodies, auth, assertions, vars and settings
• Read back — read_request and read_environment return structured JSON, identical for .bru and .yml, so an agent can inspect before it edits
• Partial-merge edits — write_request changes only the fields you pass and leaves the rest of the file alone
• CRUD and suites — five-request CRUD sets, and test suites with topological dependency ordering
• Environments — create, replace, merge, or patch a single variable
• Dual format — .bru (legacy) and .yml (opencollection), auto-detected; .yaml is read and flagged
• Multipart uploads — form-data with per-part Content-Type and multi-file fields

Running

• Execution groups — run one collection as several isolated groups in a single call: different identities, different environments, serial or concurrent, with no leakage between them
• Real parallelism — fan out groups, or requests inside a group, under a concurrency ceiling sized for the machine
• Cookie jar — a login carries into the requests after it, scoped to its group and never written to disk
• Variable chaining — bru.setVar()/bru.getVar() across requests, and captureVariables to read the values back out
• Async scripts — top-level await, bru.sleep(ms), setTimeout/setInterval inside the sandbox
• Inline scripts — attach pre-request, post-response and test scripts directly when creating or modifying a request
• Auth applied for you — bearer, basic, api-key, digest, OAuth 2.0 (client credentials and password grants), or inherit from the collection or folder
• Honest results — per-group summaries, captured response bodies, per-request warnings, parse failures and missing requests all reported; a crashed group cannot make a run read green

Safety

• SSRF protection on every request and every redirect hop, with the approved addresses pinned
• Path confinement for request references, collection roots, environment names and file uploads
• Process-isolated scripts — a forked V8 sandbox with a scrubbed environment and a hard kill

Install

Nothing to install. Point your client at npx and it fetches the published package on first run:

npx -y @ostico/bruno-mcp

That is the whole install, and it is what the client configs below use. The package ships with provenance, so npm can show you which commit and workflow built the tarball you are running.

Pinned instead, if you would rather not resolve a version at startup:

npm install @ostico/bruno-mcp

which puts a bruno-mcp executable in node_modules/.bin/ and the server itself at node_modules/@ostico/bruno-mcp/dist/index.js.

From source, for development or to run a branch:

git clone https://github.com/Ostico/bruno-mcp-studio.git
cd bruno-mcp-studio
npm install     # npm, not yarn — the yarn lockfile is stale
npm run build

Node.js >= 22 either way.

Connect a client

Any MCP client works. This is a plain stdio MCP server with no client-specific code: whatever your client calls it, point it at

command: npx
args:    ["-y", "@ostico/bruno-mcp"]

Claude Code takes it as one line:

claude mcp add bruno -- npx -y @ostico/bruno-mcp

Claude Desktop, Claude Code, Cursor, Codex CLI, opencode, Windsurf, Zed, Cline, Continue, LM Studio, Gemini CLI, MCP Inspector, your own SDK client — all the same server. Nothing below is a compatibility list; it is just where each client keeps its config.

Most clients use the same JSON shape:

{
  "mcpServers": {
    "bruno-mcp": {
      "command": "npx",
      "args": ["-y", "@ostico/bruno-mcp"],
      "env": {}
    }
  }
}

Running a clone, or a pinned install, is the same config with "command": "node" and "args": ["/absolute/path/to/dist/index.js"].

Config schemas are the client's, not this server's, and they move. If a client's format differs from the JSON above, follow the client's docs; only command and args matter here.

See INTEGRATION.md for worked examples, Docker, and troubleshooting.

Quick start

// 1. create a collection
{ "name": "my-api", "outputPath": "./collections", "baseUrl": "https://api.example.com" }

// 2. add a request with a test
{ "collectionPath": "./collections/my-api", "name": "Get Users", "method": "GET",
  "url": "{{baseUrl}}/users",
  "scripts": { "tests": "test(\"ok\", function() { expect(res.getStatus()).to.equal(200); });" } }

// 3. run it
{ "collectionPath": "./collections/my-api" }

Tools

18 tools. File paths are absolute, or relative to the collection.

Reading before writing

read_request returns method, url, headers, query and path params, body, auth mode, scripts, assertions, vars, settings and docs — identical shape for both formats, so the on-disk format stays invisible. Its notes array names anything the file declares that the runner will not act on.

Use it before an edit to see the current state, and after a write to confirm what was written.

read_environment returns each variable with its value. Secrets come back by name only — Bruno stores no value for a secret in either format, so there is none to return.

Writing requests

write_request creates when you pass collectionPath and name, and edits when you pass filePath. An edit merges: fields you omit are left alone.

Notable options:

• body.type — json, text, xml, sparql, graphql, form-urlencoded, form-data, file, binary, none
• body.type: "form-data" — multipart uploads, per-part contentType, multi-file fields
• auth.type — bearer, basic, api-key, digest, oauth2, inherit, none
• scripts — inline pre-request, post-response, tests (no separate add_test_script call needed)
• settings.timeout — script and request timeout in ms

name and filename are independent, as they are in Bruno itself: name changes the request's name inside the file and filename moves the file, so pass both to keep them in step. A filename is a basename in the request's own folder, its extension is optional and must match the collection's format if given, and a name already taken by another file is refused. The path it moved to comes back in the response — use it as filePath from then on.

write_request replaces a script of the same type by default, so repeating a call is idempotent. Pass scriptMode: "append" to concatenate. add_test_script appends by default, being an add.

In .yml collections post-response and tests share Bruno's single after-response slot, so replacing either overwrites both.

Moving requests

move_request relocates a request file — into another folder, or into another collection with targetCollectionPath. Pass copy: true to duplicate it instead.

The bytes are moved verbatim, never parsed and rewritten, so nothing a request declares can be lost on the way. Two consequences follow from that. The file keeps its name, so a copy needs a different folder or collection; renaming is write_request. And seq arrives unchanged, so the request can land next to a sibling claiming the same number — that is reported rather than repaired, because renumbering means rewriting the file. Bruno breaks such a tie by filename, so the order is defined either way.

A missing target folder is created, and reported: a folder with no settings file carries no folder-level auth, headers or scripts.

Running

{
  "collectionPath": "./collections/my-api",
  "environment": "dev",
  "requests": ["auth/login.bru", "users"]
}

A directory in requests expands to the requests under it, ordered by seq within each folder, subfolders first, ties broken by filename. Duplicates are honoured: naming a request twice runs it twice.

By default nothing stops a run early. A request that fails, a file that will not parse, a name that matches nothing — each is reported and the run continues.

Stopping at the first failure

bail: true stops the run at the first request that fails or whose tests fail. Twenty-three requests behind a login that stopped working is twenty-three failures for one cause, and the cause is the least visible of them.

{
  "collectionPath": "./collections/my-api",
  "bail": true
}

Everything the run did not reach comes back in place, marked skipped: true with skipReason: "bail", carrying the method and URL it would have sent. Those requests are counted in summary.skipped and in neither passed nor failed, so passed + failed still equals total and a truncated run cannot read as a shorter one that went green. The run itself gains a bail object:

{
  "bail": {
    "reason": "test failure",
    "at": "Login",
    "path": "/collections/my-api/auth/login.bru",
    "group": 0,
    "skipped": 22
  }
}

reason is either request failure (nothing came back) or test failure (it came back and a check failed). Later groups are skipped whole.

Nothing cancels a request already in flight. With parallel, or with a group of its own that runs concurrently, the requests that had already started still finish and are reported normally — the run says so in warnings rather than leaving you to infer it from the count.

Execution groups

A group is an isolated run inside one call. It owns its request list, environment, variables, parallel flag, variable store, cookie jar and OAuth2 tokens. Nothing crosses from one group to another, in either direction, at any parallel setting.

The same requests as two users, with no chance of one login's token or session cookie reaching the other:

{
  "collectionPath": "./collections/my-api",
  "parallel": true,
  "groups": [
    { "name": "alice", "requests": ["auth/login.bru", "orders"], "variables": { "user": "alice" } },
    { "name": "bob",   "requests": ["auth/login.bru", "orders"], "variables": { "user": "bob" } }
  ]
}

parallel: true runs the two groups against each other. Each group's own requests stay serial, which is what you want when orders depends on the login before it.

One suite against two environments:

{
  "groups": [
    { "name": "staging",    "requests": ["smoke"], "environment": "staging" },
    { "name": "production", "requests": ["smoke"], "environment": "production" }
  ]
}

Group fields: name, requests, environment, variables, parallel, startAfter, data, dataFile.

docs/execution-groups.md covers the whole model: what a group owns, the two parallel flags and their defaults, ordering, iterations over data rows, the concurrency ceiling, and what a failure looks like at each level.

• Omit requests to run the whole collection under that group's identity. An empty [] runs nothing.
• environment replaces the run-level one; variables merge over the run-level ones, group winning.
• Set parallel on a group to run its own requests concurrently. They share that group's store, so they can genuinely contend on a bru.setVar — the point when reproducing a race. Give maxConcurrency at least as many slots as racers, or the cap serialises them quietly.
• startAfter: { group, requestsCompleted } holds a group until another has got that far — a listener connected before a trigger fires, without a bru.sleep tuned to that day's latency. Needs run-level parallel; a request that failed still counts as a position reached; cycles and gates that could never open are refused before anything runs.

Results

Results are group-shaped. There is no top-level results array, not even when you passed no groups — that case is one group, and flattening it would make every caller check which way they had called.

{
  "summary": { "total": 4, "passed": 3, "failed": 1, "duration_ms": 1250 },
  "groups": [
    {
      "name": "alice",
      "index": 0,
      "summary": { "total": 2, "passed": 2, "failed": 0, "duration_ms": 620 },
      "results": [
        {
          "name": "Get Users",
          "method": "GET",
          "url": "https://api.example.com/users",
          "status": 200,
          "duration_ms": 312,
          "tests": [{ "description": "ok", "status": "pass" }],
          "response_body": "[{\"id\":1}]",
          "response_content_type": "application/json",
          "response_body_truncated": false,
          "response_headers": {
            "content-type": "application/json",
            "strict-transport-security": "max-age=31536000",
            "set-cookie": ["session=[redacted]; HttpOnly; Secure; SameSite=Lax"]
          }
        }
      ],
      "capturedVariableNames": ["authToken"]
    }
  ]
}

Each group carries its own summary, results, missingRequests, capturedVariableNames, capturedVariables and warnings. The top-level summary covers the whole run.

response_headers needs no flag and no test script. Credential-named values are masked, and set-cookie is a list — one entry per cookie, because a comma-joined one cannot be split back — whose entries keep every attribute with only the cookie value withheld. Checking HttpOnly, Secure, SameSite or Strict-Transport-Security is therefore a single call. includeResponseBody: false does not suppress them: that flag is about a body's size.

A WebSocket result carries response_headers as well, holding the handshake response — the 101 is the only place a session cookie or an agreed sec-websocket-protocol appears for that transport, since frames have no headers. A gRPC result reports its metadata under its own grpc detail instead.

A group that could not start at all reports error instead of results and counts as one failure — otherwise a run with a dead group would read green.

Run-level fields: parseErrors and parseFailures name files that could not be parsed, warnings collects anything else worth seeing.

Scripts

Scripts run in a V8 context inside a forked process (see Security). Both kinds are async functions, so top-level await works.

Tests and post-response get test(), expect(), res and bru:

Pre-request scripts get req and bru instead — there is no response yet. Mutating req changes what is sent: req.getUrl(), req.setUrl(), req.getMethod(), req.getHeader(), req.setHeader(), req.getHeaders(), req.getBody(), req.setBody().

Two things that catch people out

Wrap assertions in test(). A bare passing expect() is never recorded, so the run reports "tests": [] while the request counts as passed — green with nothing asserted. The runner spots this and says so in that result's warnings. A bare failing assertion is not silent: it throws and is reported as a script error.

test("status is 200", function() {          // ✅ recorded
  expect(res.getStatus()).to.equal(200);
});

expect(res.getStatus()).to.equal(200);      // ❌ runs, passes, reported nowhere

Do not JSON.parse(res.getBody()). It is already an object whenever the media type's subtype is json or carries the +json suffix — application/json, text/json, application/vnd.api+json — so parsing again throws SyntaxError: "[object Object]" is not valid JSON. Read fields directly. If an endpoint may return either, branch: typeof b === "string" ? JSON.parse(b) : b.

Reading a claim out of a token needs no second request. atob and btoa are both present, under the names Bruno's own sandbox uses, so the usual base64url dance works:

test("the token is for the user we logged in as", function() {
  const payload = res.getBody().token.split(".")[1];
  const claims = JSON.parse(atob(payload.replace(/-/g, "+").replace(/_/g, "/")));
  expect(claims.uid).to.equal(bru.getVar("expectedUid"));
});

Buffer is not available. It is a host class with affordances a sandbox should not hand out, and a faithful stand-in would be a fake whose gaps you would find one at a time; a bare reference throws Buffer is not defined, which is reported as a script error rather than silently misbehaving.

Sleeping counts against the script timeout — settings.timeout, 5000 ms when unset. await bru.sleep(10000) under the default reports a timeout instead of waiting.

Environments and variables

An environment is environments/<name>.yml in the collection:

name: dev
variables:
  - name: baseUrl
    value: https://api-dev.example.com
  - name: apiKey
    value: dev-key-123
  - name: skipped
    value: whatever
    disabled: true

The tools take variables as a flat object ({"baseUrl": "..."}) and write that array for you.

{{name}} is substituted into urls, headers, bodies and auth. Disabled variables are skipped; unresolved ones are left as written and named in the run's warnings.

Precedence, lowest first: environment file → run variables → a request's own vars → bru.setVar during the run. This matches Bruno's --env-var behaviour.

A variable may be built out of others: base_url: "https://{{host}}/{{stage}}" resolves the way it does under bru run, using Bruno's own interpolate. One exception, deliberate: a value captured from a response — by bru.setVar or a post-response vars block — is inserted as text and never scanned again, so a response echoing key={{api_key}} cannot make the next request send your key.

Generators. {{$guid}}, {{$timestamp}}, {{$randomEmail}} and the rest of Bruno's ~120 dynamic variables work in urls, headers, query params, bodies and auth. They are not variables: nothing declares them, each occurrence produces its own value, and none is reported as unresolved. A keyword no generator answers to — {{$gid}} — is left as written and named in the warnings, so a typo still surfaces. In a JSON body or a GraphQL variables block the generated value is escaped, so a generator that emits a newline ({{$randomLoremParagraphs}}) leaves the document parseable.

Secrets: neither Bruno format stores a secret's value — only its name. So pass secrets as run variables, which stay in memory and are never written to a file.

An environment name is a name, not a path. Anything containing a separator is refused.

Report files

run_collection returns its results as JSON, which is what an agent reads. The two other consumers of a test run read files, so report writes them:

{ "collectionPath": "/path/to/collection",
  "report": { "junit": "reports/junit.xml", "html": "reports/run.html" } }

Name either format or both. The result then carries reports, one entry per file written, with its absolute path and its size in bytes.

Paths are confined to the collection. A path resolving outside it is refused and the reason becomes a run warning; the run itself still succeeds, because the results are what was asked for and the file is a by-product. Copy the file afterwards if your pipeline collects reports from somewhere else — writing wherever a caller points is a much larger authorization than running its requests. Missing parent directories inside the collection are created, and an existing report is overwritten.

The JUnit XML follows bru run --reporter-junit: one <testsuite> per request, one <testcase> per assertion or test, and a request that errored reported as a suite error. Four things it does differently, each because the alternative is a report that reads greener than the run:

• A request that ran and verified nothing gets one skipped testcase saying so, instead of an empty suite. An empty suite is invisible in every CI summary, which is exactly the "ran green, checked nothing" reading that the requestsWithoutTests counter exists to expose.
• A request file that would not parse, a named request that resolved to nothing, and a group that crashed each get a suite of their own. A report listing only what executed says a subset ran without saying it was a subset.
• A named group's label is folded into the suite name, since JUnit has no concept of one and two identities running the same request would otherwise be indistinguishable.
• No hostname attribute. Upstream writes the machine name into the file; these reports are meant to be committed.

The HTML report is Bruno's own, rendered by @usebruno/common, with execution groups as its iterations — a two-identity run reads as two sections. Two things to know: the page embeds the run's data but loads Vue and naive-ui from unpkg.com, so it needs network access when opened and shows nothing offline; and its request pane is empty, because a result does not retain the request as it was sent. Assertions and script tests share one list for the same reason — a result does not tell them apart.

A report holds what the results hold, on disk: response bodies included, response headers masked exactly as they are in the JSON.

Formats

New collections are YAML unless you pass format: "bru".

.yaml request files are read as YAML, exactly like .yml, because other Bruno-adjacent tooling writes them. But Bruno's own app and bru run do not recognise the extension, so every .yaml file read is named in the run's warnings — a silent pass would be a green run of a request Bruno cannot see. Rename to .yml to clear it. Nothing this server writes uses .yaml.

gRPC and WebSocket requests

A collection may hold gRPC and WebSocket requests alongside HTTP ones. This server reads, preserves and reports them: read_request returns the kind, the target, the method and proto path for gRPC, its metadata block, and how many messages are stored; list_requests lists them; and editing any request in the collection no longer destroys them. Before this, both formats dropped the target block, the credentials and every stored message, so one write_request on an unrelated request rewrote the file without them.

run_collection runs both. A gRPC request performs one unary call against the service its .proto declares; a WebSocket request opens the socket, sends the frames the file stores and records what comes back until a bound is reached. Each reports its own detail: a gRPC result carries the gRPC status code, the details string and redacted trailing metadata, and a WebSocket result carries the transcript, the stop_reason that ended it and whether it was truncated. The gRPC code lives in its own field and is never mapped onto the result's status, because gRPC's OK is 0 and 0 is this API's refusal sentinel — a successful call and a security refusal would otherwise be indistinguishable in the field read first.

A WebSocket session has no natural end, so it is bounded, and every bound is settable per run under run_collection's websocket argument:

The wall-clock ceiling is a safety bound rather than a schedule, so idleTimeoutMs is what usually ends a session: once nothing has arrived for 1500 ms it stops and reports stop_reason: "idle", which is not counted as truncation because no cap bit and the ceiling went unspent. The clock is armed by the first frame, not at connect, so a listen-only request that authors no messages still waits out maxDurationMs for a peer that may yet speak. Set it to 0 for a protocol whose gaps are longer than its answers.

sendIntervalMs is what makes a send-wait-send protocol reachable. At the default of 0 a request's messages all leave in one tick, so every reply arrives after the last of them and the exchange has no order to assert on; set a gap and the transcript carries each answer between the sends it belongs to, at the offset it actually arrived. Two consequences worth knowing. maxDurationMs has to cover the whole paced sequence — a session stopped part way through names the messages that never went out, by their authored name, rather than leaving a transcript one send short to be read as a peer that stopped answering. And the idle bound is not armed while the sequence is still going out, so a sendIntervalMs longer than idleTimeoutMs is safe: the gap a request deliberately leaves between its own messages is not the peer's silence.

A subprotocol is authored as a Sec-WebSocket-Protocol header on the request, comma-separated for more than one, and is negotiated at the handshake; the one the server agreed to comes back in that result's response_headers. There is no separate field for it, here or in Bruno. Writing the header used to be worse than leaving it out: the library validates the server's answer against the list it was given at the connection, so a server that did exactly what the header asked for had its handshake refused for offering a subprotocol nobody requested. An authored Sec-WebSocket-Version is honoured the same way, for the same reason.

Each transcript entry says what kind of frame it was — text, binary, ping, pong or close — carries the authored title of a message the session sent, and, on a close frame, the close_code the peer gave, with its reason as that entry's payload: 1000 is an ordinary goodbye, 1006 a peer that vanished without one, 1008 a refusal, 1011 a server error. Control frames do not count toward maxMessages, or a peer that pings once a second would end a session by itself and report count for one that received no answer. A binary frame's payload is base64 and bytes is the true wire size for every kind. A post-response script sees the same fields, because the transcript is what res.body is on this transport.

Asserting on a gRPC or WebSocket result

Both transports run post-response and test scripts, and res is shaped so there is one thing to learn rather than two. What differs from HTTP is worth stating outright, because guessing it wrong makes a test that cannot fail.

On a WebSocket request:

• res.getBody() is the transcript — the same array the result carries, handed to the script as a structure rather than as JSON text. res.rawBody keeps the serialised form.
• res.getStatus() is always 0. A session has no status, and inventing one would be worse than having none. The outcome is in res.statusText, which carries the stop reason (count, timeout, bytes, closed or error).
• So a WebSocket assertion reads frames and statusText. A test written against res.getStatus() asserts on a constant.

test("the server answered our subscribe", function() {
  const inbound = res.getBody().filter(f => f.direction === "in" && f.type === "text");
  expect(inbound.length).to.be.at.least(1);
  expect(inbound[0].payload).to.contain('"subscribed"');
  expect(res.statusText).to.equal("count");
});

The payloads a script sees are always the real ones, whatever includePayloads says. That flag gates the transcript in the result, not the one in res, because outbound frames are recorded after {{var}} interpolation and a result returned by default must not carry every secret you passed in. This is the split HTTP already has — res.body always holds the full body while response_body is gated by includeResponseBody. It means includePayloads: false together with content assertions is the intended shape for CI, not a workaround: the assertions check the payloads, and what comes back holds only direction, timing and sizes.

On a gRPC request res is closer to HTTP: res.getStatus() is the gRPC status code (0 is OK), res.statusText is the server's own details when it supplied any and the code's canonical name otherwise, res.getBody() is the parsed response message, and the response trailers arrive as the headers.

includePayloads is off by default as a security property, not a preference: outbound frames are recorded after {{var}} substitution, so recording them by default would write every secret passed in variables into a result that is returned by default. engineIoKeepalive is off for a related reason — it puts a frame on the wire the request did not author — and even when on it replies only after an OPEN frame has actually been seen.

A WebSocket request can now be authored rather than copied. write_request takes kind: "websocket" with a url and websocket.messages, and refuses the fields that transport has no place for: an HTTP method, a body, query parameters, path params. Each message carries content and, optionally, a title and a type of text or binary; an untitled message is named message 1, message 2 by position, exactly as Bruno names one. Headers, auth, assert, vars, settings and scripts work as they do for an HTTP request, and the written file is byte-identical to what Bruno writes for the same request in both formats — proven against upstream's own writer, not against a round-trip through our parser.

One field is recorded differently by the two formats. selected: false marks a message as authored but not sent. .yml writes the false. .bru expresses only the true half: upstream's writer emits the flag when it is set and nothing when it is not, and its reader resolves an absent flag to false — so in that dialect a deselected message and an unmarked one are the same message, and neither is sent. A run follows that reading, which means a hand-written .bru message is sent only if it says selected: true; every message skipped for the lack of it is named in the result's warnings, so a request that now sends nothing says why instead of reporting an empty session. Authoring a deselected message into a .bru collection writes it with no flag, exactly as Bruno does, so the file behaves as asked; what the dialect loses is only the report, since reading the request back finds the flag absent rather than false.

A gRPC request is authored the same way, with kind: "grpc": a url, and under grpc, the fully qualified method, the protoPath, the methodType and the messages. It too refuses an HTTP method, a body, query parameters and path params. Three things about it are worth knowing before you write one.

Headers become metadata, which is that transport's only header surface — a headers block on a gRPC request is one Bruno's gRPC reader never looks at, so the headers argument is written as metadata instead. The protoPath must already exist inside the collection and is stored relative to it whichever spelling you give, because an absolute path is the operator's directory layout committed to a shared file; a path resolving outside the collection is refused, symlinks included, as is one whose imports leave it however many hops in (a well-known google/protobuf/ import is not a file and is not refused). And all four methodType values are accepted, because Bruno writes all four — but only unary runs here, so the other three author a file Bruno can open and run_collection will refuse by name. As with WebSocket, the bytes are identical to Bruno's own writer in both formats, including the two dialects' disagreement about spelling: .bru writes protoPath inside the grpc block, .yml writes protoFilePath.

write_request edits both transports. A url, headers, auth, assert, vars, settings, name and sequence all apply, as does the nested websocket or grpc object — its messages, and for gRPC the method, protoPath and methodType. Each field is written where that transport keeps it, so a gRPC header edit lands in metadata and never writes a headers block. Everything the edit does not name comes back byte-identical, which matters more here than for HTTP: an edit regenerates the whole file from a parsed model, so anything the model does not carry is gone without a message.

What is still refused is what the transport genuinely has no place for — an HTTP method, a body, query parameters, path params, and the other transport's object — by name, leaving the file byte-unchanged. Refusing url, headers and auth as well used to be the behaviour, which meant a WebSocket request's target could not be changed for the life of the file.

A pre-request script runs on both transports, and reaches what each of them actually has. bru.setVar is honoured and the value reaches that same request's own {{placeholders}}, so a script can compute a room name, a topic or a target and then dial it. req.setUrl replaces the target. req.setHeader writes the transport's own header surface: a WebSocket's handshake headers, or a gRPC call's metadata — which is the same surface, since grpc-js puts metadata on the wire as HTTP/2 headers. A script that throws stops the request before anything is dialled, and the failure is reported as itself. req.getUrl() and req.getHeaders() read the substituted target and the request's own headers; credentials the transport computes are not among them, because auth is applied after the script. The one thing not honoured is req.setBody(), which warns instead: neither transport sends a single body — a WebSocket session sends a list of messages and a unary gRPC call sends one typed message — so there is nothing for one value to replace, and guessing would put bytes on the wire the file never authored.

Both transports are loaded lazily, and that is enforced rather than asserted: a test records every module the real server resolves and fails if an HTTP-only run names @grpc/grpc-js or ws. Measured, an HTTP-only run loads undici and neither of them.

Two things are refused rather than guessed at. A file whose declared type and target block disagree (type: grpc with an http: block) is a parse error naming both, because the type decides what a reader reports while the block decides what a runner contacts. And a .bru request whose target url is empty is refused on write, because the format drops such a block while keeping the credentials beside it — the result would look authored and go nowhere.

Five things are deliberately not built. Streaming gRPC calls and held-open WebSocket sessions would make a run's result depend on when it was read, and every response here is a value a caller can assert against. Server reflection would fetch the schema over the same connection under test, so a .proto path is required instead. Proxy support and certificate pinning do not reach these transports: the gating is undici-only, @grpc/grpc-js exposes no proxy API and honours ambient http_proxy on its own, and ws would need an agent of its own. And a socket.io or MQTT block would invent a file format upstream has not chosen, which is a migration the moment it does.

socket.io needs no block, because it is a framing convention on top of WebSocket rather than a protocol of its own. Measured against socket.io 4.8.3, a plain ws request reaches one:

1. Connect to ws://host:port/socket.io/?EIO=4&transport=websocket. Both query parameters are required — EIO=4 selects the Engine.IO version, and transport=websocket stops the server expecting an HTTP long-polling handshake first.
2. The server sends 0{…}, the Engine.IO OPEN packet. Its payload carries sid, pingInterval and pingTimeout in milliseconds.
3. Send 40 to join the default namespace — nothing works before this. A named namespace is 40/namespace,.
4. The server answers 40{"sid":"…"}.
5. Send an event as 42["event-name",payload]: 4 for MESSAGE, 2 for EVENT, then a JSON array whose first element is the event name.
6. The server sends 2 (PING) every pingInterval and disconnects a client that does not answer 3 (PONG) within pingTimeout. Set websocket.engineIoKeepalive on run_collection if a recording outlives that window; it is off by default and answers only after a real OPEN frame has been seen.

Steps 1 to 5 are frames the request file already stores, so only step 6 needs anything from the runner. This is pinned to EIO=4 — Engine.IO v2 and v3 frame differently. Acks (42<id>[…] answered by 43<id>[…]) and binary attachments (a 45 placeholder followed by separate binary frames) are writable by hand and unpleasant in practice.

Security

SSRF. Every outbound URL, including each redirect hop, is resolved and checked. Private, loopback, link-local and otherwise reserved addresses are refused, and the approved addresses are pinned for the request so the name cannot resolve to something else in between. A refusal is reported per request as an SSRF blocked error with status 0.

Scripts run in a V8 context inside a forked, disposable process. The child gets a scrubbed environment, so a script that escapes the context still cannot read the server's secrets — they are not in its address space. Its stdout is piped, never inherited, so it cannot write onto the MCP JSON-RPC stream. A runaway script is bounded by SIGKILL on the child, which the in-context timeout alone cannot guarantee. This is defence in depth via an OS process, not a jail: it does not prevent code from running in the child, it makes running there worthless.

Paths. Request references must stay inside the collection. collectionRoot must contain the collection path. Environment names may not contain separators.

File uploads. A form-data file part names a path on the server's disk, so it is confined: readable only under the collection root, the user's home directory, the OS temp dir, or a directory the operator added. On top of that, any path component starting with . is refused — so ~/.ssh/id_rsa, .env and .aws stay unreadable even though home is allowed. Relative paths resolve against the collection root.

Operator escape hatches, all off by default:

An allowlist entry matches a target's exact spelling. An allowlisted hostname is never resolved — the operator vouched for the name, not for whatever it points at today — so it does not cover the addresses behind it, and an allowlisted address does not cover a name that resolves to it. localhost and 127.0.0.1 are therefore two entries, and allowing one while a request uses the other looks like an inconsistent guard when it is a missing entry. Refusals say so.

This constrains what run_collection will fetch. An agent with shell access can reach the network anyway, so treat it as one layer, not a boundary.

FAQ

Does it need the Bruno CLI (bru) installed?

No. The request pipeline is implemented here — variables, auth, cookies, redirects, assertions, scripts, dependency ordering — so nothing shells out to bru and nothing needs the binary on PATH. That is also why the parity work above exists: an independent implementation has to be held to the original deliberately.

Does it support .yml opencollection files, or only .bru?

Both, and it detects which one a collection uses rather than asking you. New collections default to .yml; create_collection takes format: "bru" if you want the legacy dialect. Where the two formats genuinely disagree — and they do — each is written the way Bruno's own writer for that dialect writes it.

A collection is one dialect or the other, though, not a mixture: the root manifest picks it, and Bruno reads only that extension, so a .yml request inside a bruno.json collection is a file in a directory as far as Bruno is concerned. This server still reads, writes and runs such a file — refusing would leave you unable to perform the fix, which is a rename of that very file — but every tool that touches or lists one tells you Bruno cannot see it, and names it.

Can I run this in CI?

The collection it produces is a normal Bruno collection, so CI runs it with bru run exactly as if a human had authored it in the app. The MCP server itself is for the authoring and debugging loop, where an agent is in the room. It writes JUnit XML and HTML report files as well — see Report files — so a run an agent drove still leaves the artefact a CI dashboard expects.

Will it rewrite files the Bruno app wrote?

Only the fields you asked to change. an edit through write_request is a partial merge, a key this server does not model is carried back out where the format can carry it — .yml throughout, and .bru wherever its grammar has a dictionary block to hold it — and every write is verified against Bruno's own reader in the test suite. Deletes need an explicit confirm: true.

Which MCP clients work?

Any of them — this is a plain stdio server with no client-specific code. Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex CLI, opencode, Zed, Cline, Continue, LM Studio, Gemini CLI, the MCP Inspector, or your own SDK client. See Connect a client for where each one keeps its config.

What happens to my secrets?

Secret environment variables stay in memory for the run and are never written to a file — neither dialect stores a secret's value on disk, which is Bruno's design, not a limitation added here. Credentials are redacted out of the results returned to the agent, including one placed in a query parameter. Scripts run in a forked V8 sandbox with a scrubbed environment. See Security.

Is this the same as the original bruno-mcp?

It started as a fork of macarthy/bruno-mcp, which has been inactive since July 2025 and generated collection files without running them. Everything above — the runner, the readers, both dialects, the parity gate, the sandbox — was built after the fork. The repository is now Ostico/bruno-mcp-studio (announcement); the npm package name is unchanged, @ostico/bruno-mcp.

Is it affiliated with Bruno?

No. Bruno is a product of usebruno and its name and trademarks belong to them. This is a community project that reads Bruno's open-source packages to stay compatible with them; it is not endorsed by or affiliated with usebruno.

Bruno's own team announced an official MCP server, usebruno/bruno-mcp, in August 2026. This is not it, and does not compete for that role — see Which Bruno MCP server should I use? for what each is good at.

Upgrading to 2.5.0 — four tools were merged into write_request

Four tools are gone. What they did, write_request does, with the same semantics: an edit still updates only the fields you pass and preserves every other field, byte for byte.

delete_request is unchanged and still here; it now also takes filePaths to delete a set in one call.

This fails closed. A client asks for the tool list at connect and gets the current names, so an agent that reads the list is unaffected. A call to a removed name is an unknown-tool error or a permission prompt — never a wrong result, never a silent one.

What actually needs editing is configuration that pins a name: a --allowedTools mcp__bruno-mcp__create_request argument, a settings.json permission entry, a hook matcher, and any prose in a CLAUDE.md or a skill that tells an agent to call one of the four by name.

Versioning

Tool names are discovered from tools/list at connect, not linked against, so renaming or removing a tool ships in a minor version. A call either behaves exactly as it did or does not exist, and the second case is loud.

Changing what an unchanged call does ships in a major version. That is the dangerous kind: 2.0.0 turned folders into execution groups, so a caller who changed nothing got a different result. Nothing quieter than that earns a major, because majors that do not signal danger teach you to ignore majors.

Upgrading from 1.x

• requestPath and folder are gone. Both become requests, an ordered array of files and/or directories.
• There is no top-level results array. Read result.groups[0].results.
• parallel: true used to isolate each folder. It does not any more: with no groups, the whole selection is one group sharing one store and one cookie jar. Name the folders as separate groups to keep the old behaviour.
• seq no longer constrains execution. It is the default order and the reporting order only.
• An empty requests: [] runs nothing. It used to run the whole collection.
• Removed exports: BruGenerator, generateBruFile, createBasicBruFile.

Full detail in CHANGELOG.md.

Development

npm run build       # compile to dist/
npm test            # full suite
npm run test:unit   # unit only
npm run typecheck
npm run lint

Use npm, not yarn — the lockfile is npm's and CI runs npm ci.

See CONTRIBUTING.md for what CI checks, the commit conventions, and the sign-off (DCO) every commit needs.

License

MIT — see LICENSE. Contributions are accepted under the same terms, with a DCO sign-off.

Links

• Bruno
• Model Context Protocol
• Changelog
• Integration guide

Support

If Test-Guard is useful to you, consider supporting its development:

Sponsor on GitHub