Skip to content

feat(mcp): every tool that writes takes dry_run and answers the request it would send - #576

Merged
bim-ba merged 1 commit into
mainfrom
feat/mcp-dry-run
Oct 10, 2026
Merged

bim-ba merged 1 commit into
mainfrom
feat/mcp-dry-run

Conversation

@bim-ba

@bim-ba bim-ba commented Oct 10, 2026 •

Copy link
Copy Markdown
Owner

Every MCP tool that writes takes dry_run. With dry_run: true it sends nothing and answers the request it would have sent. Decision: #556 (question 1, A).

{"dry_run": true, "request": {"method": "PATCH", "url": "https://api.tracker.yandex.net/v3/boards/7", "body": {"name": "New"}}}

How it works, in one place for all 260 tools

Piece Where What it does
DryRun (middleware) new_server, so every ycli server has it takes dry_run out of the call, marks the call, answers the write the guard stopped
client_provider the one place a tool's client is built under the mark, builds the client with the core's Guard(dry_run=True) (#557)
DryRunOffered (transform) new_server adds the argument to every tool whose readOnlyHint is false, and the plan to its output schema

No tool declares the argument and no tool function changed.

The answer

Case Answer
a write would go {"dry_run": true, "request": {method, url, body}}; request is what ycli … --dry-run -o json prints, secrets masked by the same function
the request would grant access the same, with "grants_access": true (decided in this PR, see below)
the tool would write nothing (it only read) {"dry_run": true, "request": null}, never the data it read: the caller asked for a plan
a tool that answers a list the plan under result, where FastMCP puts that tool's answers
a tool that only reads refused: dry_run: Unexpected keyword argument. Its schema has no such argument
dry_run that is not true or false refused: dry_run: true or false
dry_run (or dryRun, dry-run) INSIDE an argument, at any depth refused before anything is sent: `dry_run` is the tool's own argument: give it beside `body`, not inside it

Reads the tool makes before its first write go out. The plan is of the FIRST write only. Measured over the contract cases: one tool makes more than one write, wiki_attachments_upload (it plans the opening of its upload session). No write tool ends a case without a write.

Can a dry run send?

By construction no: under dry_run the only client a tool can get refuses its first write.

Guard What it catches Seen failing
test_every_tool_that_writes_takes_its_client_from_the_one_guarded_place a write tool with another way to a service. Enumerated: all 260 take their client from client_provider; the only tools that reach a service otherwise are status_get (reads) and schema_get (no service) -
the contract check, 326 write cases the tool's plan differs from the command's, or either sent a write the provider made to forget the guard: 329 failures
test_calls_side_by_side_do_not_take_each_other_s_flag 40 calls on one server, plans and real writes interleaved: exactly the real ones are sent the same mutation
test_the_flag_is_set_for_the_one_call_and_for_nothing_after_it the mark outliving its call, after a call that returned and after one that raised the reset removed: both cases fail
a tool whose client is not the guarded one it is answered an error ("it ran for real"), never a plan -

A plan says that it would grant access

Under dry_run the guard used to build the plan without the reason. Now a plan of an operation marked grants_access carries it, and the tool's answer has "grants_access": true; the key is absent otherwise. The command's --dry-run output is unchanged (the reason is no field of the plan). Say if this should not be here: it is three lines and one key of the schema.

With the mark of #571

A tool that grants access prompts for a person on a dry run too, and in dontAsk mode the dry run is denied like the grant: the client decides from the tool's tools/list entry before the server sees any argument. Not avoidable from the server. In the reference (serve-the-mcp-server, en and ru), with the way out: ycli … --dry-run.

Changes for clients

  • Input schemas: one optional boolean on 260 tools. Not breaking.
  • tools/list, measured on the served server: 747,797 -> 791,215 bytes (+43,418, about 167 per write tool). Input schemas over 5,000 bytes (mcp: Codex compacts every tool schema over 5,000 bytes; upgrade FastMCP to 4.0.11 #372): 14 before, 14 after; the closest below the line, datalens_sparkclusters_create, went 4,748 -> 4,915. Largest input schema 29,264 -> 29,431, under the budget of 32,768, whose test is unchanged.
  • Output schemas: the served server lists none (it drops them to keep the listing small), so nothing changes there. A resource server run by itself lists them: a write tool's becomes {"type": "object", "anyOf": [<the plan>, <its own>], "$defs": <its own definitions>}, or for a tool that answers a list the same union under result. The definitions stay at the root, where the tool's references look for them. Measured on FastMCP 4.0.11: its client validates an answer against the schema, so the plan has to be in it. Side effect for a user of the FastMCP client on such a server: result.data of a write tool is a plain dict, not an object built from the schema; structured_content is as before.
  • Snapshots: mcp_signatures.txt and mcp_output_schemas.txt change for 260 tools each, which is the number of tools with readOnlyHint false.
  • The convention "every union a tool returns is discriminated" now passes over the plan member (it is first, is told by dry_run: true, and takes no other key), with two cases showing the check still bites.

After the review (five findings, all fixed)

Finding Fix The test that bites
the tool's own schema was nested whole, so its $defs sat under the union and 154 of 260 write tools had references pointing nowhere: schema_get could not find a part of a write tool's reply, and on a server that lists output schemas a real write was sent and the client then raised on the answer the definitions are lifted to the root of the union every $ref of every write tool's output schema resolves; through a real client on each service server alone, a plan and a normal answer both validate for a tool with definitions and for one that answers a list; schema_get finds Calendar of tracker_boards_update. My first schema test used dict[str, str], which has no definitions: that is why the suite was green
dry_run inside a body that takes any key was SENT as a field (tracker_issues_update with body: {…, "dry_run": true}) refused, in the three spellings, at any depth, before anything is sent over every write case with an object among its arguments, at two depths, three spellings: refused, nothing sent
every plan was logged as a failed tool call with a traceback the stopped write reaches FastMCP as an error it does not log; the signal's traceback is dropped two plans, the log captured at DEBUG: no "Error calling tool", no RequestPlanned, no record with a traceback
the parity check could not see masking switched off, both sides use one function a check that does not share it: a secret is put under every key a write tool's model marks secret, the call is planned, and the literal value must not be in the answer masking switched off in the core: it fails ("access_token came back in the plan")
the test called itself ARCH-3 and ARCHITECTURE.md was not in the diff ARCH-3 now states the rule and names its checks (flagged: this PR changes an invariant's text) -

Not fixed here, older than this PR and the same on the CLI (carried to #575): a secret the request MODEL does not mark comes back unmasked in a plan (tracker_triggers_create webhook password, datalens_trinoclusters_catalog_create connector password).

Also here

One line in the docstring of the tool-search class of #571: the FastMCP version its overrides were written against (4.0.11).

Verified

On this head, over main ec278275 (0.141.0; the commit's parent, by hash; #577 is in it, so the guard lines are no longer in this diff): ruff, ty, lint-imports, ast-grep (each by exit code, 0), the commit hooks over the commit (exit 0), rulesync and the generated reference without drift; the full suite: 8143 passed, 5 skipped, coverage 100 %.

NOT RUN: any live run (the plan is made before a service is reached; the reads before a write are the existing path); a check in a real Claude Code session of the prompt on a dry run of a marked tool (the vendor's page is the evidence).

🤖 Generated with Claude Code

…uest it would send

A tool that writes, called with `dry_run: true`, sends nothing and answers
`{"dry_run": true, "request": {method, url, body}}`: the object the command
prints under `--dry-run -o json`, with secrets masked by the same function
(#556). What the tool reads before its first write is read; the plan is of the
first write. `request` is null where the tool would write nothing. A plan that
would grant access says `grants_access: true`.

One place does it for all 260 tools, and no tool declares the argument: a
middleware of every ycli server takes `dry_run` out of the call and answers the
write the core's guard stopped; `client_provider`, the one place a tool's client
is built, builds it with that guard; a listing transform adds the argument to
every tool whose `readOnlyHint` is false and puts the plan beside the tool's own
answer in its output schema.

`dry_run` written inside an argument (in a body that takes any key, or spelled
`dryRun`, `dry-run`) is refused before anything is sent: one who nests it
believes they are planning. A plan is no error: nothing in the log says a tool
failed, and no traceback of the signal is written.

A tool that only reads has no `dry_run` and refuses it like any argument it does
not have. A tool that grants access prompts for a person on a dry run too: the
client decides from the tool's entry, before the server sees the arguments.

ARCH-3 states the rule. Held by: the contract check that for every write case the tool's plan is the
command's plan and neither sends a write; a check that every writing tool takes
its client from the one guarded place; tests that calls side by side do not take
each other's flag and that the flag is gone after a call that failed; a check
that a secret given to a tool is not in its plan, by its literal value.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch was previously deployed

1 inactive deployment
yandex-e2e — 8763566c Deployed Oct 10, 2026 by bim-ba via live (all) #714
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant