fixes

Author: ezynda3

client/client.go

@@ -508,9 +508,10 @@ func (c *Client) handleSamplingRequestTransport(ctx context.Context, request tra
 		if contentMap, ok := params.Messages[i].Content.(map[string]any); ok {
 			// Parse the content map into a proper Content type
 			content, err := mcp.ParseContent(contentMap)
-			if err == nil {
-				params.Messages[i].Content = content
+			if err != nil {
+				return nil, fmt.Errorf("failed to parse content for message %d: %w", i, err)
 			}
+			params.Messages[i].Content = content
 		}
 	}
 

client/transport/streamable_http.go

@@ -594,7 +594,13 @@ func (c *StreamableHTTP) IsOAuthEnabled() bool {
 func (c *StreamableHTTP) listenForever(ctx context.Context) {
 	c.logger.Infof("listening to server forever")
 	for {
-		// Use the original context for continuous listening - no timeout
+		// Use the original context for continuous listening - no per-iteration timeout
+		// The SSE connection itself will detect disconnections via the underlying HTTP transport,
+		// and the context cancellation will propagate from the parent to stop listening gracefully.
+		// We don't add an artificial timeout here because:
+		// 1. Persistent SSE connections are meant to stay open indefinitely
+		// 2. Network-level timeouts and keep-alives handle connection health
+		// 3. Context cancellation (user-initiated or system shutdown) provides clean shutdown
 		err := c.createGETConnectionToServer(ctx)
 		if errors.Is(err, ErrGetMethodNotAllowed) {
 			// server does not support listening

mcp/utils.go

@@ -945,6 +945,12 @@ func ToBoolPtr(b bool) *bool {
 // GetTextFromContent extracts text from a Content interface that might be a TextContent struct
 // or a map[string]any that was unmarshaled from JSON. This is useful when dealing with content
 // that comes from different transport layers that may handle JSON differently.
+//
+// This function uses fallback behavior for non-text content - it returns a string representation
+// via fmt.Sprintf for any content that cannot be extracted as text. This is a lossy operation
+// intended for convenience in logging and display scenarios.
+//
+// For strict type validation, use ParseContent() instead, which returns an error for invalid content.
 func GetTextFromContent(content any) string {
 	switch c := content.(type) {
 	case TextContent:

server/stdio.go

@@ -606,7 +606,18 @@ func (s *stdioSession) handleSamplingResponse(rawMessage json.RawMessage) bool {
 		if err := json.Unmarshal(response.Result, &result); err != nil {
 			samplingResp.err = fmt.Errorf("failed to unmarshal sampling response: %w", err)
 		} else {
-			samplingResp.result = &result
+			// Parse content from map[string]any to proper Content type (TextContent, ImageContent, AudioContent)
+			if contentMap, ok := result.Content.(map[string]any); ok {
+				content, err := mcp.ParseContent(contentMap)
+				if err != nil {
+					samplingResp.err = fmt.Errorf("failed to parse sampling response content: %w", err)
+				} else {
+					result.Content = content
+					samplingResp.result = &result
+				}
+			} else {
+				samplingResp.result = &result
+			}
 		}
 	}
 

server/streamable_http.go

@@ -235,6 +235,21 @@ func (s *StreamableHTTPServer) Shutdown(ctx context.Context) error {
 
 // --- internal methods ---
 
+// getOrCreateSession retrieves an existing persistent session or creates a new ephemeral one.
+// Persistent sessions are used for bidirectional communication (sampling, elicitation) and are
+// stored in activeSessions. Ephemeral sessions are created per-request for stateless operation.
+func (s *StreamableHTTPServer) getOrCreateSession(sessionID string) *streamableHttpSession {
+	// Check if a persistent session exists (created by continuous listening GET connection)
+	if sessionInterface, exists := s.activeSessions.Load(sessionID); exists {
+		if persistentSession, ok := sessionInterface.(*streamableHttpSession); ok {
+			return persistentSession
+		}
+	}
+
+	// Create ephemeral session if no persistent session exists
+	return newStreamableHttpSession(sessionID, s.sessionTools, s.sessionLogLevels)
+}
+
 func (s *StreamableHTTPServer) handlePost(w http.ResponseWriter, r *http.Request) {
 	// post request carry request/notification message
 
@@ -309,18 +324,8 @@ func (s *StreamableHTTPServer) handlePost(w http.ResponseWriter, r *http.Request
 		}
 	}
 
-	// Check if a persistent session exists (for sampling support), otherwise create ephemeral session
-	var session *streamableHttpSession
-	if sessionInterface, exists := s.activeSessions.Load(sessionID); exists {
-		if persistentSession, ok := sessionInterface.(*streamableHttpSession); ok {
-			session = persistentSession
-		}
-	}
-
-	// Create ephemeral session if no persistent session exists
-	if session == nil {
-		session = newStreamableHttpSession(sessionID, s.sessionTools, s.sessionLogLevels)
-	}
+	// Get or create session (reuses persistent sessions for bidirectional communication)
+	session := s.getOrCreateSession(sessionID)
 
 	// Set the client context before handling the message
 	ctx := s.server.WithContext(r.Context(), session)
@@ -431,15 +436,16 @@ func (s *StreamableHTTPServer) handleGet(w http.ResponseWriter, r *http.Request)
 		sessionID = uuid.New().String()
 	}
 
-	// Check if session already exists, if so reuse it for sampling
+	// Check if session already exists (reuse for persistent bidirectional communication)
+	sessionInterface, sessionExists := s.activeSessions.Load(sessionID)
 	var session *streamableHttpSession
-	if sessionInterface, exists := s.activeSessions.Load(sessionID); exists {
+	if sessionExists {
 		if existingSession, ok := sessionInterface.(*streamableHttpSession); ok {
 			session = existingSession
 		}
 	}
 
-	// Create new session if none exists
+	// Create and register new persistent session if none exists
 	if session == nil {
 		session = newStreamableHttpSession(sessionID, s.sessionTools, s.sessionLogLevels)
 		if err := s.server.RegisterSession(r.Context(), session); err != nil {
@@ -448,7 +454,7 @@ func (s *StreamableHTTPServer) handleGet(w http.ResponseWriter, r *http.Request)
 		}
 		defer s.server.UnregisterSession(r.Context(), sessionID)
 
-		// Register session for sampling response delivery
+		// Store session for bidirectional communication (sampling/elicitation response delivery)
 		s.activeSessions.Store(sessionID, session)
 		defer s.activeSessions.Delete(sessionID)
 	}
@@ -923,6 +929,17 @@ func (s *streamableHttpSession) RequestSampling(ctx context.Context, request mcp
 		if err := json.Unmarshal(response.result, &result); err != nil {
 			return nil, fmt.Errorf("failed to unmarshal sampling response: %v", err)
 		}
+
+		// Parse content from map[string]any to proper Content type (TextContent, ImageContent, AudioContent)
+		// HTTP transport unmarshals Content as map[string]any, we need to convert it to the proper type
+		if contentMap, ok := result.Content.(map[string]any); ok {
+			content, err := mcp.ParseContent(contentMap)
+			if err != nil {
+				return nil, fmt.Errorf("failed to parse sampling response content: %w", err)
+			}
+			result.Content = content
+		}
+
 		return &result, nil
 	case <-ctx.Done():
 		return nil, ctx.Err()

www/docs/pages/clients/advanced-sampling.mdx

@@ -6,6 +6,24 @@ Learn how to implement MCP clients that can handle sampling requests from server
 
 Sampling allows MCP clients to respond to LLM completion requests from servers. When a server needs to generate content, answer questions, or perform reasoning tasks, it can send a sampling request to the client, which then processes it using an LLM and returns the result.
 
+:::danger[Critical Security Requirement]
+Per the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/client/sampling#user-interaction-model), sampling implementations **SHOULD** always include a human in the loop with the ability to deny sampling requests.
+
+**You MUST implement approval flows that:**
+- Present each sampling request to the user for review before execution
+- Allow users to view and edit prompts before sending to the LLM
+- Display generated responses for user approval before returning to the server
+- Provide clear UI to accept or reject requests at each stage
+
+**Without human approval, your implementation:**
+- Allows servers to make unauthorized LLM requests without user consent
+- May expose sensitive information through unreviewed prompts
+- Creates uncontrolled API costs from automated sampling
+- Violates user trust and security best practices
+
+The examples below show basic handler implementation. **You must add approval logic** before using in production.
+:::
+
 ## Implementing a Sampling Handler
 
 Create a sampling handler by implementing the `SamplingHandler` interface:

www/docs/pages/servers/advanced-sampling.mdx

@@ -6,6 +6,25 @@ Learn how to implement MCP servers that can request LLM completions from clients
 
 Sampling allows MCP servers to request LLM completions from clients, enabling bidirectional communication where servers can leverage client-side LLM capabilities. This is particularly useful for tools that need to generate content, answer questions, or perform reasoning tasks.
 
+:::info[User Consent Required]
+Per the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/client/sampling#user-interaction-model), clients **SHOULD** implement human-in-the-loop approval for sampling requests.
+
+When you request sampling from a client:
+- The user will typically be prompted to review and approve your request
+- The user may modify your prompts before sending to their LLM
+- The user may reject your request entirely
+- Response times may be longer due to user interaction
+
+**Design your tools accordingly:**
+- Provide clear descriptions of why sampling is needed
+- Use descriptive system prompts explaining the purpose
+- Handle rejection errors gracefully
+- Consider timeouts for user approval delays
+- Don't assume immediate or automatic approval
+
+Well-designed sampling requests improve user trust and approval rates.
+:::
+
 ## Enabling Sampling
 
 To enable sampling in your server, call `EnableSampling()` during server setup:

www/docs/pages/transports/http.mdx

@@ -693,6 +693,24 @@ The headers are automatically populated by the transport layer and are available
 
 StreamableHTTP transport now supports bidirectional sampling, allowing servers to request LLM completions from clients. This enables advanced scenarios where servers can leverage client-side LLM capabilities.
 
+:::warning[Security: Human-in-the-Loop Required]
+Per the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/client/sampling), implementations **SHOULD** always include a human in the loop with the ability to deny sampling requests.
+
+**Your sampling handler implementation MUST:**
+- Present sampling requests to users for review before execution
+- Allow users to view and edit prompts before sending to the LLM
+- Display generated responses for approval before returning to the server
+- Provide clear UI to accept or reject sampling requests
+
+Failing to implement approval flows creates serious security and trust risks, including:
+- Servers making unauthorized LLM requests on behalf of users
+- Exposure of sensitive data through unreviewed prompts
+- Uncontrolled API costs from automated sampling
+- Lack of user consent for AI interactions
+
+See the [example implementation](#example-with-approval-flow) below for a reference approval pattern.
+:::
+
 ### Requirements for Sampling
 
 To enable sampling with StreamableHTTP transport, the client **must** use the `WithContinuousListening()` option:
@@ -777,6 +795,54 @@ mcpServer.AddTool(mcp.Tool{
 - Without continuous listening, the transport operates in stateless request/response mode only
 - Network interruptions may require reconnection and re-establishment of the sampling channel
 
+### Example with Approval Flow
+
+Here's a reference implementation showing proper human-in-the-loop approval:
+
+```go
+type ApprovalSamplingHandler struct {
+    llmClient LLMClient // Your actual LLM client
+    ui        UserInterface // Your UI for presenting requests to users
+}
+
+func (h *ApprovalSamplingHandler) CreateMessage(ctx context.Context, request mcp.CreateMessageRequest) (*mcp.CreateMessageResult, error) {
+    // Step 1: Present the sampling request to the user for review
+    approved, modifiedRequest, err := h.ui.PresentSamplingRequest(ctx, request)
+    if err != nil {
+        return nil, fmt.Errorf("failed to get user approval: %w", err)
+    }
+    
+    if !approved {
+        return nil, fmt.Errorf("user rejected sampling request")
+    }
+    
+    // Step 2: Send the approved/modified request to the LLM
+    response, err := h.llmClient.CreateCompletion(ctx, modifiedRequest)
+    if err != nil {
+        return nil, fmt.Errorf("LLM request failed: %w", err)
+    }
+    
+    // Step 3: Present the response to the user for final approval
+    approved, modifiedResponse, err := h.ui.PresentSamplingResponse(ctx, response)
+    if err != nil {
+        return nil, fmt.Errorf("failed to get response approval: %w", err)
+    }
+    
+    if !approved {
+        return nil, fmt.Errorf("user rejected sampling response")
+    }
+    
+    // Step 4: Return the approved response to the server
+    return modifiedResponse, nil
+}
+```
+
+**Key Points:**
+- Users must explicitly approve both the request (before sending to LLM) and the response (before returning to server)
+- Users can modify prompts or responses before approval
+- Rejection at any stage returns an error to the server
+- The UI should clearly display what the server is requesting and why
+
 ## Next Steps
 
 - **[In-Process Transport](/transports/inprocess)** - Learn about embedded scenarios