Blog
MCP Tool Errors During Developer Onboarding
An MCP server that fails on stdio looks like a hung editor. Print a one-line error on stderr, exit non-zero, and do not prompt. Editors are not a TTY conversation.
2026-09-24 · 7 min read · AethelLayer
Stdio is the protocol, stderr is the diagnosis
MCP over stdio uses stdin and stdout for JSON-RPC. Logs and errors belong on stderr. A log line on stdout breaks the session, and the developer sees a spinner.
If the process cannot start, exit non-zero with a stable code. A server that sits forever waiting for a config file looks identical to a working server that has not received a call.
Do not prompt
There is no person on that pipe. A question such as 'what were you trying to do?' will deadlock the editor. Record the probe silently. Ask that question only in a real terminal CLI.
Missing keys should name the variable and the config file the host app reads. 'Initialization failed' is not enough.
Tool errors need codes too
A tool that returns a paragraph will be copied into a chat. A tool that returns a code, a message, and a suggestion can be searched. Keep stacks out of the tool result the model will quote, and keep them in the probe.
Redact tokens before either path. Tool arguments are full of keys.
The editor log is not your inbox
Developers will not paste an MCP log into GitHub. Capture the start failure and the tool error code yourself. Draft the issue when the same code shows up across machines.
A green API does not mean the MCP install path works. Test the documented config on a clean machine.
Keep reading
Capture the failure before they leave
Capture the failure before they leave. Book early access or talk to sales, then install @aethellayer/sdk when you are onboarded.