feat: introduce health check handler support (#135)

* feat: health check handler

* introduce healthcheck support

* introduce healthcheck support

* chore: clippy

* chore: add missing arg when auth is disabled

* chore: update readme

* chore: cargo update

Author: hashemix

Cargo.lock

@@ -32,6 +32,7 @@ This SDK fully implements the latest MCP protocol version ([2025-11-25](https://
 - ✅ MCP [Tasks](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks) support
 - ✅ Batch Messages
 - ✅ Streaming & non-streaming JSON response
+- ✅ HTTP Health Checks (for load balancers & container orchestration)
 - ✅ OAuth Authentication for MCP Servers
   - ✅ [Remote Oauth Provider](crates/rust-mcp-sdk/src/auth/auth_provider/remote_auth_provider.rs) (for any provider with DCR support)
     - ✅ **Keycloak** Provider (via [rust-mcp-extra](crates/rust-mcp-extra/README.md#keycloak))
@@ -67,6 +68,7 @@ This SDK fully implements the latest MCP protocol version ([2025-11-25](https://
 - [Handler Traits](#handlers-traits)
   - [Choosing Between **ServerHandler** and **ServerHandlerCore**](#choosing-between-serverhandler-and-serverhandlercore)
   - [Choosing Between **ClientHandler** and **ClientHandlerCore**](#choosing-between-clienthandler-and-clienthandlercore)
+- [Health Check Endpoint](#health-check-endpoint)
 - [Projects using Rust MCP SDK](#projects-using-rust-mcp-sdk)
 - [Contributing](#contributing)
 - [Development](#development)
@@ -576,6 +578,28 @@ Both functions create an MCP client instance.
 
 Check out the corresponding examples at: [examples/simple-mcp-client-stdio.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples/simple-mcp-client-stdio.rs) and [examples/simple-mcp-client-stdio-core.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples/simple-mcp-client-stdio-core.rs).
 
+## Health Check Endpoint
+
+While not part of the official MCP spec, `rust-mcp-sdk` provides an optional HTTP health check endpoint. This is a practical quality-of-life feature, specifically useful when your MCP server is:
+- Exposed behind load balancers or reverse proxies (e.g., NGINX, HAProxy, Cloudflare).
+- Running in container orchestration environments (e.g., Kubernetes, Docker Swarm, AWS ECS).
+
+The health check endpoint is disabled by default. You can enable it and optionally provide your own custom handler (to return specific metrics or metadata) via `HyperServerOptions`:
+
+```rs
+let server = hyper_server::create_server(
+    server_details,
+    handler.to_mcp_server_handler(),
+    HyperServerOptions {
+        host: "127.0.0.1".into(),
+        health_endpoint: Some("/health".into()),             // enables the endpoint
+        health_handler: Some(Arc::new(CustomHealth {})),     // optional: overrides default 200 OK
+        ..Default::default()
+    },
+);
+```
+
+👉 See the [streamable_http_healthcheck.rs](crates/rust-mcp-sdk/examples/streamable_http_healthcheck.rs) example for a complete implementation demonstrating a custom JSON health handler.
 
 ## Projects using Rust MCP SDK
 

README.md

@@ -32,6 +32,7 @@ This SDK fully implements the latest MCP protocol version ([2025-11-25](https://
 - ✅ MCP [Tasks](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks) support
 - ✅ Batch Messages
 - ✅ Streaming & non-streaming JSON response
+- ✅ HTTP Health Checks (for load balancers & container orchestration)
 - ✅ OAuth Authentication for MCP Servers
   - ✅ [Remote Oauth Provider](crates/rust-mcp-sdk/src/auth/auth_provider/remote_auth_provider.rs) (for any provider with DCR support)
     - ✅ **Keycloak** Provider (via [rust-mcp-extra](crates/rust-mcp-extra/README.md#keycloak))
@@ -67,6 +68,7 @@ This SDK fully implements the latest MCP protocol version ([2025-11-25](https://
 - [Handler Traits](#handlers-traits)
   - [Choosing Between **ServerHandler** and **ServerHandlerCore**](#choosing-between-serverhandler-and-serverhandlercore)
   - [Choosing Between **ClientHandler** and **ClientHandlerCore**](#choosing-between-clienthandler-and-clienthandlercore)
+- [Health Check Endpoint](#health-check-endpoint)
 - [Projects using Rust MCP SDK](#projects-using-rust-mcp-sdk)
 - [Contributing](#contributing)
 - [Development](#development)
@@ -576,6 +578,28 @@ Both functions create an MCP client instance.
 
 Check out the corresponding examples at: [examples/simple-mcp-client-stdio.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples/simple-mcp-client-stdio.rs) and [examples/simple-mcp-client-stdio-core.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples/simple-mcp-client-stdio-core.rs).
 
+## Health Check Endpoint
+
+While not part of the official MCP spec, `rust-mcp-sdk` provides an optional HTTP health check endpoint. This is a practical quality-of-life feature, specifically useful when your MCP server is:
+- Exposed behind load balancers or reverse proxies (e.g., NGINX, HAProxy, Cloudflare).
+- Running in container orchestration environments (e.g., Kubernetes, Docker Swarm, AWS ECS).
+
+The health check endpoint is disabled by default. You can enable it and optionally provide your own custom handler (to return specific metrics or metadata) via `HyperServerOptions`:
+
+```rs
+let server = hyper_server::create_server(
+    server_details,
+    handler.to_mcp_server_handler(),
+    HyperServerOptions {
+        host: "127.0.0.1".into(),
+        health_endpoint: Some("/health".into()),             // enables the endpoint
+        health_handler: Some(Arc::new(CustomHealth {})),     // optional: overrides default 200 OK
+        ..Default::default()
+    },
+);
+```
+
+👉 See the [streamable_http_healthcheck.rs](crates/rust-mcp-sdk/examples/streamable_http_healthcheck.rs) example for a complete implementation demonstrating a custom JSON health handler.
 
 ## Projects using Rust MCP SDK
 

crates/rust-mcp-sdk/README.md

@@ -11,7 +11,8 @@ This folder contains a variety of example programs demonstrating how to use the
     - **[Streamable HTTP Examples](#%EF%B8%8F-mcp-servers-examples-streamable-http)**
         - quick-start-streamable-http
         - hello-world-server-streamable-http
-        - hello-world-server-streamable-http-core        
+        - hello-world-server-streamable-http-core      
+        - streamable_http_healthcheck  
     - **[Oauth Example](#%EF%B8%8F-mcp-server---oauth-example)**
         - mcp-server-oauth-remote
 - **MCP Client**
@@ -58,6 +59,7 @@ Minimal quick-start example demonstrating the fastest way to set up a basic MCP
 - [quick-start-streamable-http.rs](quick-start-streamable-http.rs)
 - [hello-world-server-streamable-http.rs](hello-world-server-streamable-http.rs)
 - [hello-world-server-streamable-http-core.rs](hello-world-server-streamable-http-core.rs)
+- [streamable_http_healthcheck.rs](streamable_http_healthcheck.rs)
 
 **Start the server:**
 _for instance, start the `hello-world-server-streamable-http`_

crates/rust-mcp-sdk/examples/README.md

@@ -85,6 +85,7 @@ async fn main() -> SdkResult<()> {
         HyperServerOptions {
             host: "127.0.0.1".to_string(),
             event_store: Some(std::sync::Arc::new(InMemoryEventStore::default())), // enable resumability
+            health_endpoint: Some("/health".into()), // enable health check endpoint
             ..Default::default()
         },
     );

crates/rust-mcp-sdk/examples/quick-start-streamable-http.rs

@@ -0,0 +1,99 @@
+//! Example custom health check handler.
+//!
+//! This demonstrates how to implement `HealthHandler` to override the default
+//! `/health` endpoint behavior. Instead of returning the minimal static `200 OK`,
+//! this handler returns a JSON payload containing basic service metadata.
+
+pub mod common;
+
+use crate::common::{initialize_tracing, ExampleServerHandler};
+use rust_mcp_schema::ServerCapabilitiesResources;
+use rust_mcp_sdk::mcp_http::{self, GenericBodyExt};
+use rust_mcp_sdk::schema::{
+    Implementation, InitializeResult, ProtocolVersion, ServerCapabilities, ServerCapabilitiesTools,
+};
+use rust_mcp_sdk::{
+    error::SdkResult,
+    event_store::InMemoryEventStore,
+    mcp_icon,
+    mcp_server::{hyper_server, HyperServerOptions, ToMcpServerHandler},
+    task_store::InMemoryTaskStore,
+};
+use serde_json::Map;
+use std::sync::Arc;
+
+/// Custom health check handler.
+///
+/// Use this with `HyperServerOptions.health_handler` to override the default
+/// health endpoint behavior and return a custom response.
+struct CustomHealth {}
+impl mcp_http::HealthHandler for CustomHealth {
+    fn call(
+        &self,
+        _req: mcp_http::http::Request<&str>,
+    ) -> mcp_http::http::Response<mcp_http::GenericBody> {
+        let status = serde_json::json!({
+            "status":"ok",
+            "server": env!("CARGO_PKG_NAME"),
+            "version":env!("CARGO_PKG_VERSION")
+        });
+        mcp_http::GenericBody::from_value(&status).into_json_response(http::StatusCode::OK, None)
+    }
+}
+
+#[tokio::main]
+async fn main() -> SdkResult<()> {
+    // Set up the tracing subscriber for logging
+    initialize_tracing();
+
+    // STEP 1: Define server details and capabilities
+    let server_details = InitializeResult {
+        // server name and version
+        server_info: Implementation {
+            name: "Hello World MCP Server Streamable Http/SSE".into(),
+            version: "0.1.0".into(),
+            title: Some("Hello World MCP Streamable Http/SSE".into()),
+            description: Some("test server, by Rust MCP SDK".into()),
+            icons: vec![mcp_icon!(
+                src = "https://raw.githubusercontent.com/rust-mcp-stack/rust-mcp-sdk/main/assets/rust-mcp-icon.png",
+                mime_type = "image/png",
+                sizes = ["128x128"],
+                theme = "dark"
+            )],
+            website_url: Some("https://github.com/rust-mcp-stack/rust-mcp-sdk".into()),
+        },
+        capabilities: ServerCapabilities {
+            // indicates that server support mcp tools
+            tools: Some(ServerCapabilitiesTools { list_changed: None }),
+            resources: Some(ServerCapabilitiesResources{ list_changed: None, subscribe: None }),
+            completions:Some(Map::new()),
+            ..Default::default() // Using default values for other fields
+        },
+        meta: None,
+        instructions: Some("server instructions...".into()),
+        protocol_version: ProtocolVersion::V2025_11_25.into(),
+    };
+
+    // STEP 2: instantiate our custom handler for handling MCP messages
+    let handler = ExampleServerHandler {};
+
+    // STEP 3: instantiate HyperServer, providing `server_details` , `handler` and HyperServerOptions
+    let server = hyper_server::create_server(
+        server_details,
+        handler.to_mcp_server_handler(),
+        HyperServerOptions {
+            host: "127.0.0.1".into(),
+            event_store: Some(Arc::new(InMemoryEventStore::default())), // enable resumability
+            task_store: Some(Arc::new(InMemoryTaskStore::new(None))),
+            client_task_store: Some(Arc::new(InMemoryTaskStore::new(None))),
+            health_endpoint: Some("/health".into()), // enable health check endpoint
+            health_handler: Some(Arc::new(CustomHealth {})), // use a custom health check handler
+            ..Default::default()
+        },
+    );
+
+    // STEP 4: Start the server
+    server.start().await?;
+
+    Ok(())
+}

crates/rust-mcp-sdk/examples/streamable_http_healthcheck.rs

@@ -1,6 +1,7 @@
 #[cfg(feature = "auth")]
 pub mod auth_routes;
 pub mod fallback_routes;
+pub mod health_check_route;
 #[cfg(feature = "sse")]
 pub mod messages_routes;
 #[cfg(feature = "sse")]
@@ -44,6 +45,11 @@ pub fn app_routes(
             server_options.streamable_http_endpoint(),
         ));
 
+        // mount health check if enabled
+        if let Some(health_check_endpoint) = server_options.health_endpoint.as_ref() {
+            router = router.merge(health_check_route::routes(health_check_endpoint));
+        }
+
         #[cfg(feature = "sse")]
         {
             router = router

crates/rust-mcp-sdk/src/hyper_servers/routes.rs

@@ -0,0 +1,37 @@
+use crate::hyper_servers::error::TransportServerResult;
+use crate::mcp_http::McpHttpHandler;
+use crate::{mcp_http::McpAppState, utils::remove_query_and_hash};
+use axum::response::IntoResponse;
+use axum::routing::get;
+use axum::Extension;
+use axum::Router;
+use http::{HeaderMap, Method, Uri};
+use std::sync::Arc;
+
+pub fn routes(health_check_endpoint: &str) -> Router<Arc<McpAppState>> {
+    Router::new().route(
+        remove_query_and_hash(health_check_endpoint).as_str(),
+        get(handle_health_check),
+    )
+}
+
+// The health check endpoint is **not** part of the official MCP spec but is added
+// as a practical quality-of-life feature specifically useful when:
+//   • The server is exposed behind load balancers / reverse proxies (nginx, traefik, haproxy, cloudflare, etc.)
+//   • The service is running in container orchestration (Kubernetes, Docker Swarm, ECS…)
+//
+// Many load balancers and proxies periodically send health check requests to determine
+// if a backend is still alive.
+//
+// Custom path can be set in HyperServerOptions.
+pub async fn handle_health_check(
+    headers: HeaderMap,
+    uri: Uri,
+    Extension(http_handler): Extension<Arc<McpHttpHandler>>,
+) -> TransportServerResult<impl IntoResponse> {
+    let request = McpHttpHandler::create_request(Method::GET, uri, headers, None);
+    let generic_res = http_handler.handle_health(request).await?;
+    let (parts, body) = generic_res.into_parts();
+    let resp = axum::response::Response::from_parts(parts, axum::body::Body::new(body));
+    Ok(resp)
+}