53 · The MCP server¶

stalwart mcp gives your AI coding assistant -- Claude Code, Cursor, VS Code -- the whole suite as tools: the guardrail, built with you and dry-run on your own calls; the gateway; the bug hunter; the red team; formal verification of your rules and of an agent's graph; and certificates, checked on your machine. Your assistant does each step through the server and brings you the result, with the page of the developer console that shows it and the chapter of this guide that explains it.

The server runs on your machine, over stdio. It calls Stalwart's service only where a step already does -- compiling a rule sheet, a hunt, a red team, a proof -- and it never calls a model: where a step needs one, such as drafting a rule sheet from your policy, your own assistant does it, through a prompt, and the server checks what it made.

Language support

The selector reads turns written in English and in Brazilian Portuguese (pt-BR). The language is chosen, never guessed from the turn: the console's Settings page (Language the selector reads), language on a plan request, or the settings.language of your vocabulary file; with none of them, English. A Portuguese turn may be typed with its accents or without them. European Portuguese is not a grammar the selector has, and a turn in any other language is unread.

Adding it to your assistant¶

In your project's folder:

$ stalwart mcp --config claude      # prints: claude mcp add stalwart -e STALWART_MCP_HOME=<this folder> -e QLS_API_KEY=<your key> -- ...
$ stalwart mcp --config cursor      # the mcpServers entry for Cursor
$ stalwart mcp --config vscode      # the servers entry for VS Code

Run it in your project's folder: the configuration names that folder (STALWART_MCP_HOME), so the server's files go there, never into the home folder a client starts servers in. Put your key in the configuration too: a server reads its environment once, when it starts, so a key set afterwards needs the server started again (status says so).

Then ask your assistant to call status: it answers with the folder the server works in, whether it has your key, your plan, and how much of each meter is left this month.

How it leads your assistant¶

An assistant uses what a server shows it, so the server shows it everything, and says where to go next:

Its instructions, which your assistant reads first, name every product and the tool for each, and tell the assistant to do every step through these tools rather than by writing code or reading the package's source.
Every answer says what comes next (next): what the step did not cover, and the tool that does. After a hunt that found nothing, for example, it says what the hunt did not read, and that verify_rules proves one action against your rules.
Every answer that leads to a page gives its address: console for the developer console's page that shows the result, guide for this guide's chapter on the step. links gives every address at once (below).
The assurance-plan prompt walks your assistant through every level in turn, says what each covers and what it uses of your plan, and asks you which you need.

A session that starts from nothing goes like this: status; catalogue_from_server on your tools' server; writes_file, and the kinds you check; a rule sheet your assistant drafts from your policy in plain words, which you read; compile_rules and lint_rules; check_sequence on a conversation's calls; hunt into a project; and, where you want it proved, verify_rules on the proof profile and check_certificate on what it wrote.

Its tools¶

Asking what it can do¶

Tool	Answers
`capabilities(language)`	every check, from the guardrail's own list: what it catches and cannot, its inputs and on-fail options; where it can run; versions; what is guaranteed and what is not
`explain_check(name, language)`	one check in full, with an allowed and a stopped example and its manual section
`search_manual(question, language)`	the manual's sections that best match, by their words, in English or Portuguese; no model
`how_to(goal, language)`	fixed recipes: "guard my MCP server", "add it to my Guardrails AI guard", "write a rule for refunds over 100", "evaluate on my traces", ...
`explain_decision(decision_id)`	why a recorded call was stopped: the check, its rule and what it read
`status()`	whether a key is set, its plan, what it may use and how much of each meter is left, and the folder the server works in: read it before a step that uses quota
`links(about, language)`	every address a person needs: each developer console page with what it holds, and where to sign in; the guide's chapter for each product; the API reference, the package's documentation, the package and where to sign up

Building and dry-running a guardrail¶

Tool	Does
`catalogue_from_server(server, out)`	reads an MCP server's tools into `tools.json`: its address, a saved `tools/list` reply, or the command that starts it (`npx -y @playwright/mcp@latest`), started here, listed and stopped
`writes_file(tools, out)`	drafts `tool_kinds.yaml`: each tool's kind, reason and source, unsure tools first
`set_tool_kinds(changes, reasons)`	sets kinds as your assistant proposes them, recorded as `source: assistant`
`compile_rules(sheet, out_dir)`	compiles `rules.yaml` with the service into `compiled/`
`lint_rules(sheet, tools)`	a rule for a tool you do not have; a write no rule names
`check_call(call, context)`	one dry-run answer; nothing runs
`check_sequence(calls, context, approve)`	a dry run of one session: each call answered with what the calls before it ran, so order rules, limits and confirmations are tried as a run meets them; a call asked about is answered again with a person's yes
`search_wordings(tools, language, checks, seconds)`	the wording search of the three checks that read the turn
`snippet(where, upstream)`	the code for `python`, `guardrails-ai` or `nemo`, or `gateway`'s `catalogue.json` and `gateway.yaml`

