Issue: `UnboundLocalError` in `call_tool` on Client Disconnect — Due to Uninitialized Variable

[TBice123123]

🔁 Reproduction Steps

1. Set up an MCP server using StreamableHTTP transport.
2. Trigger a tool call that takes noticeable time to execute (e.g., >3–5 seconds — for ease of reproduction).
3. From the frontend, initiate the request via fetch with SSE (e.g., in a browser).
4. While the tool is still executing, cancel the request — by closing the tab, clicking “Stop”, or programmatically aborting the fetch.
5. Observe the backend logs — you’ll see:

UnboundLocalError: cannot access local variable 'call_tool_result' where it is not associated with a value

💡 Note: The tool doesn’t need to be slow — this can happen with any tool if the client disconnects before the result is assigned. Long-running tools just make it easier to trigger.

---

⚠️ Problem & Root Cause

The crash occurs in code like this:

async def call_tool(...):
    if session is None:
        ...
        call_tool_result = await session.call_tool(...)  # ← May be skipped if exception 
    return _convert_call_tool_result(call_tool_result)   # ← CRASH: variable not bound

• call_tool_result is never initialized at the function scope — it’s only assigned inside the else block.
• When the client disconnects:
  • The underlying read_stream closes.
  • session.call_tool(...) may raise an exception (e.g., anyio.EndOfStream, BrokenResourceError) — but due to async task group behavior, the exception may not propagate synchronously.
  • As a result, the assignment to call_tool_result is skipped entirely.
• When the code reaches return _convert_call_tool_result(call_tool_result), Python throws UnboundLocalError — because the variable was never bound in this scope.

This is not a race condition — it’s a logic error in variable binding and error handling.

---

🚨 Impact

• Causes unhandled 500 errors or process crashes in production.
• Breaks user experience — instead of “Request cancelled”, users see generic failures or timeouts.
• Makes the system fragile under real-world conditions: network drops, impatient users, mobile clients, etc.
• Violates “fail gracefully” principle — should return an error message, not crash.

---

✅ Proposed Solution

To fix this with minimal, safe, and production-ready changes:

1. Initialize call_tool_result to None at the start of the function:

async def call_tool(...):
    call_tool_result = None  # ← Prevents UnboundLocalError

    if session is None:
        ...
    else:
        call_tool_result = await session.call_tool(...)

    return _convert_call_tool_result(call_tool_result)

→ Guarantees the variable is always bound — no more crashes.

2. Update _convert_call_tool_result to handle None:

def _convert_call_tool_result(result: CallToolResult | None) -> tuple[str | list[str], list[NonTextContent] | None]:
    if result is None:
        return "❌ Tool call failed: connection closed or no response received", None
    # ... existing logic

→ Now, LangChain Agents/Chains receive a meaningful error string instead of crashing. They can log it, show it to users, or retry.

---

[eyurtsev]

Thanks for sending the issue -- any chance you'd be willing to create a unit test for it that recreates the unbound local error issue? Another user encountered this same problem!

As far as the solution, I don't want to return a fake tool message with an explanation about what went wrong since we don't know what went wrong. The mcp sdk that this library is using under the hood is swallowing the exception.

[eyurtsev]

@TBice123123 for your reproduction -- where are you using langchain-mcp-adapters? It looks like like you're talking to an MCP backend directly from a FE? is langchain-mcp-adapters even used?

[TBice123123]

@TBice123123 for your reproduction -- where are you using langchain-mcp-adapters? It looks like like you're talking to an MCP backend directly from a FE? is langchain-mcp-adapters even used?

Thank you for taking the time to review my issue!

To clarify upfront: I am not using the LangGraph framework to build my agent, so I’m unsure whether LangGraph Server would handle this type of exception. My implementation is based on LangChain with a manual while-loop tool-calling workflow, exposed via FastAPI to deliver SSE (Server-Sent Events) streaming responses to the frontend.

