Fail Safely, Never Hang
Guard against timeouts and unhandled exceptions.
Fail Safely, Never Hang is a free MCP Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MCP Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
A Hung Tool Is Worse Than a Failed One
A tool that errors clearly lets the model move on. A tool that hangs freezes the whole call, so always design for a timely exit.
Catch the Unexpected
Wrap risky work so a surprise exception becomes a clean error, not a crash. The server stays up and the model learns what failed.
try:
data = parse(raw)
except Exception as e:
raise ValueError("could not parse input")Always Set a Timeout
Any network or external call needs a timeout. Without one, a slow upstream can pin your tool open indefinitely and stall the client.
import httpx
r = httpx.get(url, timeout=10.0)Prefer Async for I/O
Async tools let one slow request wait without blocking everything else, so your server keeps serving other calls meanwhile.
@mcp.tool()
async def fetch(url: str) -> str:
async with httpx.AsyncClient() as c:
r = await c.get(url, timeout=10)Honor Cancellation
If the client cancels, stop promptly. Respecting cancellation frees resources and avoids work nobody is waiting for anymore.
Bound Loops and Retries
Cap any loop or retry. An unbounded retry on a failing API can spin forever, so set a max attempts and then give up gracefully.
for attempt in range(3):
if try_call():
breakRelease What You Open
Use with blocks or finally so files and connections always close, even when an error fires partway through the function.
with open(path) as f:
return f.read()Degrade Gracefully
When part of a job fails, return what you have with a note rather than nothing. A partial result still helps the model decide.
Log the Failure Server-Side
Record the full detail in your logs while sending the model only a safe summary. You get to debug without leaking internals.
One Crash Shouldn't End the Server
A single bad call must not take down the process. Isolating failures per tool keeps every other capability available to clients.
Always Return Something
Every path through your tool should end in a response, success or error. Silence leaves the client waiting and the model stuck.
Quick Check
What is the key reason to add a timeout to an external call in a tool?
Recap
Fail fast, never hang: catch surprises, set timeouts, bound retries, release resources, log safely, and always return a response. ✅
Frequently asked questions
Is the “Fail Safely, Never Hang” lesson free?
Yes — the full text of “Fail Safely, Never Hang” is free to read here on the web, and the MCP Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MCP Academy course, upgrade to CoddyKit PRO.
What will I learn in “Fail Safely, Never Hang”?
Guard against timeouts and unhandled exceptions. You practise MCP Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start MCP Academy?
No prior experience is required. MCP Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Fail Safely, Never Hang” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this MCP Academy lesson?
Yes. Every MCP Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Tool Errors the Model Can See
- Protocol Errors vs Tool Failures
- Validate Inputs Before Acting
- Fail Safely, Never Hang