New example: examples/servers/admission-gate — a real approve/deny ServerMiddleware demo

[fede-kamel]

Summary

Propose adding a new example server, examples/servers/admission-gate, demonstrating a real approve/deny use of ServerMiddleware — the SDK has this real, documented pre-execution veto point (runner.py's own comment calls it a "middleware veto") but no existing example actually denies anything. The one middleware example (stories/middleware) is audit-logging only; the SDK's only human-in-the-loop pattern (stories/refund_desk) uses elicitation for mid-call parameter confirmation, a different mechanism from a pre-call approve/deny gate on the whole tool call.

What it is

A filesystem server (read_file/write_file/delete_file) whose write_file/delete_file calls go through a middleware that queries an admission model with a written policy and the proposed action, and raises MCPError (the same mechanism handler errors already use) instead of calling call_next when the model says the policy requires denial.

The model backend is real tulip-agents code (tulip.models.native.openai.OpenAIModel, whose base_url override is documented for vLLM endpoints) — a dependency of this one example only, declared in its own pyproject.toml, not the rest of the workspace. Demoed against Clusiana, a real (unreleased) checkpoint trained for this exact three-way decision; any tulip-compatible chat model works the same way.

Verified

Real MCP client, real stdio transport, the server run as its own installed console script, the gate backed by a live model over a real network call — 4/4 correct on a representative probe, with the denied writes/deletes independently confirmed to have genuinely not touched the filesystem (not the tool's own claimed result). Full methodology: gist.

Scope

Doesn't touch src/mcp at all — new example directory only, own pyproject.toml, matches the existing examples/servers/* pattern (each with independent dependencies, e.g. simple-auth adds pydantic-settings).

Have a working, tested implementation ready — opening this first per CONTRIBUTING.md before submitting the PR.

[Ecocitizenz]

This would be a valuable example because it demonstrates that middleware can be a genuine pre-execution control rather than only an observation layer.

I would suggest making one architectural distinction explicit in the example: an admission model’s response is a policy input, not proof that the requested action is safe.

For state-changing tools, the useful pattern is:

1. identify the tool and capability being requested;
2. bind the decision to the proposed arguments or an args hash;
3. evaluate the request under a named/versioned policy;
4. return allow, deny or escalate;
5. enforce the result before call_next;
6. record the completed policy decision separately from the eventual tool outcome.

That distinction matters because an admission model can itself be unavailable, manipulated or changed. A production implementation should define deterministic behaviour for:

• timeout or backend failure;
• malformed or ambiguous decisions;
• policy-version changes;
• model/checkpoint changes;
• materially changed tool schemas;
• replay of an earlier approval against different arguments.

For write_file and delete_file, fail-closed or escalate-on-uncertainty would be safer than interpreting uncertainty as permission.

It would also be useful if the example emitted a minimal secret-redacted decision record containing:

request_id, tool_id, capability_class, args_hash, policy_version, decision, reason_code, issued_at

That would make the example useful not only as a middleware demonstration, but as a clean reference boundary between admission, enforcement and evidence.

The proposed example fills a real documentation gap. The middleware veto deserves a first-class, independently testable example.