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 core preview rule, not a sidecar guidance check. The detector is narrow and field signal is already good, but the ecosystem still needs broader validation before the rule should be treated as fully mature.

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".