FreshCtx: pre-action freshness protection for MCP tools at tools/call

[bhooshanvarma]

Pre-submission Checklist

• This post follows the MCP community guidelines

What would you like to share?

I built a pre-action freshness guard for consequential MCP tool calls.

The failure case is narrow: an agent can make a valid decision from current evidence, but that evidence can change before the MCP tool executes.

FreshCtx 0.9.0 adds protection at the native tools/call boundary. Immediately before a configured tool handler runs, FreshCtx revalidates the evidence declared for that action.

A reproducible scenario:

1. Agent observes available_balance = $10,000
2. Agent decides an $8,000 transfer is valid
3. Balance changes to $2,000
4. The MCP tool call begins
5. FreshCtx revalidates the declared balance dependency
6. Result: STALE_REASONING
7. The protected handler does not execute

The outcomes are explicit:

• CURRENT → protected handler proceeds
• STALE_REASONING → blocked before the handler
• UNVERIFIABLE → blocked because required evidence could not be confirmed

Multiple protected tools can have independent dependency sets, so stale evidence affecting one tool does not automatically block unrelated tools.

The main design challenge was keeping this boundary narrow. FreshCtx does not replace MCP authentication, authorization, transaction controls, idempotency, or tool-level safety.

It asks one additional question immediately before the protected action:

Is the evidence that justified this specific tool call still current?

I would especially value feedback from MCP server authors on whether tools/call is the right boundary for this check in real MCP architectures.

Relevant Links

GitHub:
https://github.com/Hyperwise-LLC/freshctx

MCP Guard documentation:
https://github.com/Hyperwise-LLC/freshctx/blob/main/docs/MCP_GUARD.md

Runnable three-outcome demo:
https://github.com/Hyperwise-LLC/freshctx/blob/main/examples/mcp_balance_guard.py

PyPI:
https://pypi.org/project/freshctx/0.9.0/

freshctx-mcp-stale-action-demo.mp4

[okgrit]

Your MCP_GUARD.md makes the useful distinction that an unprotected tool passes through while UNVERIFIABLE blocks a protected handler. One fixture I would be interested in comparing is a source that changes after the guard returns CURRENT but before the handler commits its effect. The expected outcome should depend on the application's transaction/version check, rather than the pre-action guard alone.

Would a shared three-case fixture be useful: changed declared dependency; unavailable declared dependency; and a change inside that final guard-to-commit window? The last case could explicitly document what the host must enforce.

Disclosure: I maintain done-is-a-claim, with Codex assisting this reply. Its local rechecker has a related but narrower boundary: selected evidence freshness, without executing or authorizing an action. I have read your guard contract, but have not run FreshCtx; this is a proposed comparison, not a bug claim or integration result.

[okgrit]

Following through with a bounded Windows reproduction of the public demo. I called run_demo for each scenario in mcp_balance_guard.py at 4ecc563, using a fresh venv and the package installed from that same commit's archive.

Environment: Windows, Python 3.12.14, FreshCtx 0.17.0, MCP SDK 2.3.0.

Scenario	MCP tool error	Observed state	Handler executions
current	false	CURRENT	1
stale	true	STALE_REASONING	0
unverifiable	true	UNVERIFIABLE	0

The unprotected status call also succeeded in each scenario. A local wrapper asserted the error/state/execution-count combinations and exited zero. The temporary runtime was removed afterward.

These are synthetic in-memory actions with the in-process SDK client: no real transfer, native model session or full integration suite. The guard-to-commit window raised in my original comment was not exercised by this run. No behavior change or bug claim is being inferred from it.

Codex performed the reproduction and prepared this follow-up on behalf of Grit-77. Sharing the result in case the Windows/SDK combination is useful; no action needed from you to reproduce the existing three cases.

[bhooshanvarma]

Thanks for running the Windows reproduction and sharing the versions and execution counts. It’s useful to see the three expected outcomes confirmed within the in-process demo’s scope.

I’d be happy to compare notes on a shared test showing what happens when data changes between the guard check and the action, with and without an application-level version check.

[okgrit]

Thanks — here is a concrete proposed contract for the shared test. Use an in-memory versioned record and an ordinary synthetic action, with an event/barrier inside the action handler after FreshCtx admission but before the write. A second task changes the record while that handler is paused; avoid timing-based sleeps.

Mutation after admission	Application version check	Expected committed actions
no	off	1
no	on	1
yes	off	1, based on the old decision
yes	on	0, application conflict

The application check needs to compare the expected version and commit atomically, under the same lock or compare-and-set operation. A separate version read followed by an unprotected write would introduce another window.

Record handler admission, commit count and application outcome separately. The final row should not invent a FreshCtx STALE_REASONING verdict after admission; it is an application conflict. Existing stale-before-admission coverage stays a separate control. These are proposed expectations, not newly executed results.

Would you prefer this as a separate example/test beside examples/mcp_balance_guard.py? I would keep it synthetic and dependency-compatible, with no change to guard semantics or production transaction claims.

Prepared with Codex on behalf of Grit-77.

[bhooshanvarma]

A separate example beside examples/mcp_balance_guard.py makes sense. The four cases and the event/barrier approach are a good fit. Please the version check and commit atomic, and distinguish an application conflict from FreshCtx’s STALE_REASONING result. A small PR to FreshCtx with the example and assertions would be a useful next step. Please keep it synthetic, with no changes to guard semantics.

[okgrit]

Thanks @bhooshanvarma — I opened the requested separate example as draft PR Hyperwise-LLC/freshctx#77 . It uses the real in-process MCP client/guard, an event after handler admission, and one lock for mutation plus atomic application comparison/commit. The four rows produce commits 1/1/1/0, with application_conflict kept separate from FreshCtx rejection.

The tests are in the existing MCP integration module so your current MCP CI selector includes them. That module passed 10 tests without skips on Windows and Linux with MCP2.3.0; the separate general test environment passed 215 tests with 11 skips. Exact commands and limits are in the PR.

Upstream CI is waiting for maintainer approval, and the draft also records an unresolved extra restrictive-sandbox run instead of presenting it as passed. Could you review whether the example layout and reported outcomes match the boundary you wanted? Guard semantics remain unchanged.

Prepared with Codex on behalf of Grit-77.