Why It Matters

SEC347 flags AI-native documentation that teaches MCP setup through mutable package runners such as npx, uvx, pnpm dlx, yarn dlx, or pipx run.

These examples are convenient, but they are weak as shared onboarding guidance:

• they are less reproducible than checked-in wrappers or pinned install flows
• they normalize latest-style package execution in copy-paste setup docs
• they make it harder for reviewers to tell whether the recommended path is intentionally trusted or just convenient

Positioning

This is a deeper-review preview rule, not part of the quiet recommended default. The detector is narrow and field signal is already good, but markdown setup guidance is still a noisier surface than committed executable config, so the rule stays in preview and skills while broader validation continues.

Treat it as supply-chain hardening guidance about mutability and reviewability, not as proof that the documented package or server is malicious.

What Triggers

SEC347 applies only to AI-native markdown surfaces:

• SKILL.md
• CLAUDE.md, AGENTS.md, *.instructions.md, *.agent.md
• .mdc, .cursorrules
• plugin agent / plugin command markdown

It has two narrow trigger shapes.

CLI form

Same line contains:

• claude mcp add
• and a mutable launcher token like npx or uvx

Example that triggers:

claude mcp add exa -- npx -y mcp-remote "https://mcp.exa.ai/mcp"

Config-snippet form

The same markdown region contains:

• MCP context such as mcpServers or MCP server
• a launcher command marker such as "command": "npx" or command: pipx
• nearby mutable-launch semantics in args, such as package args, dlx, or run

Example that triggers:

{
  "mcpServers": {
    "olostep": {
      "command": "npx",
      "args": ["-y", "olostep-mcp"]
    }
  }
}

Examples that stay clean:

• bare command: npx without nearby package args
• generic npx lighthouse
• safety guidance like Do not use "command": "npx" for MCP examples

False Positives

This rule stays Preview because setup docs are not the same as committed executable config. A project may intentionally document a mutable launcher for convenience, especially in quick-start guides.

To reduce noise, SEC347 suppresses findings near safety wording such as:

• do not use
• don't use
• avoid
• replace with
• instead of

Remediation

Prefer one of these fixes:

1. replace the example with a checked-in wrapper or local script
2. rewrite the docs around a pinned or reproducible install flow
3. keep the risky example only as an explicitly discouraged pattern

Good replacement pattern:

Use the checked-in wrapper at `./scripts/mcp-exa.sh` instead of launching through `npx`.

Community intent for this rule is guidance, not blame: the finding means "this doc teaches a mutable MCP setup path", not "the package is malicious".