Skip to content

Progress notifications cause server to hang on stdio transport #1141

Open

Description

@abhishekgahlot2

Initial Checks

Description

When using the low-level Server API (mcp.server.lowlevel.Server) with stdio transport, sending progress notifications during request handling causes the server to hang indefinitely and never send the final response.

What I am seeing:

  • Server successfully sends progress notification via write_stream.send()
  • Server handler returns CallToolResult
  • The final response is never sent to the client
  • Client times out waiting for response
  • Server remains blocked and time out eventually

Example Code

import asyncio
from mcp.server.lowlevel import Server
from mcp.server.stdio import stdio_server
from mcp.types import *

server = Server("progress-bug-demo")

@server.list_tools()
async def handle_list_tools() -> list[Tool]:
    return [Tool(
        name="test_tool",
        description="Demonstrates the bug",
        inputSchema={"type": "object", "properties": {}}
    )]

@server.call_tool()
async def handle_call_tool(name: str, arguments: dict) -> list[TextContent]:
    ctx = server.request_context
    progress_token = ctx.meta.progressToken if ctx.meta else None
    
    if progress_token:
        # This causes the server to hang
        await ctx.session.send_progress_notification(
            progress_token=progress_token,
            progress=0.5,
            total=1.0,
            message="Working..."
        )
    
    # This response is never sent due to the hang
    return [TextContent(type="text", text="Task completed!")]

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            server.create_initialization_options()
        )

if __name__ == "__main__":
    asyncio.run(main())

Python & MCP Python SDK

MCP: 1.10.1
Python: 3.12.6

From deeper debugging looks like buffer size is the problem : https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/stdio.py#L57

Have to test locally if increasing it will most likely fix the issue and if its causing more problems than just fixing this.

Activity

  1. abhishekgahlot2 commented on Jul 14, 2025

    @abhishekgahlot2
    Author

    Actually using buffered streams seems to fix this problem.

  2. ihrpr commented on Jul 15, 2025

    @ihrpr
    Contributor

    @abhishekgahlot2 which client are you using for testing?

  3. self-assigned this
    on Jul 15, 2025
  4. abhishekgahlot2 commented on Jul 15, 2025

    @abhishekgahlot2
    Author

    @ihrpr I am using a custom Python MCP client that I built for agents.

    However looking more into my custom client i see sending progress via

    # cause deadlock
    await self.write_stream.send({...})
    
    # sdk works well here
    await ctx.session.send_progress_notification(...)
    
  5. added
    bugSomething isn't working
    ready for workEnough information for someone to start working on
    P2Moderate issues affecting some users, edge cases, potentially valuable feature
    P3Nice to haves, rare edge cases
    and removed
    P2Moderate issues affecting some users, edge cases, potentially valuable feature
    on Oct 6, 2025
  6. 2830500285 commented on May 21, 2026

    @2830500285

    I'll take a look at this. First step is to reproduce it on current main, then I'll keep any fix scoped to the stdio/progress path with regression coverage.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P3Nice to haves, rare edge casesbugSomething isn't workingready for workEnough information for someone to start working on

    Type

    No type

    Projects

    • Status
      To triage

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions