Pre-1.0, actively developed.

• Validation engine, autopatch, and CLI (check/launch/rules) are implemented and covered by an automated test suite that runs against the real binaries installed on the test machine (python, node, npx) -- not mocks -- including a genuine end-to-end MCP handshake through a real spawned server fixture, and a genuine subprocess-level test of launch.
• Not yet on PyPI -- see Install.
• See SECURITY.md for exactly what is and is not covered.

Scope

In scope: validating a stdio MCP server launch (command + args + env) before it reaches the OS process-spawn layer, specifically to close the command/argument-injection path described in SECURITY.md.

Explicitly out of scope: scanning a server's declared tools for risky capabilities (that's a different problem -- see AgentGuard), sandboxing the spawned process, and non-stdio (SSE/HTTP) MCP transports.

Install

Verify it worked:

Getting started

Option A: the autopatch (Python MCP hosts)

If your app is written in Python and builds StdioServerParameters / calls mcp.client.stdio.stdio_client itself, add one import at the very top of your entrypoint -- before anything else imports mcp.client.stdio:

An unsafe launch now raises mcpshield.core.errors.UnsafeConfigurationError (a ValueError subclass) instead of ever spawning a process.

Option B: static check (any language, zero execution)

Audit an mcpServers-style config file without running anything:

Exits non-zero if anything is BLOCKED (add --strict to also fail on WARN) -- drop it straight into CI.

Option C: launch supervisor (non-Python hosts)

For an MCP client (Node, Java, Rust, ...) that can't use the Python autopatch, point its config at mcpshield instead of the real command:

launch validates, then executes the real command with the same stdio your MCP client expects (transparent passthrough) -- or refuses with a clear error if the launch is unsafe.

What gets blocked vs. what gets a warning

Native binaries get looser argument checks because they exec directly -- there's no shell to re-parse the argument list. Shell-interpretable commands (most commonly npx.cmd/npx.bat on Windows) get strict checks because that's the exact mechanism the underlying CVE exploits.

The escape hatches

Both are deliberate, per-value opt-ins -- never a blanket "disable checks" flag:

• allow_raw_args=["--some-value-with-a-pipe"] (library) exempts specific argument values you've reviewed and trust.
• allow_env=["SOME_VAR"] permits a normally-stripped environment variable to pass through unmodified.

CLI reference

Known limitations

• Not yet on PyPI -- install requires git clone.
• The autopatch only patches mcp.client.stdio.stdio_client as looked up at patch time. Code that already holds its own reference (via from mcp.client.stdio import stdio_client executed before import mcpshield.autopatch) will bypass it -- import mcpshield.autopatch first, always.
• The shell-metacharacter check is deny-list based, applied only when the resolved command is detected as shell-interpretable. It is not a full shell-grammar parser -- see SECURITY.md for the exact scope boundary.
• check resolves commands using the machine it runs on. A config that would resolve differently on the machine it's actually deployed to (a different PATH, different installed tools) may report differently there.

Project layout

Development

The test suite validates against the real python/node/npx binaries installed on the machine it runs on (resolved the same way the engine itself resolves them), and includes a genuine end-to-end MCP handshake through a real spawned server fixture -- not mocks.