fastmcp 2.14.2__tar.gz → 2.14.3__tar.gz

{fastmcp-2.14.2 → fastmcp-2.14.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.14.2
+Version: 2.14.3
 Summary: The fast, Pythonic way to build MCP servers and clients.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp
@@ -28,7 +28,7 @@ Requires-Dist: openapi-pydantic>=0.5.1
 Requires-Dist: platformdirs>=4.0.0
 Requires-Dist: py-key-value-aio[disk,keyring,memory]<0.4.0,>=0.3.0
 Requires-Dist: pydantic[email]>=2.11.7
-Requires-Dist: pydocket>=0.16.3
+Requires-Dist: pydocket>=0.16.6
 Requires-Dist: pyperclip>=1.9.0
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: rich>=13.9.4

{fastmcp-2.14.2 → fastmcp-2.14.3}/pyproject.toml

@@ -10,7 +10,7 @@ dependencies = [
     "mcp>=1.24.0,<2.0",
     "openapi-pydantic>=0.5.1",
     "platformdirs>=4.0.0",
-    "pydocket>=0.16.3",
+    "pydocket>=0.16.6",
     "rich>=13.9.4",
     "cyclopts>=4.0.0",
     "authlib>=1.6.5",

{fastmcp-2.14.2 → fastmcp-2.14.3}/src/fastmcp/cli/cli.py

@@ -28,6 +28,7 @@ from fastmcp.utilities.inspect import (
 )
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.mcp_server_config import MCPServerConfig
+from fastmcp.utilities.version_check import check_for_newer_version
 
 logger = get_logger("cli")
 console = Console()
@@ -122,6 +123,14 @@ def version(
     else:
         console.print(g)
 
+        # Check for updates (not included in --copy output)
+        if newer_version := check_for_newer_version():
+            console.print()
+            console.print(
+                f"[bold]🎉 FastMCP update available:[/bold] [green]{newer_version}[/green]"
+            )
+            console.print("[dim]Run: pip install --upgrade fastmcp[/dim]")
+
 
 @app.command
 async def dev(

{fastmcp-2.14.2 → fastmcp-2.14.3}/src/fastmcp/client/auth/oauth.py

@@ -105,10 +105,13 @@ class TokenStorageAdapter(TokenStorage):
 
     @override
     async def set_tokens(self, tokens: OAuthToken) -> None:
+        # Don't set TTL based on access token expiry - the refresh token may be
+        # valid much longer. Use 1 year as a reasonable upper bound; the OAuth
+        # provider handles actual token expiry/refresh logic.
         await self._storage_oauth_token.put(
             key=self._get_token_cache_key(),
             value=tokens,
-            ttl=tokens.expires_in,
+            ttl=60 * 60 * 24 * 365,  # 1 year
         )
 
     @override

{fastmcp-2.14.2 → fastmcp-2.14.3}/src/fastmcp/client/transports.py

@@ -25,7 +25,7 @@ from mcp.client.sse import sse_client
 from mcp.client.stdio import stdio_client
 from mcp.client.streamable_http import streamable_http_client
 from mcp.server.fastmcp import FastMCP as FastMCP1Server
-from mcp.shared._httpx_utils import McpHttpClientFactory
+from mcp.shared._httpx_utils import McpHttpClientFactory, create_mcp_http_client
 from mcp.shared.memory import create_client_server_memory_streams
 from pydantic import AnyUrl
 from typing_extensions import TypedDict, Unpack
@@ -284,25 +284,31 @@ class StreamableHttpTransport(ClientTransport):
         # need to be forwarded to the remote server.
         headers = get_http_headers() | self.headers
 
-        # Build httpx client configuration
-        httpx_client_kwargs: dict[str, Any] = {
-            "headers": headers,
-            "auth": self.auth,
-            "follow_redirects": True,
-        }
-
-        # Configure timeout if provided (convert timedelta to seconds for httpx)
+        # Configure timeout if provided, preserving MCP's 30s connect default
+        timeout: httpx.Timeout | None = None
         if session_kwargs.get("read_timeout_seconds") is not None:
             read_timeout_seconds = cast(
                 datetime.timedelta, session_kwargs.get("read_timeout_seconds")
             )
-            httpx_client_kwargs["timeout"] = read_timeout_seconds.total_seconds()
+            timeout = httpx.Timeout(30.0, read=read_timeout_seconds.total_seconds())
 
-        # Create httpx client from factory or use default
+        # Create httpx client from factory or use default with MCP-appropriate timeouts
+        # create_mcp_http_client uses 30s connect/5min read timeout by default,
+        # and always enables follow_redirects
         if self.httpx_client_factory is not None:
-            http_client = self.httpx_client_factory(**httpx_client_kwargs)
+            # Factory clients get the full kwargs for backwards compatibility
+            http_client = self.httpx_client_factory(
+                headers=headers,
+                auth=self.auth,
+                follow_redirects=True,
+                **({"timeout": timeout} if timeout else {}),
+            )
         else:
-            http_client = httpx.AsyncClient(**httpx_client_kwargs)
+            http_client = create_mcp_http_client(
+                headers=headers,
+                timeout=timeout,
+                auth=self.auth,
+            )
 
         # Ensure httpx client is closed after use
         async with (

{fastmcp-2.14.2 → fastmcp-2.14.3}/src/fastmcp/server/auth/oauth_proxy.py

@@ -1221,12 +1221,24 @@ class OAuthProxy(OAuthProvider):
         # - 1 year if no refresh token (likely API-key-style token like GitHub OAuth Apps)
         if "expires_in" in idp_tokens:
             expires_in = int(idp_tokens["expires_in"])
+            logger.debug(
+                "Access token TTL: %d seconds (from IdP expires_in)", expires_in
+            )
         elif self._fallback_access_token_expiry_seconds is not None:
             expires_in = self._fallback_access_token_expiry_seconds
+            logger.debug(
+                "Access token TTL: %d seconds (using configured fallback)", expires_in
+            )
         elif idp_tokens.get("refresh_token"):
             expires_in = DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS
+            logger.debug(
+                "Access token TTL: %d seconds (default, has refresh token)", expires_in
+            )
         else:
             expires_in = DEFAULT_ACCESS_TOKEN_EXPIRY_NO_REFRESH_SECONDS
+            logger.debug(
+                "Access token TTL: %d seconds (default, no refresh token)", expires_in
+            )
 
         # Calculate refresh token expiry if provided by upstream
         # Some providers include refresh_expires_in, some don't
@@ -1266,8 +1278,9 @@ class OAuthProxy(OAuthProvider):
         await self._upstream_token_store.put(
             key=upstream_token_id,
             value=upstream_token_set,
-            ttl=refresh_expires_in
-            or expires_in,  # Auto-expire when refresh token, or access token expires
+            ttl=max(
+                refresh_expires_in or 0, expires_in, 1
+            ),  # Keep until longest-lived token expires (min 1s for safety)
         )
         logger.debug("Stored encrypted upstream tokens (jti=%s)", access_jti[:8])
 
@@ -1467,10 +1480,21 @@ class OAuthProxy(OAuthProvider):
         # (user override still applies if set)
         if "expires_in" in token_response:
             new_expires_in = int(token_response["expires_in"])
+            logger.debug(
+                "Refreshed access token TTL: %d seconds (from IdP expires_in)",
+                new_expires_in,
+            )
         elif self._fallback_access_token_expiry_seconds is not None:
             new_expires_in = self._fallback_access_token_expiry_seconds
+            logger.debug(
+                "Refreshed access token TTL: %d seconds (using configured fallback)",
+                new_expires_in,
+            )
         else:
             new_expires_in = DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS
+            logger.debug(
+                "Refreshed access token TTL: %d seconds (default)", new_expires_in
+            )
         upstream_token_set.access_token = token_response["access_token"]
         upstream_token_set.expires_at = time.time() + new_expires_in
 
@@ -1504,15 +1528,18 @@ class OAuthProxy(OAuthProvider):
                 )
 
         upstream_token_set.raw_token_data = token_response
+        # Calculate refresh TTL for storage
+        refresh_ttl = new_refresh_expires_in or (
+            int(upstream_token_set.refresh_token_expires_at - time.time())
+            if upstream_token_set.refresh_token_expires_at
+            else 60 * 60 * 24 * 30  # Default to 30 days if unknown
+        )
         await self._upstream_token_store.put(
             key=upstream_token_set.upstream_token_id,
             value=upstream_token_set,
-            ttl=new_refresh_expires_in
-            or (
-                int(upstream_token_set.refresh_token_expires_at - time.time())
-                if upstream_token_set.refresh_token_expires_at
-                else 60 * 60 * 24 * 30  # Default to 30 days if unknown
-            ),  # Auto-expire when refresh token expires
+            ttl=max(
+                refresh_ttl, new_expires_in, 1
+            ),  # Keep until longest-lived token expires (min 1s for safety)
         )
 
         # Issue new minimal FastMCP access token (just a reference via JTI)
@@ -1549,7 +1576,7 @@ class OAuthProxy(OAuthProvider):
         )
 
         # Store new refresh token JTI mapping with aligned expiry
-        refresh_ttl = new_refresh_expires_in or 60 * 60 * 24 * 30
+        # (reuse refresh_ttl calculated above for upstream token store)
         await self._jti_mapping_store.put(
             key=new_refresh_jti,
             value=JTIMapping(
@@ -1622,7 +1649,10 @@ class OAuthProxy(OAuthProvider):
             # 2. Look up upstream token via JTI mapping
             jti_mapping = await self._jti_mapping_store.get(key=jti)
             if not jti_mapping:
-                logger.debug("JTI mapping not found: %s", jti)
+                logger.info(
+                    "JTI mapping not found (token may have expired): jti=%s...",
+                    jti[:16],
+                )
                 return None
 
             upstream_token_set = await self._upstream_token_store.get(
@@ -1865,6 +1895,11 @@ class OAuthProxy(OAuthProvider):
                 logger.debug(
                     f"Successfully exchanged IdP code for tokens (transaction: {txn_id}, PKCE: {bool(proxy_code_verifier)})"
                 )
+                logger.debug(
+                    "IdP token response: expires_in=%s, has_refresh_token=%s",
+                    idp_tokens.get("expires_in"),
+                    "refresh_token" in idp_tokens,
+                )
 
             except Exception as e:
                 logger.error("IdP token exchange failed: %s", e)

{fastmcp-2.14.2 → fastmcp-2.14.3}/src/fastmcp/server/context.py

@@ -185,10 +185,24 @@ class Context:
         self._tokens.append(token)
 
         # Set current server for dependency injection (use weakref to avoid reference cycles)
-        from fastmcp.server.dependencies import _current_server
+        from fastmcp.server.dependencies import (
+            _current_docket,
+            _current_server,
+            _current_worker,
+        )
 
         self._server_token = _current_server.set(weakref.ref(self.fastmcp))
 
+        # Set docket/worker from server instance for this request's context.
+        # This ensures ContextVars work even in environments (like Lambda) where
+        # lifespan ContextVars don't propagate to request handlers.
+        server = self.fastmcp
+        if server._docket is not None:
+            self._docket_token = _current_docket.set(server._docket)
+
+        if server._worker is not None:
+            self._worker_token = _current_worker.set(server._worker)
+
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
@@ -196,10 +210,20 @@ class Context:
         # Flush any remaining notifications before exiting
         await self._flush_notifications()
 
-        # Reset server token
-        if hasattr(self, "_server_token"):
-            from fastmcp.server.dependencies import _current_server
+        # Reset server/docket/worker tokens
+        from fastmcp.server.dependencies import (
+            _current_docket,
+            _current_server,
+            _current_worker,
+        )
 
+        if hasattr(self, "_worker_token"):
+            _current_worker.reset(self._worker_token)
+            delattr(self, "_worker_token")
+        if hasattr(self, "_docket_token"):
+            _current_docket.reset(self._docket_token)
+            delattr(self, "_docket_token")
+        if hasattr(self, "_server_token"):
             _current_server.reset(self._server_token)
             delattr(self, "_server_token")
 

{fastmcp-2.14.2 → fastmcp-2.14.3}/src/fastmcp/server/server.py

@@ -197,8 +197,9 @@ class FastMCP(Generic[LifespanResultT]):
         # Resolve server default for background task support
         self._support_tasks_by_default: bool = tasks if tasks is not None else False
 
-        # Docket instance (set during lifespan for cross-task access)
+        # Docket and Worker instances (set during lifespan for cross-task access)
         self._docket = None
+        self._worker = None
 
         self._additional_http_routes: list[BaseRoute] = []
         self._mounted_servers: list[MountedServer] = []
@@ -468,6 +469,8 @@ class FastMCP(Generic[LifespanResultT]):
 
                     # Create and start Worker
                     async with Worker(docket, **worker_kwargs) as worker:  # type: ignore[arg-type]
+                        # Store on server instance for cross-context access
+                        self._worker = worker
                         # Set Worker in ContextVar so CurrentWorker can access it
                         worker_token = _current_worker.set(worker)
                         try:
@@ -480,13 +483,11 @@ class FastMCP(Generic[LifespanResultT]):
                                     await worker_task
                         finally:
                             _current_worker.reset(worker_token)
+                            self._worker = None
                 finally:
-                    # Reset ContextVar
                     _current_docket.reset(docket_token)
-                    # Clear instance attribute
                     self._docket = None
         finally:
-            # Reset server ContextVar
             _current_server.reset(server_token)
 
     async def _register_mounted_server_functions(
@@ -564,6 +565,8 @@ class FastMCP(Generic[LifespanResultT]):
     @asynccontextmanager
     async def _lifespan_manager(self) -> AsyncIterator[None]:
         if self._lifespan_result_set:
+            # Lifespan already ran - ContextVars will be set by Context.__aenter__
+            # at request time, so we just yield here.
             yield
             return
 

{fastmcp-2.14.2 → fastmcp-2.14.3}/src/fastmcp/server/tasks/handlers.py

@@ -56,6 +56,7 @@ async def handle_tool_as_task(
     ctx = get_context()
     session_id = ctx.session_id
 
+    # Get Docket from ContextVar (set by Context.__aenter__ at request time)
     docket = _current_docket.get()
     if docket is None:
         raise McpError(
@@ -72,13 +73,15 @@ async def handle_tool_as_task(
     tool = await server.get_tool(tool_name)
 
     # Store task key mapping and creation timestamp in Redis for protocol handlers
-    redis_key = f"fastmcp:task:{session_id}:{server_task_id}"
-    created_at_key = f"fastmcp:task:{session_id}:{server_task_id}:created_at"
+    task_meta_key = docket.key(f"fastmcp:task:{session_id}:{server_task_id}")
+    created_at_key = docket.key(
+        f"fastmcp:task:{session_id}:{server_task_id}:created_at"
+    )
     ttl_seconds = int(
         docket.execution_ttl.total_seconds() + TASK_MAPPING_TTL_BUFFER_SECONDS
     )
     async with docket.redis() as redis:
-        await redis.set(redis_key, task_key, ex=ttl_seconds)
+        await redis.set(task_meta_key, task_key, ex=ttl_seconds)
         await redis.set(created_at_key, created_at, ex=ttl_seconds)
 
     # Send notifications/tasks/created per SEP-1686 (mandatory)
@@ -165,6 +168,7 @@ async def handle_prompt_as_task(
     ctx = get_context()
     session_id = ctx.session_id
 
+    # Get Docket from ContextVar (set by Context.__aenter__ at request time)
     docket = _current_docket.get()
     if docket is None:
         raise McpError(
@@ -181,13 +185,15 @@ async def handle_prompt_as_task(
     prompt = await server.get_prompt(prompt_name)
 
     # Store task key mapping and creation timestamp in Redis for protocol handlers
-    redis_key = f"fastmcp:task:{session_id}:{server_task_id}"
-    created_at_key = f"fastmcp:task:{session_id}:{server_task_id}:created_at"
+    task_meta_key = docket.key(f"fastmcp:task:{session_id}:{server_task_id}")
+    created_at_key = docket.key(
+        f"fastmcp:task:{session_id}:{server_task_id}:created_at"
+    )
     ttl_seconds = int(
         docket.execution_ttl.total_seconds() + TASK_MAPPING_TTL_BUFFER_SECONDS
     )
     async with docket.redis() as redis:
-        await redis.set(redis_key, task_key, ex=ttl_seconds)
+        await redis.set(task_meta_key, task_key, ex=ttl_seconds)
         await redis.set(created_at_key, created_at, ex=ttl_seconds)
 
     # Send notifications/tasks/created per SEP-1686 (mandatory)
@@ -272,12 +278,13 @@ async def handle_resource_as_task(
     ctx = get_context()
     session_id = ctx.session_id
 
+    # Get Docket from ContextVar (set by Context.__aenter__ at request time)
     docket = _current_docket.get()
     if docket is None:
         raise McpError(
             ErrorData(
                 code=INTERNAL_ERROR,
-                message="Background tasks require Docket",
+                message="Background tasks require a running FastMCP server context",
             )
         )
 
@@ -285,13 +292,15 @@ async def handle_resource_as_task(
     task_key = build_task_key(session_id, server_task_id, "resource", str(uri))
 
     # Store task key mapping and creation timestamp in Redis for protocol handlers
-    redis_key = f"fastmcp:task:{session_id}:{server_task_id}"
-    created_at_key = f"fastmcp:task:{session_id}:{server_task_id}:created_at"
+    task_meta_key = docket.key(f"fastmcp:task:{session_id}:{server_task_id}")
+    created_at_key = docket.key(
+        f"fastmcp:task:{session_id}:{server_task_id}:created_at"
+    )
     ttl_seconds = int(
         docket.execution_ttl.total_seconds() + TASK_MAPPING_TTL_BUFFER_SECONDS
     )
     async with docket.redis() as redis:
-        await redis.set(redis_key, task_key, ex=ttl_seconds)
+        await redis.set(task_meta_key, task_key, ex=ttl_seconds)
         await redis.set(created_at_key, created_at, ex=ttl_seconds)
 
     # Send notifications/tasks/created per SEP-1686 (mandatory)

{fastmcp-2.14.2 → fastmcp-2.14.3}/src/fastmcp/server/tasks/protocol.py

@@ -77,10 +77,12 @@ async def tasks_get_handler(server: FastMCP, params: dict[str, Any]) -> GetTaskR
             )
 
         # Look up full task key and creation timestamp from Redis
-        redis_key = f"fastmcp:task:{session_id}:{client_task_id}"
-        created_at_key = f"fastmcp:task:{session_id}:{client_task_id}:created_at"
+        task_meta_key = docket.key(f"fastmcp:task:{session_id}:{client_task_id}")
+        created_at_key = docket.key(
+            f"fastmcp:task:{session_id}:{client_task_id}:created_at"
+        )
         async with docket.redis() as redis:
-            task_key_bytes = await redis.get(redis_key)
+            task_key_bytes = await redis.get(task_meta_key)
             created_at_bytes = await redis.get(created_at_key)
 
         task_key = None if task_key_bytes is None else task_key_bytes.decode("utf-8")
@@ -176,9 +178,9 @@ async def tasks_result_handler(server: FastMCP, params: dict[str, Any]) -> Any:
             )
 
         # Look up full task key from Redis
-        redis_key = f"fastmcp:task:{session_id}:{client_task_id}"
+        task_meta_key = docket.key(f"fastmcp:task:{session_id}:{client_task_id}")
         async with docket.redis() as redis:
-            task_key_bytes = await redis.get(redis_key)
+            task_key_bytes = await redis.get(task_meta_key)
 
         task_key = None if task_key_bytes is None else task_key_bytes.decode("utf-8")
 
@@ -309,10 +311,12 @@ async def tasks_cancel_handler(
             )
 
         # Look up full task key and creation timestamp from Redis
-        redis_key = f"fastmcp:task:{session_id}:{client_task_id}"
-        created_at_key = f"fastmcp:task:{session_id}:{client_task_id}:created_at"
+        task_meta_key = docket.key(f"fastmcp:task:{session_id}:{client_task_id}")
+        created_at_key = docket.key(
+            f"fastmcp:task:{session_id}:{client_task_id}:created_at"
+        )
         async with docket.redis() as redis:
-            task_key_bytes = await redis.get(redis_key)
+            task_key_bytes = await redis.get(task_meta_key)
             created_at_bytes = await redis.get(created_at_key)
 
         task_key = None if task_key_bytes is None else task_key_bytes.decode("utf-8")

{fastmcp-2.14.2 → fastmcp-2.14.3}/src/fastmcp/server/tasks/subscriptions.py

@@ -70,7 +70,7 @@ async def subscribe_to_task_updates(
                 )
 
     except Exception as e:
-        logger.warning(f"Subscription task failed for {task_id}: {e}", exc_info=True)
+        logger.error(f"subscribe_to_task_updates failed for {task_id}: {e}")
 
 
 async def _send_status_notification(
@@ -101,8 +101,7 @@ async def _send_status_notification(
     key_parts = parse_task_key(task_key)
     session_id = key_parts["session_id"]
 
-    # Retrieve createdAt timestamp from Redis
-    created_at_key = f"fastmcp:task:{session_id}:{task_id}:created_at"
+    created_at_key = docket.key(f"fastmcp:task:{session_id}:{task_id}:created_at")
     async with docket.redis() as redis:
         created_at_bytes = await redis.get(created_at_key)
 
@@ -175,8 +174,7 @@ async def _send_progress_notification(
     key_parts = parse_task_key(task_key)
     session_id = key_parts["session_id"]
 
-    # Retrieve createdAt timestamp from Redis
-    created_at_key = f"fastmcp:task:{session_id}:{task_id}:created_at"
+    created_at_key = docket.key(f"fastmcp:task:{session_id}:{task_id}:created_at")
     async with docket.redis() as redis:
         created_at_bytes = await redis.get(created_at_key)
 

{fastmcp-2.14.2 → fastmcp-2.14.3}/src/fastmcp/settings.py

@@ -392,6 +392,21 @@ class Settings(BaseSettings):
         ),
     ] = True
 
+    check_for_updates: Annotated[
+        Literal["stable", "prerelease", "off"],
+        Field(
+            description=inspect.cleandoc(
+                """
+                Controls update checking when displaying the CLI banner.
+                - "stable": Check for stable releases only (default)
+                - "prerelease": Also check for pre-release versions (alpha, beta, rc)
+                - "off": Disable update checking entirely
+                Set via FASTMCP_CHECK_FOR_UPDATES environment variable.
+                """
+            ),
+        ),
+    ] = "stable"
+
     @property
     def server_auth_class(self) -> AuthProvider | None:
         from fastmcp.utilities.types import get_cached_typeadapter

{fastmcp-2.14.2 → fastmcp-2.14.3}/src/fastmcp/utilities/cli.py

@@ -17,6 +17,7 @@ from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.mcp_server_config import MCPServerConfig
 from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import FileSystemSource
 from fastmcp.utilities.types import get_cached_typeadapter
+from fastmcp.utilities.version_check import check_for_newer_version
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -200,6 +201,9 @@ LOGO_ASCII_4 = (
 def log_server_banner(server: FastMCP[Any]) -> None:
     """Creates and logs a formatted banner with server information and logo."""
 
+    # Check for updates (non-blocking, fails silently)
+    newer_version = check_for_newer_version()
+
     # Create the logo text
     # Use Text with no_wrap and markup disabled to preserve ANSI escape codes
     logo_text = Text.from_ansi(LOGO_ASCII_4, no_wrap=True)
@@ -231,8 +235,10 @@ def log_server_banner(server: FastMCP[Any]) -> None:
 
     # v3 notice banner (shown below main panel)
     v3_line1 = Text("✨ FastMCP 3.0 is coming!", style="bold")
-    v3_line2 = Text(
-        "Pin fastmcp<3 in production, then upgrade when you're ready.", style="dim"
+    v3_line2 = Text.assemble(
+        ("Pin ", "dim"),
+        ("`fastmcp < 3`", "dim bold"),
+        (" in production, then upgrade when you're ready.", "dim"),
     )
     v3_notice = Panel(
         Group(Align.center(v3_line1), Align.center(v3_line2)),
@@ -250,5 +256,26 @@ def log_server_banner(server: FastMCP[Any]) -> None:
     )
 
     console = Console(stderr=True)
-    # Center both panels
-    console.print(Group("\n", Align.center(panel), Align.center(v3_notice), "\n"))
+
+    # Build output elements
+    output_elements: list[Align | Panel | str] = ["\n", Align.center(panel)]
+    output_elements.append(Align.center(v3_notice))
+
+    # Add update notice if a newer version is available (shown last for visibility)
+    if newer_version:
+        update_line1 = Text.assemble(
+            ("🎉 Update available: ", "bold"),
+            (newer_version, "bold green"),
+        )
+        update_line2 = Text("Run: pip install --upgrade fastmcp", style="dim")
+        update_notice = Panel(
+            Group(Align.center(update_line1), Align.center(update_line2)),
+            border_style="blue",
+            padding=(0, 2),
+            width=80,
+        )
+        output_elements.append(Align.center(update_notice))
+
+    output_elements.append("\n")
+
+    console.print(Group(*output_elements))