Initially, I used Microsoft’s fetch-sse library to consume the SSE stream, and occasionally encountered an “unbound variable” error originating from langchain-mcp-adapters. Through investigation, I noticed this error typically follows an anyio.CancelledError raised on the MCP Server side. My hypothesis is: when the MCP Server throws an error due to a broken connection, the context manager in langchain-mcp-adapters may exit prematurely — skipping the initialization of the call_tool_result variable — which later leads to the “unbound local variable” exception.

Further testing revealed that Microsoft’s fetch-sse library automatically disconnects the SSE stream after periods of inactivity — which is precisely what triggers the issue. When I switched to native fetch + EventSource to consume the stream, the error disappeared. This confirms the root cause lies in “frontend-initiated disconnection,” which cascades into a server-side exception chain:

Frontend disconnects → FastAPI cancels the request execution;
Connection to MCP Server is forcibly closed;
MCP Server, unaware of the disconnection, attempts to write to the now-closed connection → triggers anyio.CancelledError;
The exception is caught and “silently skipped” by the context manager in langchain-mcp-adapters;
Subsequent code tries to access call_tool_result, which was never initialized → raises “unbound variable” error.
Strictly speaking, this isn’t entirely a bug in langchain-mcp-adapters — it’s a “reasonable” response to an unexpected cancellation. However, the lack of defensive initialization (e.g., setting call_tool_result = None at the start) results in a misleading/unhelpful error message that obscures the true cause.

📌 Easy Reproduction Steps:

Have the frontend actively disconnect during SSE streaming (e.g., page refresh, tab close, or using an SSE client with timeout/auto-reconnect);
Backend immediately terminates execution → MCP Server connection breaks;
MCP Server continues writing to the closed connection → triggers anyio.CancelledError;
Finally, langchain-mcp-adapters raises “unbound variable” due to uninitialized state.
I hope this clarifies the issue. I’m happy to provide a minimal reproduction repo or detailed logs if needed. I’d also welcome suggestions for more robust error handling — for example, initializing call_tool_result to None within the context manager to prevent unbound errors entirely.

Thank you again for your attention and support!

the mcp server transport is streamable-http

[eyurtsev]

@TBice123123 OK great thank you for this context it's super helfpul! I'll try re-creating this via unit tests

[eyurtsev]

@TBice123123 I tried reproducing in various ways for the past 2 hrs but without success. For now, I merged a more helpful Runtime exception.

If you can figure out how to convert the reproduction into a unit test that would be amazing!

The exception is caught and “silently skipped” by the context manager in langchain-mcp-adapters;

This context manager is from the mcp-sdk, we're just building on top of it. A reproduction would be helpful in figuring out how to actually surface the underlying exception

[TBice123123]

@TBice123123 I tried reproducing in various ways for the past 2 hrs but without success. For now, I merged a more helpful Runtime exception.

If you can figure out how to convert the reproduction into a unit test that would be amazing!

The exception is caught and “silently skipped” by the context manager in langchain-mcp-adapters;

This context manager is from the mcp-sdk, we're just building on top of it. A reproduction would be helpful in figuring out how to actually surface the underlying exception

I tried to write a local minimal reproducible example, but please note that this is not a unit test.

server.py:

import asyncio
from fastmcp import FastMCP


mcp = FastMCP()


@mcp.tool
async def hello():
    await asyncio.sleep(10)
    return "Hello"


if __name__ == "__main__":
    mcp.run(transport="streamable-http", stateless_http=True)

main.py:

from langchain_mcp_adapters.client import MultiServerMCPClient

from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
import asyncio
import uvicorn


client = MultiServerMCPClient({
    "server": {"url": "http://localhost:8000/mcp", "transport": "streamable_http"}
})


app = FastAPI()


@app.get("/sse")
async def sse_endpoint(request: Request):
    async def event_stream():
        tools = await client.get_tools()
        tool = tools[0]
        await tool.ainvoke({})

    return StreamingResponse(event_stream(), media_type="text/event-stream")


if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=5000)

Start the project, visit the /sse path, then close the tab — you should see an error like the following:

[lchkeepit]

I've faced a simiar issue that when tool execution gets timedout. asyncio.CancelledError will be throwed while this will not be caught by the Exception type depending on python version https://docs.python.org/3/library/asyncio-exceptions.html. In my case, it is python 3.12.