legion-guard — verify before connect

An agent reads an MCP server's tool descriptions as instructions. The server you approved last week can expose other tools, or the same tools with other descriptions, today. legion-guard checks the tools/list your client actually receives, at connect time.

import legion_guard
session = legion_guard.wrap(session, "com.dexpaprika/dexpaprika")   # after session.initialize(); one line, no config file
tools = await session.list_tools()
print(session.report["verdict"])     # NO_CHANGE_DETECTED | CHANGE_DETECTED | UNVERIFIED

Any MCP client, no code: the stdio proxy

Claude Code, Cursor, Claude Desktop, Codex CLI, Gemini CLI: any client that launches a stdio server can run it through the guard. Replace the server command with:

python3 -m legion_guard proxy [--server-id io.example/server] [--mode warn|block] -- npx -y @scope/server --flag

or let it rewrite your config for review (it prints, it never writes):

python -m legion_guard wrap-config ~/.cursor/mcp.json > mcp.guarded.json

The proxy relays JSON-RPC unchanged and inspects every tools/list answer:

• tool fingerprints (name, description, inputSchema) against your first-use pin, the list seen at the start of the session, and, with --server-id, the list signed by the LEGION log;
• tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) against their first-seen values. Fingerprints do not cover annotations, but a client may rely on them to decide what runs without asking. A change toward less caution (read-only false→true, destructive true→false, open-world true→false) is reported as a change even when the fingerprint is identical.

warn (default) logs to stderr and ~/.cache/legion-guard/proxy-audit.jsonl and changes nothing. block removes changed, new or relaxed tools from tools/list and answers their tools/call with JSON-RPC error -32001 without reaching the server. Guard errors are logged and traffic passes unchanged. Tested end to end with the official MCP Python SDK client (tests/test_proxy.py); stdio only (HTTP servers are left untouched by wrap-config).

Try it in about a minute (including the virtualenv + install)

python3 -m venv v && . v/bin/activate && pip install legion-guard
python -m legion_guard check https://mcp.dexpaprika.com/streamable-http com.dexpaprika/dexpaprika

It connects to the public DexPaprika MCP server (initialize + tools/list, no tool call), fingerprints the 20 tools it receives and checks them against the latest list signed by the LEGION log. Look for "state": "MATCHES_SIGNED" (or DIFFERS_FROM_SIGNED, UNKNOWN, UNVERIFIED); exit code 0 = no difference, 1 = difference, 2 = connection error.

Low risk to add (tested)

• Observes by default. The default mode is warn: changes are logged (logging.getLogger("legion_guard")) and reported in session.report; no tool is hidden and no call is refused.
• Never breaks your app. If a source is unreachable or fails, it is reported UNAVAILABLE and nothing is blocked, in every mode. Internal errors of the guard are logged, never raised.
• Blocking is opt-in. wrap(session, server_id, mode="block") hides from list_tools() and refuses in call_tool() only the tools for which a source has evidence of a change (changed or new tool). UNKNOWN and UNAVAILABLE never block.

Removable: LEGION is the default, not a lock-in

Sources are pluggable. Each one compares the received list with its own reference:

session = legion_guard.wrap(session, "io.example/server", sources=[legion_guard.PinnedSource(".mcp-tools.lock.json")])  # no LEGION at all

Measured on 2026-10-17: the 20-tool list served by mcp.dexpaprika.com/streamable-http matches the list LEGION signed (MATCHES), also when the head must be a checkpoint cosigned by a chosen witness. There is no independent witness of the LEGION log yet: the only cosigning witness today is run by LEGION itself.

Limits

• LEGION observes only part of the servers; absence from the log is not a verdict (UNKNOWN).
• A change is not an attack. This does not certify that a server is secure, and says nothing about what the tools do.
• First-use pinning trusts the first list it sees.
• With witnesses=, the result is UNAVAILABLE (never blocking) until your witnesses have cosigned the log's current checkpoint. The only witness today is run by LEGION and cosigns hourly, so after each new head there is a window of up to about one hour where this option cannot confirm anything (measured on 2026-10-18).
• Fingerprints cover name, description and inputSchema (JCS RFC 8785), as in the LEGION log.
• Tested with the MCP Python SDK ClientSession; frameworks that build on it are not tested yet.

The 0.1 functions (guard_session, evaluate, approve, python3 -m legion_guard check|approve) are unchanged.

Release notes

• 0.2.6 (2026-10-24): python -m legion_guard proxy -- CMD runs any stdio MCP server through the guard, for any client that launches stdio servers; python -m legion_guard wrap-config FILE prints a config with its stdio servers wrapped (writes nothing). New signal: tool annotations compared with their first-seen values; a change toward less caution is reported (and blocked in block mode) even when the fingerprint is identical. Tested with the MCP Python SDK client (mcp 2.1.1, tests/test_proxy.py 17/17) and against @modelcontextprotocol/server-everything (13 annotated tools, identical tools/list with and without the proxy). The library API and the check/approve CLI are unchanged.
• 0.2.5 (2026-10-21): requires mcp>=1.24 (was mcp>=1.0). 1.24.0 is the first MCP Python SDK version with mcp.client.streamable_http.streamable_http_client, which the CLI uses. With 1.0–1.23.3 the package installed but python3 -m legion_guard check failed with an ImportError (measured on 2026-10-21; 0.2.1–0.2.4 declared mcp>=1.0). Tested on mcp 1.24.0, 1.30.0, 2.0.0, 2.1.1 and 2.3.0. The library itself does not import mcp. GHSA-84m7-p3x7-pcfv concerns MCP servers (fixed in 1.30.0 and 2.2.0); if the same environment also runs servers, use one of those versions. The test servers run on both the 1.x and the 2.x SDK.
• 0.2.4 (2026-10-21): the vendored mirror verifier accepts the checkpoint note signed under the log's origin name (C2SP) as well as the historical name, same key.