Stdio developer loop¶
This is the workflow mcpdev exists for: rebuild a local MCP server, inspect what it advertises, call a safe tool, snapshot the interface, and watch the next edit without restarting your AI harness.
The example server is the in-repo fixture at testdata/servers/stdio-lab, so the
whole loop runs from this checkout. No sibling repository and no personal
absolute path is involved.
Prerequisites: Go 1.27+ and this checkout. The HTTP half needs a Streamable HTTP fixture from Test fixtures.
Build the fixture¶
mkdir -p ./bin
go build -o ./bin/stdio-lab ./testdata/servers/stdio-lab
The binary serves the legacy-stdio catalog by default. Set MCPDEV_FIXTURE to
another catalog name to change the interface it advertises; this page uses
legacy-paginate to force a diff.
Point mcpdev at it with a profile¶
testdata/integration/mcpdev.toml ships an opt-in lab profile whose argv is
./bin/stdio-lab. Command and cwd values resolve from the process working
directory, so run mcpdev from the repository root.
export MCPDEV_CONFIG=$PWD/testdata/integration/mcpdev.toml
mcpdev --profile lab inspect
xdrun ci does not need that variable. go test ./internal/integration and
xdrun integration read the same file for the laboratory loop tests.
Inspect after a source edit¶
Each mcpdev command starts a fresh child process:
mcpdev --profile lab inspect
mcpdev --format json --profile lab inspect tools
mcpdev --profile lab inspect prompts
mcpdev --profile lab inspect resources
mcpdev --profile lab inspect templates
You should see tools echo and fail, prompt greet, resources
fixture://stable/note and fixture://stable/blob, and template
fixture://items/{id}. Incomplete collection is labeled (exit class 60); it is
never a silent empty catalog. Details are in Inspect a server
and Inventory.
Call, prompt, and read¶
Safe operations only. Do not pass server-returned strings to a shell.
mcpdev --format json --profile lab call echo --args '{"text":"loop"}'
mcpdev --profile lab prompt greet --arg name=mcpdev
mcpdev --profile lab read fixture://stable/note
mcpdev --profile lab read --template 'fixture://items/{id}' --arg id=n1
--arg values for prompts and URI templates are strings. call --args is a
JSON object. See Call, prompt, and read.
The same sequence as a declarative suite is
testdata/scenarios/valid/stdio.json. testdata/scenarios/valid/stdio-profile.yaml
is the same file format with a profile: target instead of an argv target:
mcpdev --command ./bin/stdio-lab test testdata/scenarios/valid/stdio.json
Snapshot, change the interface, diff¶
Capture a baseline from the default catalog, then compare it to the paginated
one. Exit class 40 means the public interface moved at or above --fail-on
(default additive).
mcpdev --profile lab snapshot --out /tmp/stdio-lab-baseline.json
mcpdev --format json --command ./bin/stdio-lab \
--env MCPDEV_FIXTURE=legacy-paginate diff /tmp/stdio-lab-baseline.json
The second command exits 40 because the paginated catalog advertises a
different tool set. Snapshots and diffs covers
--ignore, --rename, and the classification rules.
Watch rebuild, restart, reconnect¶
Watch is a foreground command. --rebuild is argv. Staging is renamed onto
--artifact only after a successful build; a compiler error keeps the last good
binary.
mcpdev --format json --command ./bin/stdio-lab watch \
--rebuild go --rebuild build --rebuild -o --rebuild ./bin/stdio-lab.partial \
--rebuild ./testdata/servers/stdio-lab \
--staging ./bin/stdio-lab.partial --artifact ./bin/stdio-lab \
--root ./testdata/servers --include '*.go' --debounce 200ms
Edit testdata/servers/stdio-lab/main.go. JSON Lines events on stdout include
fs, build, restart, negotiate, probe, and diff. Ctrl-C cancels
in-flight work and shuts the child down. You do not restart Cursor, Claude, or
another harness to see the new catalog. See Watch and rebuild.
HTTP: stateless modern era and redacted headers¶
Streamable HTTP for 2026-07-28 is POST-only. Put the bearer token in the
environment, not in the TOML file.
export MCPDEV_LAB_URL=http://127.0.0.1:8080/mcp
export MCPDEV_LAB_TOKEN="Bearer fixture-token"
mcpdev --format json --trace --trace-format json --profile http inspect tools
Inspect JSON and traces must show [REDACTED] in place of the token. Loopback
http is allowed; other insecure combinations stay opt-in. See
Streamable HTTP and Configuration.
Failure modes¶
| Symptom | What to check |
|---|---|
unknown profile lab |
MCPDEV_CONFIG does not point at testdata/integration/mcpdev.toml, and the current directory has no mcpdev.toml with that profile. |
Connect exit 10 |
./bin/stdio-lab is missing or failed to start. Rebuild it from the repository root. |
Diff exit 40 |
The public interface changed. That is the CI signal, not a crashed child. |
Diff exit 60 |
A catalog did not finish. Raise --timeout or reconnect before treating the run as clean. |
| Token visible in JSON | Stop. Headers must come from header_env or ${NAME:?}, never a literal in the file. |
Do not execute server-provided strings as shell commands. Do not commit secrets, machine home directories, or login names in integration assets.