Merge remote-tracking branch 'origin/main' into fix/nginx-underscore-headers

Author: jaylonmcshan19-x

CHANGELOG.md

@@ -1,5 +1,9 @@
 ## UNRELEASED
 
+FIXES
+
+* Fix sessions handling in stateless and load balanced environments
+
 IMPROVEMENTS
 * Add `Authorization: Bearer` header support for Terraform token in proxy environments
 * Add `--heartbeat-interval` CLI flag and `MCP_HEARTBEAT_INTERVAL` env var for HTTP heartbeat in load-balanced environments

README.md

@@ -496,7 +496,50 @@ To enable stateless mode, set the environment variable:
 ```bash
 export MCP_SESSION_MODE=stateless
 ```
+## Troubleshooting
 
+### Corporate Proxy / TLS Inspection (Zscaler, etc.)
+
+If you're behind a corporate proxy that performs TLS inspection (like Zscaler Internet Access), you may see certificate errors:
+```
+tls: failed to verify certificate: x509: certificate signed by unknown authority
+```
+
+**Solution: Mount your corporate CA certificate into the container:**
+```bash
+docker run -i --rm \
+  -v /path/to/corporate-ca.pem:/etc/ssl/certs/corporate-ca.pem \
+  -e SSL_CERT_FILE=/etc/ssl/certs/corporate-ca.pem \
+  hashicorp/terraform-mcp-server:0.4.0
+```
+
+For MCP client configurations:
+```json
+{
+  "mcpServers": {
+    "terraform": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-v", "/path/to/corporate-ca.pem:/etc/ssl/certs/corporate-ca.pem",
+        "-e", "SSL_CERT_FILE=/etc/ssl/certs/corporate-ca.pem",
+        "-e", "TFE_TOKEN=<>",
+        "hashicorp/terraform-mcp-server:0.4.0"
+      ]
+    }
+  }
+}
+```
+
+**Alternative: Run the binary directly**
+
+If Docker is not permitted in your environment, you can install and run the server binary directly, which will use your system's certificate store:
+```bash
+go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@latest
+terraform-mcp-server stdio
+```
 ## Development
 
 ### Prerequisites

cmd/terraform-mcp-server/main.go

@@ -18,6 +18,7 @@ import (
 	"github.com/hashicorp/terraform-mcp-server/pkg/toolsets"
 	"github.com/hashicorp/terraform-mcp-server/version"
 
+	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 	log "github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
@@ -69,6 +70,23 @@ func NewServer(version string, logger *log.Logger, enabledToolsets []string, opt
 	hooks.AddOnUnregisterSession(func(ctx context.Context, session server.ClientSession) {
 		client.EndSessionHandler(ctx, session, logger)
 	})
+	// When running multiple sessions of the MCP server (load balancing), calling client.NewSessionHandler
+	// in both BeforeListTools and BeforeCallTool ensures that a session that was not initialized during
+	// registration (e.g., due to being routed to a different instance) will still have its clients created
+	// before any tool calls are made. This provides a safety net to ensure that all sessions have
+	// the necessary clients initialized regardless of how they are routed.
+	hooks.AddBeforeListTools(func(ctx context.Context, id any, message *mcp.ListToolsRequest) {
+		session := server.ClientSessionFromContext(ctx)
+		if session != nil {
+			client.NewSessionHandler(ctx, session, logger)
+		}
+	})
+	hooks.AddBeforeCallTool(func(ctx context.Context, id any, message *mcp.CallToolRequest) {
+		session := server.ClientSessionFromContext(ctx)
+		if session != nil {
+			client.NewSessionHandler(ctx, session, logger)
+		}
+	})
 
 	// Add hooks to options
 	opts = append(opts, server.WithHooks(hooks))
@@ -210,19 +228,6 @@ func shouldUseStreamableHTTPMode() bool {
 		os.Getenv("MCP_ENDPOINT") != ""
 }
 
-// shouldUseStatelessMode returns true if the MCP_SESSION_MODE environment variable is set to "stateless"
-func shouldUseStatelessMode() bool {
-	mode := strings.ToLower(os.Getenv("MCP_SESSION_MODE"))
-
-	// Explicitly check for "stateless" value
-	if mode == "stateless" {
-		return true
-	}
-
-	// All other values (including empty string, "stateful", or any other value) default to stateful mode
-	return false
-}
-
 // getHTTPPort returns the port from environment variables or default
 func getHTTPPort() string {
 	if port := os.Getenv("TRANSPORT_PORT"); port != "" {
@@ -239,6 +244,19 @@ func getHTTPHost() string {
 	return "127.0.0.1"
 }
 
+// shouldUseStatelessMode returns true if the MCP_SESSION_MODE environment variable is set to "stateless"
+func shouldUseStatelessMode() bool {
+	mode := strings.ToLower(os.Getenv("MCP_SESSION_MODE"))
+
+	// Explicitly check for "stateless" value
+	if mode == "stateless" {
+		return true
+	}
+
+	// All other values (including empty string, "stateful", or any other value) default to stateful mode
+	return false
+}
+
 // Add function to get endpoint path from environment or flag
 func getEndpointPath(cmd *cobra.Command) string {
 	// First check environment variable

pkg/client/session.go

@@ -15,6 +15,10 @@ type contextKey string
 
 // NewSessionHandler initializes clients for the session
 func NewSessionHandler(ctx context.Context, session server.ClientSession, logger *log.Logger) {
+	if _, ok := activeTfeClients.Load(session.SessionID()); ok {
+		return
+	}
+
 	// Create both TFE and HTTP clients for the session
 	tfeClient, err := CreateTfeClientForSession(ctx, session, logger)
 	if err != nil {