Debug calling a tool not in the discovered list in the MCP stdio client

Do not start with a speculative fix for the MCP stdio client. Force the failure on purpose, save the before output, then change one cause at a time. Retries are allowed only for transient conditions—not for bad input that will fail forever on mcp-in-code.

for (let attempt = 0; attempt <= maxRetries; attempt++) {
  try { return await operation(signal); }
  catch (error) {
    const failure = classify(error);
    if (!failure.retryable || attempt === maxRetries) throw failure;
    await sleep(jitteredBackoff(attempt), signal);
  }
}
throw new Error("unreachable");

Expected evidence: The client discovers echo, calls it once, prints “hello”, and closes the transport.. If you cannot reproduce on demand, you do not yet control the failure mode for mcp-in-code.

After repair, rerun the exact reproduction command. Keep the failing fixture as a regression seed for the observability page. For the MCP stdio client calling one local tool, remember the claim you are restoring: discovered tool schemas are printed; only named tool executes with validated args.

Store a one-command reproduction for: calling a tool not in the discovered list, or hanging on stderr noise. The command should use local stdio server exposing one read-only echo tool or a minimal mutant of it. Paste the failing output into notes/failure-before.txt (or your shell scrollback as copied text). After the fix, paste notes/failure-after.txt and keep both.

Retries belong only on transient faults. If the failure is bad input, a bad allowlist, or a logic bug in the MCP stdio client, retrying will amplify cost without repairing trust around connect to a local MCP server, list tools, and invoke one allowlisted tool safely.

Classify the failure as prevent, detect, contain, or recover—using this lab’s language, not a generic poster. For mcp-in-code, the first fix should usually be detect+prevent at the boundary, because calling a tool not in the discovered list, or hanging on stderr noise is cheaper to stop early than to explain in production prose.

At the debugging stage for mcp-in-code, the job is narrower than finishing a product demo. You are creating one progressive evidence piece about local stdio server exposing one read-only echo tool that later pages inherit without redefining success. Keep that fixture small enough to inspect by hand, keep outputs copy-pasteable as text, and refuse to narrate this baseline as if it were a production SLA: direct function call without MCP discovery.

For this page specifically, success looks like before/after evidence for the characteristic failure while still centering the user decision to connect to a local MCP server, list tools, and invoke one allowlisted tool safely. If you cannot point to a file, command, or assertion that proves that for the MCP stdio client, stay on this page instead of advancing.

Glossary: tool · Glossary: structured output · Cheatsheet: production ops signals

Previous · Next