mcp-preflight

mcp-preflight is a utility that inspects an MCP server to reveal what capabilities, tools, resources, and prompts it exposes before you establish trust or run any tool. It runs the target MCP server in inspection mode locally and does not execute the server’s tools. This helps you understand the surface area a server offers, including available commands, endpoints, and action-level capabilities. You can point it at a server by passing a command string that would normally start the server, such as an npx or uv command, and it will return a structured summary, or save a JSON report for later diffs and audits. The tool also supports optional environment flags (for example, to authenticate to gated servers) and can isolate HOME to reduce side effects during inspection. Typical usage includes running the inspection against your own server, saving a JSON report, or diffing two reports to track changes over time. The output highlights the exposed MCP tools, the resources they publish, and intermediate prompts, along with a risk classification heuristic for actions like read-only, write, and destructive.

Prerequisites:

• Python 3.8+ (or a compatible Python environment)
• pipx (recommended) or pip

Install using pipx:

pipx install mcp-preflight

Alternatively, install as a Python package (not required if you use the CLI installed by pipx):

python -m pip install mcp-preflight

Basic usage after installation:

# Inspect a server by passing the command that starts it
mcp-preflight "npx @modelcontextprotocol/server-filesystem /tmp"

# Save a JSON report for later diffing
mcp-preflight --save report.json "uv run server.py"

# Diff two saved reports
mcp-preflight diff before.json after.json

# Output JSON only
mcp-preflight --json "uv run server.py"

Ensure you have Node.js, uv (Python), or other runtimes installed as required by the target server command.

Tips and caveats:

• The inspection runs the server locally but does not execute tools (no tool calls) to avoid side effects.
• If a server requires authentication to reveal capabilities, you can pass tokens via environment variables (for example, MCP_SERVER_TOKEN).
• You can isolate HOME to reduce pollution from the server’s filesystem dependencies using --isolate-home or redirect HOME with --home.
• If a server exposes a manifest or per-tool actions behind a tool, ensure you publish and surface those resources so preflight can surface and diff them.
• For authentication-gated servers, login flows are not executed by preflight; capabilities may appear after credentials are provided.
• If you’re comparing changes over time, save multiple JSON reports and use the diff feature to track evolution of capabilities.