docs: quickstart filesystem config should document that argless form delegates scope to client roots #4423

Finding

When @modelcontextprotocol/server-filesystem is launched without path arguments, as in the quickstart .mcp.json example, it does not default to broad filesystem access. I verified this in v2026.1.14:

• path-validation.js lines 16-18: returns false for all paths when allowedDirectories is empty (fail-closed)
• index.js lines 563-585: the server starts, requests roots from the MCP client via the roots protocol, and throws on init if neither CLI args nor client roots are provided

The fail-closed behavior is correct and intentional. This is not a security bug report.

The legibility gap

The quickstart ships this config:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

This config is not self-contained: the actual filesystem access boundary is invisible at config-review time. The scope is whatever roots the MCP client sends at runtime, which varies by client (Claude Desktop, Cursor, VS Code, etc.) and is not recorded in the committed file.

In practice: people copy this from the quickstart, commit it, and an auditor reviewing the repository cannot determine what filesystem paths the agent can actually access. Two different clients connecting to the same config get different scopes. Neither is visible in the file.

The ask

No behavior change needed. Two small documentation additions would close the gap:

1. Show an explicit path arg in the quickstart example:

"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"]

2. Add a note that the argless form is valid but delegates scope to client roots at runtime, so the access boundary is client-determined rather than config-defined. Developers who want an auditable, self-contained config should use explicit path args.

Happy to open a PR for the docs change if that is easier.