Skip to content

docs(unstable-v2): require an absolute command for stdio MCP servers - #2878

Open
benbrandt wants to merge 1 commit into
mainfrom
docs/v2-mcp-stdio-absolute-command
Open

benbrandt wants to merge 1 commit into
mainfrom
docs/v2-mcp-stdio-absolute-command

Conversation

@benbrandt

Copy link
Copy Markdown
Member

Summary

The stdio MCP server command was described as "the absolute path to the MCP server executable", with no requirement and no error. cwd and additionalDirectories both have an explicit absolute-path rule with -32602.

Without a rule, one Agent can resolve a bare npx through its PATH while another rejects it. The Agent runs this value, so a name resolved on the Agent's machine can start a different binary than the Client meant.

Changes

  • Session setup: command MUST be an absolute path, and Agents reject a request with a relative command with -32602. The wording matches the cwd rule. Changed in the stable page and its draft/ copy.
  • Schema description: the command field of McpServerStdio states the same rule. This regenerates schema/v2/schema.json, schema/v2/schema.unstable.json and both schema.mdx pages. Only the description text changes.
  • Migration guide: one new bullet under "MCP server configuration", and a few words in the Agent and Client checklists. v1 described the field as an absolute path but did not require it.

Implementations

Checked on 2026-11-18 against the default branch of each repository.

  • Zed already refuses to send a relative command on v2 connections.
  • claude-agent-acp and codex-acp check that cwd is absolute but pass command through unchecked. Each needs a small follow-up to reject a relative one.

v1 is unchanged.

Checks

  • cargo clippy in the three configurations from npm run check, cargo test --all-features, and rustdoc with -D warnings pass.
  • Regenerating the schema a second time produces no diff.
  • Prettier, cargo fmt, the spellcheck script, and the link check pass.

The stdio `command` was described as "the absolute path to the MCP
server executable" with no requirement and no error, unlike `cwd` and
`additionalDirectories`. One Agent could resolve a bare `npx` through
its `PATH` while another rejected it.

- Say that `command` MUST be an absolute path and that Agents reject a
  relative one with `-32602`, in the same words as the `cwd` rule.
- State the rule in the `McpServerStdio` schema description.
- Add it to the MCP section and both checklists of the migration guide.
@benbrandt
benbrandt requested a review from a team as a code owner November 18, 2026 15:53

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant