FastMCP.run(transport="stdio") produces noisy traceback on KeyboardInterrupt instead of clean exit

[MikeNjoroge]

Initial Checks

• I confirm that I'm using the latest version of MCP Python SDK
• I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue

Description

Running a FastMCP stdio server from the terminal and interrupting with Ctrl-C produces a multi-frame traceback through anyio.run() → asyncio.runners → mcp.server.lowlevel.server.run → anyio.streams.memory.receive. The server is correctly waiting on stdin in an async loop; the trace surfaces because anyio/asyncio don't suppress the cancellation chain. Suggested fix: catch KeyboardInterrupt (or asyncio.CancelledError at the outer boundary) inside FastMCP.run and exit cleanly. Cosmetic but reduces user confusion when testing MCP servers from the terminal.

Example Code

Python & MCP Python SDK

Python 3.13.5
MCP Python SDK 1.27.1

[mcp-claude]

reproduced on main (commit 616476f) and v1.x (commit 6213787). root cause: the sync run(...) entry point wraps anyio.run(self.run_stdio_async) with no KeyboardInterrupt guard, so a ctrl-c during the stdio receive loop propagates as asyncio.CancelledError → WouldBlock → KeyboardInterrupt through asyncio/anyio internals before reaching user code. same pattern affects the sse and streamable-http cases on the same dispatch. workaround for users: catch KeyboardInterrupt in the caller or run via asyncio.run(mcp.run_stdio_async()) and trap there.

repro

repro_server.py (main / MCPServer):

import sys

from mcp.server.mcpserver import MCPServer

mcp = MCPServer("repro")


@mcp.tool()
def echo(s: str) -> str:
    return s


if __name__ == "__main__":
    print("READY", file=sys.stderr, flush=True)
    mcp.run(transport="stdio")

repro_server_v1x.py (v1.x / FastMCP):

import sys

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("repro")


@mcp.tool()
def echo(s: str) -> str:
    return s


if __name__ == "__main__":
    print("READY", file=sys.stderr, flush=True)
    mcp.run(transport="stdio")

repro.py — spawns the server in its own process group, waits for READY, sends SIGINT, captures stderr:

"""Reproduce: KeyboardInterrupt during stdio run produces a noisy traceback."""

import os
import signal
import subprocess
import sys
import time


def main() -> int:
    proc = subprocess.Popen(
        [sys.executable, "repro_server.py"],
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        start_new_session=True,
    )
    deadline = time.monotonic() + 30.0
    while time.monotonic() < deadline:
        line = proc.stderr.readline()
        if b"READY" in line:
            break
        time.sleep(0.05)
    time.sleep(0.5)

    print(f"sending SIGINT to pid {proc.pid}", file=sys.stderr)
    os.killpg(proc.pid, signal.SIGINT)

    try:
        stdout, stderr = proc.communicate(timeout=10)
    except subprocess.TimeoutExpired:
        proc.kill()
        stdout, stderr = proc.communicate()

    print(f"--- exit code: {proc.returncode} ---")
    print("--- stdout ---")
    sys.stdout.write(stdout.decode(errors="replace"))
    print("--- stderr ---")
    sys.stdout.write(stderr.decode(errors="replace"))
    print("--- end ---")
    return 0


if __name__ == "__main__":
    sys.exit(main())

run:

$ uv run python repro.py

tail of stderr from the spawned process:

  File "src/mcp/server/lowlevel/server.py", line 394, in run
    async for message in session.incoming_messages:
  ...
  File "anyio/streams/memory.py", line 119, in receive
    await receive_event.wait()
  ...
asyncio.exceptions.CancelledError

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "repro_server.py", line 15, in <module>
    mcp.run(transport="stdio")
  File "src/mcp/server/mcpserver/server.py", line 296, in run
    anyio.run(self.run_stdio_async)
  ...
  File "asyncio/runners.py", line 123, in run
    raise KeyboardInterrupt()
KeyboardInterrupt

code path

main — src/mcp/server/mcpserver/server.py:294-300:

match transport:
    case "stdio":
        anyio.run(self.run_stdio_async)
    case "sse":
        anyio.run(lambda: self.run_sse_async(**kwargs))
    case "streamable-http":
        anyio.run(lambda: self.run_streamable_http_async(**kwargs))

v1.x — src/mcp/server/fastmcp/server.py:294-300 is identical in shape. wrapping each anyio.run(...) in try/except KeyboardInterrupt: return (or a single guard around the match) is sufficient — run_stdio_async/run_sse_async/run_streamable_http_async already let cancellation unwind their context managers cleanly; only the outer print of the traceback needs suppressing. needs the same change on v1.x.

suggested fix

// src/mcp/server/mcpserver/server.py (and the analogous block in src/mcp/server/fastmcp/server.py on v1.x)
-        match transport:
-            case "stdio":
-                anyio.run(self.run_stdio_async)
-            case "sse":  # pragma: no cover
-                anyio.run(lambda: self.run_sse_async(**kwargs))
-            case "streamable-http":  # pragma: no cover
-                anyio.run(lambda: self.run_streamable_http_async(**kwargs))
+        try:
+            match transport:
+                case "stdio":
+                    anyio.run(self.run_stdio_async)
+                case "sse":  # pragma: no cover
+                    anyio.run(lambda: self.run_sse_async(**kwargs))
+                case "streamable-http":  # pragma: no cover
+                    anyio.run(lambda: self.run_streamable_http_async(**kwargs))
+        except KeyboardInterrupt:
+            pass

test to verify: patches anyio.run to raise KeyboardInterrupt and asserts mcp.run(transport=...) returns cleanly for each of the three transports.

[devansh-dek]

Picking this up — catching KeyboardInterrupt at the MCPServer.run() boundary so stdio servers exit cleanly on Ctrl-C.