check_call answers one call alone. Order rules (after), limits (at_most) and confirmations are met only across a conversation, so try them with check_sequence: each call is answered with what the calls before it ran.

Measuring, hunting and red-teaming¶

Tool	Does
`replay(trace, format)`	every call's answer; counts by rule; the calls stopped; confirmations per 100 calls; p50/p95 time; determinism
`evaluate(labelled, format)`	false alarms and misses against your labels, per rule
`counterfactual(trace, outcome_checker)`	your own outcome check, as run and with the stopped calls removed
`hunt(sheet, properties, session_steps, profile, project, branch, commit)`	the bug hunter on your rules (the service, with your key); with a `project`, the scan is stored where the developer console's Findings page shows it, and the answer links the project's findings and each finding's page
`redteam(server)`	an MCP server's tools behind the gateway, proved for any call (the service, with your key)
`compare_with_gai(trace, guard)`	your Guardrails AI guard alone, and with our validator
`benchmark(name)`	fetches the tau2-bench airline or retail data from its pinned upstream commits

Proving¶

Tool	Does
`verify_rules(action, without, sheet, profile, certificate)`	formal verification of your rules: can `action` run without `without`? Yes with the witness; no, proved with a certificate on the `proof` and `patch` profiles, and the solver's word on `fast`
`verify_graph(graph, catalogue, rules, certificate)`	an agent's graph verified before it is deployed: every route to a risky action without its safeguard
`check_certificate(certificate, cnf)`	a certificate checked here, offline, by the checker the package carries (`stalwart check`)

Its prompts¶

assurance-plan: every level of assurance in turn -- build, dry-run, hunt, red team, prove, certify, monitor -- what each covers and does not and what it uses of your plan; your assistant asks which you need and does only those.
build-guardrail: the whole build, in order: tools, kinds, a rule sheet drafted from your policy in plain words, compile and lint, dry runs, search and hunt, the snippet. Your assistant drafts the sheet; you read it before it is used.
classify-tools: your assistant proposes kinds for the tools the inference is unsure of.
set-up-guardrail: a recipe from how_to, followed step by step.
evaluate-guardrail: replay and evaluate on your calls, with nothing quoted from them.

Results in the developer console¶

What the server does with the service is listed in the developer console, under your organisation:

Findings: hunt with a project (a name; the project is made the first time) stores the scan against it, on a branch and at a commit where you give them. The answer gives the project's address on the Findings page, and each finding's own. There you accept a finding with its reason, or leave it to fix, and the next scan of the project reads your decisions (chapter 28).
Jobs: every hunt, red team and proof is a job, with its state, its verdict and its files, a certificate among them (chapter 9).
Usage: what each meter has used this month against its cap -- status gives the same figures to your assistant (chapter 16).

links gives your assistant every address: each developer console page with what it holds, and where to sign in; this guide's chapter for each product; the API reference, the package's documentation, the package and where to sign up. links(about="findings") narrows each list to what names it. Chapter 5 has every console page.

A proof, or the solver's word¶

verify_rules asks one question -- can this action run without this condition? -- and answers it on the profile you name (chapter 10):

Yes comes with the witness: the conversation in which it runs. Fix the rule it passes, compile, and ask again.
No, on proof or patch, is a derived proof, with a certificate. The server writes it to certificates/, and check_certificate checks it on your machine, offline, with the checker the package carries (chapter 7).
No, on fast, is the solver's word, with no certificate. The answer says so, and says to ask again on proof for one.

A proof answers the question asked, and no other (what this proves). verify_graph proves an agent's graph before it is deployed (chapter 47).

The files it reads and writes¶

Every path is inside the folder the server works in; a path that would leave it is refused.

File	Written by	Read by
`tools.json`	`catalogue_from_server`	every guardrail tool
`tool_kinds.yaml`	`writes_file`, `set_tool_kinds`	every guardrail tool
`rules.yaml`	your assistant, from your policy	`compile_rules`, `lint_rules`, `hunt`, `verify_rules`
`compiled/`	`compile_rules`	`check_call`, `check_sequence`, `replay`, `evaluate`
`catalogue.json`, `gateway.yaml`	`snippet` with `gateway`	`stalwart gateway`
`certificates/`	`verify_rules`, `verify_graph`	`check_certificate`

Plan and quota¶

Hunts, red teams and proofs are the service's, and count against your plan; status says what is left before your assistant starts one, and a proof on the proof profile is counted apart (chapter 16). Building, dry runs, replays and checking a certificate run on your machine, and count nothing.

The limits¶

The server leads your assistant; it does not make it follow. An assistant that writes its own code instead still can, and its results are its own.
A report holds tool names, rule names, counts, decision ids and digests, never an argument value or a word a person said. To see a finding's witness in full, open its page in the console.
The red team reads your tools' server, not your agent's own routing: verify_graph is the step for that.