No portable way for a plugin's MCP server to receive the user's workspace root

[fixlyai]

v1 expands ${PLUGIN_ROOT}/${PLUGIN_DATA} and recommends the plugin root as the default subprocess cwd. A server whose tools operate on the user's project — writing project files, keeping project-scoped state — has no portable way to learn that path, so any such server either requires per-call absolute paths or silently writes into the plugin directory.

Concrete case: reelier serve --workspace <path> exists precisely for this, and no conformant manifest can populate it.

Proposal: an optional client-supplied ${WORKSPACE_ROOT} expansion variable (defined as "the directory the user's session is rooted in, if the client has one"), with absence meaning the client provides no workspace notion.

[bobleer]

Strong +1 on the need, but I'd push on the definition, because "the directory the user's session is rooted in" stops being well-defined as soon as a client supports remote workspaces — and that's the case where a project-scoped MCP server needs it most.

We implement workspaces that can live on a remote SSH host or inside a Docker container, local or remote. In all of those, the session's workspace root is a path on the target, not on the machine where a stdio MCP server spawned from the plugin would run. Expanding ${WORKSPACE_ROOT} to that path and handing it to a locally-launched subprocess yields a path that exists nowhere on the subprocess's filesystem — which is worse than absent, because it looks valid and fails late, inside the plugin's own error handling rather than at load time.

Two amendments that I think would make the variable safe to adopt:

1. Scope it to same-filesystem cases. Say explicitly that ${WORKSPACE_ROOT} is expanded only when the workspace shares a filesystem with the spawned server, and is treated as absent otherwise. Clients with remote workspaces then degrade to the "client provides no workspace notion" branch the proposal already defines, rather than emitting a path that is confidently wrong. Without this, every client with remote execution has to choose between non-conformance and handing plugins bad data, and different clients will choose differently.

2. Pin the path semantics. We normalize workspace paths to POSIX separators regardless of client OS, precisely because the target's conventions and the client's don't have to match. If the spec doesn't state whose separator convention wins, a plugin author testing on macOS against a local workspace will ship something that breaks on a Windows client, and it will present as a plugin bug rather than as an ambiguity in the spec.

Separately: for the streamable-http and sse transports the question changes shape entirely — the server isn't a subprocess and may share no filesystem with anyone involved. It may be cleaner to define the variable as stdio-only in v1 than to leave each client to decide what it means for a remote server.

[DontFretBrett]

+1 on the need, and I think bobleer's two amendments are the same problem surfacing twice. Worth naming it directly, because it's going to keep producing amendments one at a time.

The spec never says whose filesystem it means.

Every load-bearing requirement here is expressed in filesystem terms — PLUGIN_ROOT and PLUGIN_DATA in §9.1, the containment rules in §4.1, cwd resolution and plugin-relative command in §7.2.1 — and none of them names a host. §9.1 says "clients that launch plugin subprocesses," which quietly attributes the launch to the client and assumes the client and the subprocess share one filesystem. Remote workspaces are one place that assumption breaks; they aren't the only one.

We're building on the other side of that gap. J5 Agent Fleet is an agent orchestration platform: the control plane is hosted, and tasks execute on runners that are separate machines — a Mac Studio on someone's desk, or a container. For us the client and any plugin subprocess are never on the same host. That isn't an edge case in our design, it's the design.

A case I don't think has come up: there can be more than one root.

A runner can be configured with multiple workspace roots — we cap it at 32 — and a single task can legitimately span several. A scalar ${WORKSPACE_ROOT} gives a client like ours two options: pick one root arbitrarily, or don't conform. Different clients will pick differently, and a plugin author has no way to tell which they got — which is the interop failure the variable is meant to prevent.

Suggested shape

Define the execution context once, in §3, then state the variable in terms of it. Something like "plugin host — the execution context whose filesystem package paths, PLUGIN_ROOT, PLUGIN_DATA, and cwd resolve against. A client need not run on the plugin host."

Then this issue reduces to one predicate instead of three carve-outs:

${WORKSPACE_ROOT} expands only when the client has exactly one workspace root on the plugin host's filesystem. Otherwise it is absent.

That covers bobleer's remote-workspace case, the multi-root case above, and — since a streamable-http or sse server has no plugin host the client controls — the transport question he raised at the end, without needing a stdio-only rule. Absence stays the well-defined branch this proposal already has, and clients degrade deterministically instead of each inventing a different confidently-wrong path.

No new fields or schema changes; it's a terminology row and a sentence.

On timing: §10.1 makes published canonical schema identifiers immutable, so whichever semantics ship with this variable are the ones we're stuck with until the next version. Absence semantics seem worth settling before it lands rather than after.

For disclosure — we haven't implemented Agent Plugins yet; this is from reading 1.0.0 against an architecture where the split host is unavoidable. Happy to be told the single-host reading is intended and this belongs in client extensions instead.

[fixlyai]

The plugin host framing is better than what I opened with, and I am adopting it. It covers both of bobleer's amendments. Three things to add. Two of them make the change smaller.

The transport carve-out is not needed. v1 already says clients "MUST NOT perform placeholder or environment-variable expansion in url, header names, or header values", and defines expansion over "the args, env, and cwd fields in a stdio server configuration". A streamable-http or sse entry has no field that expands. A stdio-only rule for ${WORKSPACE_ROOT} would restate something v1 already does.

The separator question answers itself once the predicate is in place. If the variable only expands when the root is on the plugin host's filesystem, the value has to be in that host's native form. The subprocess passes it straight to its own filesystem calls. A POSIX-normalized C:/... handed to a Windows plugin host is just a different wrong path. Normalization is what you need when the path might belong to some other host, and the predicate removes that case. So bobleer's second amendment falls out of the first instead of being its own rule.

§3 is where the confusion starts. It defines a Client as "a tool that discovers, installs, loads, and executes plugin components". That is four jobs assigned to one actor. Separating the last one is the entire change.

One correction, and it cuts against my own argument for urgency. §10.1 covers published canonical schema identifiers. Expansion semantics are prose, not part of mcp.schema.json, so that rule does not actually bind this. The timing point still holds, but for a different reason: clients will implement whatever ships, and their behavior is what gets locked in.

The absent branch works for us, and I would take it over a guess. A wrong but plausible workspace path would make a tool write project state into a plugin directory. That is worse for us than the tool not running at all. If ${WORKSPACE_ROOT} is absent, we ship no mcp.json in the portable package and use host-specific packaging where a host supplies a path. So this is not blocking us. I would rather the semantics be right than early.

Maintainers: is the single-host reading of §9.1 and §4.1 intended? If it is, this is a terminology row plus one predicate. If it is not, this issue is one symptom of something larger.