CLI reference for assessors¶

This is the operator reference for the current mcp-fuzzer command. It focuses on flags that affect scope, inputs, authentication, safety, evidence, and reproduction. For a task-based walkthrough, start with Run a first assessment.

Syntax¶

mcp-fuzzer [OPTIONS] --mode MODE --protocol TRANSPORT --endpoint TARGET

--endpoint is required for a real run. It is a URL for HTTP/SSE/Streamable HTTP and a command string for stdio.

Assessment selection¶

Use audit recipes to separate baseline, aggressive, protocol, auth, and runtime evidence.

Transport and protocol¶

The retry delay curve (transport_retry_delay, transport_retry_backoff, transport_retry_max_delay, transport_retry_jitter) is set in a config file rather than on the command line; see configuration.

Generic http/https resolution depends on the selected MCP schema path. Use streamablehttp when the target explicitly exposes that transport and record the negotiated version in the assessment.

Spec and deterministic checks¶

Supported protocol type names are listed in configuration and sourced from the runtime registry. Result schemas are validated by spec guard but are not --protocol-type values.

Security and authentication audits¶

--security-audit can produce signals for tool/schema poisoning, hidden or encoded instructions, ANSI/control content, trigger-conditioned metadata, duplicate or drifting definitions, dangerous local-read/network-egress combinations, cleartext remote transport, and evidence-backed command/path/SQL or output-injection behavior. It also flags names that closely imitate common tool names.

--security-audit-intrusive adds a foreign-Origin HTTP/SSE request. Legacy SSE revisions are probed with GET; 2026-07-28 removed the GET stream endpoint, so stateless revisions are probed with a server/discover POST. Configured transport authentication is replayed so a server that authenticates before it evaluates Origin still reaches the check.

Only a successful (2xx) response is reported as missing_origin_validation. Same-host redirects are followed first, because /mcp → /mcp/ and HTTP → HTTPS canonicalization can precede the Origin check; a redirect is never itself treated as acceptance. HTTP 403 is the spec-mandated rejection, HTTP 401 is reported as origin_validation_inconclusive, and unrelated protocol or routing errors produce no finding. Every revision requires Origin validation, but only 2025-11-25 and later mandate HTTP 403, so the finding text is scoped to the negotiated revision. Use this only against a target and network boundary covered by the engagement.

--auth-audit is read-only by default. The intrusive variant may create OAuth registration state and exercise redirect handling; keep it separate from a baseline and never use it against production without written authorization.

Authentication options¶

Authentication provider examples and secret-handling guidance live in configuration.

Safety and host boundaries¶

These are controls for the assessment client, not a complete OS sandbox. Use a container or VM for untrusted local code. See contain the target.

Runtime observation for stdio¶

The probe is opt-in, applies to local stdio process behavior, and fails open if it cannot observe an event. It does not monitor remote transports.

Output and diagnostics¶

Read Interpret evidence and findings before processing artifact contents. Reports can contain target data and secrets.

Process controls¶

Tune these only after a baseline. High concurrency and retries can change the target's behavior and make evidence harder to interpret.

Common command patterns¶

# Validate a target profile without connecting
mcp-fuzzer --validate-config assessment.yaml

# Baseline with reproducible payload generation
mcp-fuzzer --config assessment.yaml --phase realistic --seed 42 \
  --output-dir reports/baseline

# Focus one tool with aggressive inputs
mcp-fuzzer --mode tools --tool NAME --phase aggressive \
  --protocol streamablehttp --endpoint https://target.example/mcp \
  --security-audit --runs 20 --seed 42 --output-dir reports/tool-NAME

# CI target usability check
mcp-fuzzer --mode all --protocol streamablehttp \
  --endpoint http://127.0.0.1:8000/mcp --security-audit \
  --fail-if-no-tools --output-dir reports/ci

For config precedence, environment variables, protocol type values, and authentication provider JSON, use configuration.