Stdio servers¶
mcpdev launches a new MCP child for every invocation (and every watch restart). It does not keep a hidden daemon around, and it never feeds the argv through a shell. Protocol bytes stay on the child's stdin/stdout. Logs stay on stderr.
The operator flags, stream rules, and exit classes are in CLI. Failure records and redaction are in Diagnostics.
Argv, not a shell string¶
--command / -c is repeatable. Each value is one argv slot. Paths with spaces are one slot; they are not split. On Windows the child path should include .exe when you pass a built file (the same suffix go build -o writes).
A local binary:
mcpdev inspect --command ./bin/weather
go run without wrapping it in sh -c:
mcpdev inspect --command go --command run --command ./cmd/weather
A wrapper script (still exec of that path, not bash -c "..."):
mcpdev inspect --command ./scripts/run-weather.sh
You can also put the argv after --:
mcpdev inspect -- ./bin/weather --flag
Profiles use the same argv shape in mcpdev.toml (see Configuration):
[profiles.local]
command = ["go", "run", "."]
command = "go run ." is invalid. mcpdev will not parse a shell string from config, from the environment, or from server output.
Environment and working directory¶
--env KEY=VALUE is repeatable and overlays the parent environment. --cwd sets the child's working directory (absolute or relative to mcpdev's cwd).
mcpdev inspect \
--command ./bin/weather \
--cwd ./services/weather \
--env API_URL=http://127.0.0.1:8080
Overrides win over inherited keys. The merged environment is applied as a sorted KEY=VALUE list so two launches with the same spec are deterministic. Child env values that look like credentials are redacted in diagnostics.
Fresh binary every time¶
Each inspect / call / watch reconnect starts exec again with the argv you passed. Rebuild the server, then run mcpdev again (or let watch --rebuild do it). You do not restart mcpdev to pick up ./bin/weather.
Watch still tears the previous child down (stdin close, then interrupt, then kill) before starting the next argv.
Streams¶
| Child stream | Role |
|---|---|
| stdin | JSON-RPC from mcpdev |
| stdout | JSON-RPC to mcpdev |
| stderr | Untrusted diagnostics, copied with a byte bound |
Do not log on stdout. A first stdout byte that is not JSON ({ or [) is a protocol error (exit class 20). An early exit with no JSON-RPC is a connection error (exit class 10). Bytes on stderr never become protocol_error by themselves, even if they look like JSON-RPC.
Shutdown¶
On cancel, timeout, or the end of a command, mcpdev:
- Closes the child's stdin (graceful MCP servers exit).
- Waits a short grace period.
- Interrupts the process group.
- Waits again, then kills the group if it is still running.
Cancellation and timeout tests must leave no child process. If shutdown blocks, mcpdev still kills; the error is connection-class, not success.
Failure modes¶
| Symptom | Typical class | What to check |
|---|---|---|
| Binary missing or not executable | 10 connection |
argv[0], --cwd, file mode |
| Child exits before handshake | 10 connection |
bounded child_stderr |
| Garbage on stdout | 20 protocol |
server logs should move to stderr |
| Child ignores interrupt | connection after kill | wrapper that reaps children; mcpdev kills the process group |
Report failures with the redacted diagnostic, not a raw env dump. See Diagnostics.