AI agents & MCP
An MCP server for API testing: give your agent the tests, not a description of them.
Because flows are plain text, an agent can genuinely work on them: read the YAML, run the flow, see exactly which node failed and what it sent, edit the file, run it again. The Bandura MCP server packages that loop as Model Context Protocol tools for Claude Code, Claude Desktop, and Cursor. It is a local stdio process on your machine, with no vendor relay in between.
v1.0.0-rc.8 is out now on Windows and Linux. v1.0.0 final, and signed macOS builds, in August 2026.
Ground truth, not guesswork
"The checkout flow is failing. Fix it."
The difference between an agent that helps and an agent that speculates is whether it can run the thing. Give it the run, the failing node's actual request and response, and a deterministic drift check against your spec, and the fix stops being a guess.
Every step there is a real tool call. detect_drift is deterministic code,
not a model opinion. It is the same comparison the app's
self-healing runs, and edit_flow
validates the YAML before a byte reaches disk.
The tools
Fourteen tools, all local.
| Tool | What it does |
|---|---|
list_flows | Enumerate the .aether files under the workspace root: path, name, node count. |
read_flow | Return a flow's raw YAML. |
run_flow |
Execute a flow and return structured results: per-node pass/fail, captured
variables, request/response snapshots sized for a model's context, and
anything the flow printed with log(). Accepts variable
overrides.
|
detect_drift | Compare a flow against an OpenAPI spec and return findings with proposed fixes. Deterministic and offline. |
import |
Convert curl, OpenAPI, Postman, Insomnia, or HAR source into
.aether, written to a directory or returned inline. A HAR is the
one exception to one-flow-per-request: it is a recording, so it yields a single
flow replaying the captured calls in order, with credential header values
replaced by variables rather than copied.
|
export_openapi | The inverse: generate an OpenAPI 3.0 spec from the workspace's flows, inline or into the repo. |
create_flow | Write a new flow. Validated first; an existing path is never overwritten. |
edit_flow | Replace an existing flow's YAML. Validated before writing; a missing path is rejected. |
list_runs | List the runs this server session has executed, newest first, with pass/fail and duration. |
read_run | Replay a recorded run by id: per-node snapshots and the timestamped event log, bodies as captured. Inspecting a payload never means re-executing a flow with side effects. |
describe_node_types |
Return the .aether schema itself: every node type's fields, which
are required, and what each enum accepts. Read from the parser's own validator
at call time, so the agent writes against the syntax this build accepts rather
than syntax it half-remembers.
|
lint_flow |
Check a flow, or all of them, without running anything: nodes nothing routes to,
loops with no body, TLS verification turned off, credentials written as literals
where an ${{ env.* }} reference belongs. The same rules
bandura lint runs in CI.
|
search_flows | Find nodes across every flow by type, URL substring, auth type, or free text, without reading each file in turn. |
get_project_status | What the workspace and this build actually contain: flow count, which node types are in use, what is supported, and any flow that fails to parse. |
The last four exist so the agent can check rather than recall. An assistant writing
.aether from memory gets the schema subtly wrong, and
describe_node_types cannot go out of date because it is generated from the
validator rather than written down.
list_runs and read_run replay this session's runs
from memory; durable history stays in the desktop app. Full parameter reference:
the MCP server docs →
Setup
How to connect it to Claude Code or Cursor: one command, because it ships inside the CLI.
The engine is compiled into the same binary, so there is no second package to
install and no server to keep running. Your client starts it.
On npm now
# The MCP server ships inside the bandura CLI. Nothing else to install.
claude mcp add bandura -- bandura mcp
@bandura/cli is published, so the command above works today; the
1.0.0 tag is held for launch day, which means you pin a release
candidate for now. MCP server reference →
{
"mcpServers": {
"bandura": {
"command": "bandura",
"args": ["mcp"],
"env": { "BANDURA_WORKSPACE": "/path/to/your/api-tests" }
}
}
}
Or register it as an ordinary stdio server in any MCP client's JSON config. The
workspace root comes from a root argument, then
BANDURA_WORKSPACE, then the working directory.
What the sandbox guarantees
Reads and writes are confined to the workspace root. A path that escapes it is
refused, not resolved. Written YAML is parsed and schema-validated first, so an
agent cannot leave you a file that looks plausible and fails at run time.
Whether you get asked before a write is your client's decision, not ours:
approval is an MCP client responsibility, and the good ones already do it well.
One window
Or run your agent inside the IDE, next to the graph it is editing.
Bandura's bottom panel is a real terminal, so Claude Code runs in it. The session
starts at your workspace root, which is the root bandura mcp serves, so
the flows the agent lists are the flows in your explorer.
npm install -g @bandura/cli
claude mcp add bandura -- bandura mcp
# then, in Bandura's terminal panel (Ctrl+backtick)
claude
One install, one registration, then claude in the panel.
Setup, in the docs →
Ask on the left, watch on the right
The agent edits a file on disk; the editor picks the change up and the canvas
redraws. You read a diff as a graph rather than as YAML, and you can run the flow
yourself before you believe any of it.
Save your open tab first. A tab with unsaved edits is never overwritten from disk,
which is the one case where the canvas and the agent disagree.
Or stay in the app
The same agent loop lives in the editor.
An agentic chat, not a chat box
The sidebar chat calls the same core tools (list flows, read one, run one, check
it against your spec) and reasons from what actually came back.
AI chat →
Edits behind a gate
When the in-app agent wants to create or change a file, it proposes the change and
you approve or discard it. Nothing is written on your behalf without that step.
Your model, including a local one
The app's AI is bring-your-own: Claude or Gemini natively, any OpenAI-compatible
endpoint, or a model on localhost.
Local LLM API testing →
Scope, stated
What this is not.
Not a hosted agent service
There is no Bandura cloud running flows for you, on a schedule or otherwise. The
server runs where your files are, for as long as your client keeps it alive, and
its run history goes away with the process.
Not a substitute for assertions
An agent is excellent at finding out why something failed. Whether a run
passes should still be decided by
assertion nodes with concrete expressions:
deterministic, reviewable, and the same for everyone on the team.
It does not approve its own writes
create_flow and edit_flow are validated and confined to
the workspace, but the "are you sure" prompt is your MCP client's job, not ours.
A client with no approval step will let an agent change files without asking, and
there is nothing this server can do about that from its side of the pipe.
Run history dies with the process
list_runs and read_run replay what this server session
executed, held in memory. Close the client and it is gone. Durable history, with
full captured bodies, lives in the desktop app's local SQLite file and does not
reach the agent.
Questions, answered straight
FAQ
What is the Bandura MCP server?
A stdio server, started with bandura mcp, that exposes your .aether flows to any Model Context Protocol client: Claude Code, Claude Desktop, Cursor, and others. It gives the agent fourteen tools: list flows, read one, run one, replay a recorded run, detect drift against an OpenAPI spec, import foreign formats, export a spec, create or edit a flow, lint flows, search across them, read the .aether schema itself, and report what the workspace contains. It runs the same engine, parser, and importers as the desktop app and the CLI.
Does my API traffic go through a cloud service?
No. It is a local process speaking over stdin and stdout. There is no network service, no relay, and no account. Your flows, the requests they send, the tokens they capture, and the responses they get back stay on the machine running the server. The model your client uses is whatever that client is already configured with; Bandura adds no provider of its own to the path.
Do I have to install anything besides the CLI?
No. The MCP server is compiled into the bandura binary, so bandura mcp is the whole setup. The workspace root resolves from a root argument on the tool call, the BANDURA_WORKSPACE environment variable, or the server's working directory, in that order.
Can the agent write to my files?
create_flow and edit_flow can, within limits that are enforced rather than requested: the YAML is parsed and schema-validated before anything is written, create_flow refuses to overwrite an existing path, edit_flow refuses a path that does not exist, and both are confined to the workspace. Whether you are asked before a write is your MCP client's job: approval UX belongs to the client, and Claude Code and Cursor both have it.
How is this different from the AI chat in the app?
Same loop, different host. The desktop chat is an agent with the same core tools (list, read, run, search, lint, detect drift, read the schema) plus file creation and editing behind an in-chat approve/discard gate, and it runs flows in the app's sandboxed execution process. Two differ by host: in the app, list_runs and read_run read the durable run history, so the assistant can explain a run you started yourself, and it can read the local error log. The MCP server is for when you would rather stay in your coding agent, with your repository, your editor, and your own model already in front of you.
Can the agent see the full response body?
run_flow returns request and response snapshots sized for a model's context; pass fullBody: true when you want them untruncated. If a run has already happened, read_run replays it from the session's history: per-node snapshots and the timestamped event log, with bodies as captured at run time. Inspecting a POST or a delete therefore never means executing it again. That history is in memory for the life of the server process, and is separate from the desktop app's durable run history.
Do ai-action nodes work when an agent runs a flow?
Yes, when the server's environment names an AI provider. A shell that is already configured usually needs nothing new: ANTHROPIC_API_KEY, GEMINI_API_KEY or GOOGLE_API_KEY, or BANDURA_AI_BASE_URL for any OpenAI-compatible endpoint including a local Ollama or LM Studio. The provider-neutral BANDURA_AI_* names take precedence over all of them. With nothing configured, only the ai-action nodes fail and the rest of the flow runs normally.
Can I run Claude Code inside Bandura itself?
Yes. The bottom panel is a real terminal, so a terminal-based agent runs in it like any other program. Register the server once with claude mcp add bandura -- bandura mcp, then run claude in the panel: the session starts at your workspace root, so that is the root the server reads and writes, and no per-project configuration is needed. When the agent writes a flow, the editor picks the change up from disk and the canvas redraws, so you review the change as a graph and can run it yourself. Save any tab you have unsaved edits in first, because Bandura never overwrites those from disk.
Is this the same model my agent is already using?
For the tool calls, yes: the MCP server adds no model of its own, so the reasoning that decides which tool to call is whatever Claude Code or Cursor is already configured with. An ai-action node inside a flow is the one exception, because that node names its own provider from the server's environment and runs during the flow rather than during the conversation.
Keep reading
Why an agent can work on these files at all.
Tests as plain files
YAML in your repo, diffable in a pull request, and readable by a model for the
same reason it is readable by a reviewer.
The same engine in CI
What the agent ran locally is what the pipeline runs: one command, one exit code,
JUnit for the dashboard.
Keep the model local
Ollama, LM Studio, or any OpenAI-compatible endpoint. No prompt or payload leaves
your machine.
Coming from Postman
Import the collections first. An agent can only work on flows that already exist
as files, which a hosted collection isn't.
Nothing transits a vendor
The stdio server is one piece of a larger claim. That page names the file every
other piece of your data sits in.
Coming from Bruno or Insomnia
Neither ships a first-party MCP server. The
Bruno and
Insomnia comparisons say where each of them
wins instead, and Postman vs Bruno compares the
two directly.
v1.0.0-rc.8 is out now. v1.0.0 final in August 2026
Hand your agent the suite.
You do not need the desktop app for this part. The CLI is on npm now with the MCP
server compiled into it, so claude mcp add bandura is the entire install
and your agent has fourteen tools a minute later. The desktop app is up for
Windows and Linux if you want the canvas and the debugger
too. On a Mac, or waiting for the
1.0.0 tag? Leave an address and you get the link the day it exists.
You're on the list.
Nothing to confirm. The signed macOS build and 1.0.0 final arrive by email the day they
ship. The Windows and Linux builds are downloadable now:
get the installer.
Wiring a client that isn't Claude Code?
The MCP server reference has every tool's parameters and the workspace-root rules.