--sandbox inherit fails under Claude Code (and likely other generic MCP clients) due to missing metadata

Summary

--sandbox inherit fails on every repl tool call when the MCP client is Claude Code (and likely other generic MCP clients), because those clients don't send Posit-specific sandbox metadata in their tool-call requests. The server appears to require that metadata when inherit is set, with no fallback to a default mode, so every call errors out before the Python interpreter even runs the user's code.

Repro

~/.codex-style config or .mcp.json with:

{
  "mcpServers": {
    "py-repl": {
      "command": "uvx",
      "args": ["--from", "posit-mcp-repl==0.2.0", "mcp-repl", "--interpreter", "python", "--sandbox", "inherit"]
    }
  }
}

In Claude Code: load the plugin, call any repl(input="...") from the agent. Every call returns a "sandbox-state error" before executing the input. Switching to --sandbox workspace-write (or any other concrete mode) makes the same calls succeed.

What the docs say

The CLI help says:

--sandbox: base sandbox mode (inherit uses client tool-call metadata; --debug-repl bootstraps local defaults)

That implies inherit reads sandbox metadata from each MCP tool-call. The MCP protocol has a _meta field on requests, but it's by convention server-private and most clients (Claude Code, Cursor, Windsurf, Cline, GitHub Copilot in VS Code) don't populate it with anything beyond standard MCP plumbing. There's no documented expectation that those clients would supply Posit-specific sandbox metadata, and no Claude Code-side configuration that would let a user populate it.

Impact

The MCP plugin ecosystem is dominated by Claude Code right now, with Codex and Cursor catching up — these are the agents most users will run posit-mcp-repl from. If inherit only works under Codex (or any other client that happens to send the right metadata), the help text is misleading and the failure mode is opaque to users. We hit this in a plugin (https://github.com/meridianlabs-ai/inspect-skills) and had to switch to a hardcoded --sandbox workspace-write to get past it.

Suggested fixes (in increasing scope)

1. Document the precondition. Add to the --sandbox inherit help: "Only works with MCP clients that send Posit-specific sandbox metadata (e.g. Codex). For Claude Code / Cursor / Windsurf / Cline, pick a concrete mode like workspace-write." Cheapest.

2. Fall back gracefully. When inherit is set but no metadata is supplied, default to workspace-write (or whatever is sensible) and emit a one-time warning to stderr. Backward-compatible.

3. Make inherit aware of common client identifiers. Check the MCP clientInfo.name (sent during initialization) and pick a sensible mode per known client. Bigger lift.

(1) at minimum would have saved us hours of debugging. (2) would make inherit actually a sane default.

Environment

• posit-mcp-repl==0.2.0 (PyPI)
• Launched via uvx --from posit-mcp-repl==0.2.0 mcp-repl --interpreter python --sandbox inherit
• Client: Claude Code v2.1.195

Start at the --sandbox inherit handling and the MCP tool-call metadata path; reproduce the failure with the provided .mcp.json/uvx command and a Claude Code repl call. Confirm the missing-metadata error occurs before Python execution, then review the --sandbox help text. Done means the selected fallback or documentation accurately handles clients without Posit-specific metadata.