Refactor: Code organization improvements from semantic clustering analysis (#1068)

Semantic function clustering analysis identified 4 high-priority
refactoring opportunities: duplicate auth middleware application,
misplaced generic utilities, schema transformation mixed with type
definitions, and unnecessary wrapper indirection.

## Changes

### Extract auth middleware helper
- Replaced duplicate conditional auth application with
`applyAuthIfConfigured()` helper
- Eliminates 8 lines of duplication in `internal/server/transport.go`

**Before:**
```go
finalHandler := shutdownHandler
if apiKey != "" {
    finalHandler = authMiddleware(apiKey, shutdownHandler.ServeHTTP)
}
// ... repeated for closeHandler
```

**After:**
```go
finalHandler := applyAuthIfConfigured(apiKey, shutdownHandler.ServeHTTP)
finalCloseHandler := applyAuthIfConfigured(apiKey, closeHandler.ServeHTTP)
```

### Move runtime error logging to dedicated file
- Created `internal/server/errors.go` for error handling utilities
- Moved `logRuntimeError()` from `auth.go` (was incorrectly placed in
auth-specific file)

### Separate schema transformation from type definitions
- Created `internal/mcp/schema.go` for 86-line `NormalizeInputSchema()`
function
- `internal/mcp/types.go` now contains only type definitions per Go
conventions

### Remove validation wrapper
- Removed thin `validateServerConfig()` wrapper that only passed `nil`
- Tests call `validateServerConfigWithCustomSchemas()` directly

## Files Changed
- Modified: `internal/server/transport.go`, `internal/server/auth.go`,
`internal/mcp/types.go`, `internal/config/validation.go`,
`internal/config/validation_test.go`
- Added: `internal/server/errors.go`, `internal/mcp/schema.go`

> [!WARNING]
>
> <details>
> <summary>Firewall rules blocked me from connecting to one or more
addresses (expand for details)</summary>
>
> #### I tried to connect to the following addresses, but was blocked by
firewall rules:
>
> - `example.com`
> - Triggering command: `/tmp/go-build1870635187/b275/launcher.test
/tmp/go-build1870635187/b275/launcher.test
-test.testlogfile=/tmp/go-build1870635187/b275/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true ain cfg s.test
--gdwarf-5 --64 -o s.test 6525�� ache/go/1.25.7/x-s -I 86_64/git
--gdwarf-5 --64 -o 256506/b165/_x00-extld=gcc` (dns block)
> - `invalid-host-that-does-not-exist-12345.com`
> - Triggering command: `/tmp/go-build1870635187/b260/config.test
/tmp/go-build1870635187/b260/config.test
-test.testlogfile=/tmp/go-build1870635187/b260/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true d -n 10
5877973&#43;lpcox@users.noreply.github.com&gt;
64/pkg/tool/linux_amd64/vet -p net/netip -lang=go1.25
64/pkg/tool/linux_amd64/vet -I
/opt/hostedtoolcache/go/1.25.7/x64/src/runtime/cgo 256506/b165/
x_amd64/link --gdwarf-5 --64` (dns block)
> - Triggering command: `/tmp/go-build3740779677/b001/config.test
/tmp/go-build3740779677/b001/config.test
-test.testlogfile=/tmp/go-build3740779677/b001/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -uns�� on-clustering-again
/tmp/go-build165256506/b208/vet.cfg .12/x64/bin/bash` (dns block)
> - `nonexistent.local`
> - Triggering command: `/tmp/go-build1870635187/b275/launcher.test
/tmp/go-build1870635187/b275/launcher.test
-test.testlogfile=/tmp/go-build1870635187/b275/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true ain cfg s.test
--gdwarf-5 --64 -o s.test 6525�� ache/go/1.25.7/x-s -I 86_64/git
--gdwarf-5 --64 -o 256506/b165/_x00-extld=gcc` (dns block)
> - `slow.example.com`
> - Triggering command: `/tmp/go-build1870635187/b275/launcher.test
/tmp/go-build1870635187/b275/launcher.test
-test.testlogfile=/tmp/go-build1870635187/b275/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true ain cfg s.test
--gdwarf-5 --64 -o s.test 6525�� ache/go/1.25.7/x-s -I 86_64/git
--gdwarf-5 --64 -o 256506/b165/_x00-extld=gcc` (dns block)
> - `this-host-does-not-exist-12345.com`
> - Triggering command: `/tmp/go-build1870635187/b284/mcp.test
/tmp/go-build1870635187/b284/mcp.test
-test.testlogfile=/tmp/go-build1870635187/b284/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true
rverConfigWithCustomSchemas 256506/b082/vet.cfg cfg --gdwarf-5
ut-2576538208.c -o ache/go/1.25.7/x-importcfg` (dns block)
> - Triggering command: `/tmp/go-build3437160695/b284/mcp.test
/tmp/go-build3437160695/b284/mcp.test
-test.testlogfile=/tmp/go-build3437160695/b284/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true -c=4 -nolocalimports
-importcfg /tmp/go-build1870635187/b305/importcfg -pack
/home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/internal/version/version.go
/home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/internal/version/version_test.go
-qui�� ain /opt/hostedtoolcache/go/1.25.7/x64/src/net x_amd64/compile
/tmp/go-build165/opt/hostedtoolcache/go/1.25.7/x64/pkg/tool/linux_amd64/compile
-imultiarch x86_64-linux-gnu/tmp/go-build1870635187/b306/_pkg_.a
x_amd64/compile` (dns block)
> - Triggering command: `/tmp/go-build880157664/b284/mcp.test
/tmp/go-build880157664/b284/mcp.test
-test.testlogfile=/tmp/go-build880157664/b284/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true
C77u/Ma68ZNCRMnumNFLzC77u /tmp/go-build165256506/b065/vet.cfg
k/_temp/ghcca-node/node/bin/sh go1.25.7 -c=4 -nolocalimports
256506/b258/importcfg -plu�� celain --ignore-submodules | head -n 10
nction

Co-authored-by: lpcox
&lt;15877973&#43;lpcox@users.noreply.github.com&gt; 64/bin/git
-plugin-opt=-pas/usr/libexec/docker/cli-plugins/docker-buildx
-plugin-opt=-pasdocker-cli-plugin-metadata
-plugin-opt=-pass-through=-lpthr(create|run)
/opt/hostedtoolcache/go/1.25.7/x64/pkg/tool/linux_amd64/vet` (dns block)
>
> If you need me to access, download, or install something from one of
these locations, you can either:
>
> - Configure [Actions setup
steps](https://gh.io/copilot/actions-setup-steps) to set up my
environment, which run before the firewall is enabled
> - Add the appropriate URLs or hosts to the custom allowlist in this
repository's [Copilot coding agent
settings](https://github.com/github/gh-aw-mcpg/settings/copilot/coding_agent)
(admins only)
>
> </details>

<!-- START COPILOT ORIGINAL PROMPT -->



<details>

<summary>Original prompt</summary>


----

*This section details on the original issue you should resolve*

<issue_title>[refactor] Semantic Function Clustering Analysis - Code
Organization & Refactoring Opportunities</issue_title>
<issue_description>## Executive Summary

Analyzed **63 Go source files** (excluding tests) across **16 packages**
containing **~450 functions** to identify refactoring opportunities
through semantic function clustering and duplicate detection.

**Key Findings:**
- ✅ **Overall code quality is excellent** - well-organized with strong
use of Go patterns
- 🔧 **8 high-priority refactoring opportunities** identified (duplicate
logic, misplaced functions)
- 📊 **Function clusters are generally well-organized** by file purpose
- ⚠️ **Minor inconsistencies** in naming patterns and file organization

**Analysis covered:**
- 16 packages in `internal/` directory
- Pattern analysis using semantic clustering
- Duplicate detection across files
- File organization validation

---

## Package Overview

### Files by Package

| Package | Files | Primary Purpose |
|---------|-------|----------------|
| **logger** | 14 | Debug logging framework, file/markdown/JSONL
logging, RPC logging |
| **server** | 10 | HTTP server (routed/unified modes), handlers,
middleware |
| **config** | 8 | Configuration parsing (TOML/JSON), validation,
variable expansion |
| **cmd** | 7 | CLI (Cobra), flag management, completions |
| **difc** | 5 | Data Information Flow Control labels and evaluation |
| **guard** | 4 | Security guard framework and registry |
| **testutil/mcptest** | 4 | Test utilities for MCP integration |
| **launcher** | 3 | Backend process management and connection pooling |
| **mcp** | 2 | MCP protocol types and connections |
| **tty** | 2 | Terminal detection utilities |
| **auth** | 1 | Authentication header parsing |
| **envutil** | 1 | Environment variable utilities |
| **middleware** | 1 | HTTP middleware (jq schema processing) |
| **sys** | 1 | System utilities |
| **timeutil** | 1 | Time formatting utilities |
| **version** | 1 | Version management |

---

## Identified Issues

### Priority 1: High-Impact Refactoring

#### 1. **Duplicate Auth Middleware Application** (server package)

**Issue**: Auth middleware is applied with identical pattern in two
places.

**Location**: `internal/server/transport.go:120-122` and `137-139`

**Current Code Pattern**:
````go
// Pattern repeated twice
finalHandler := shutdownHandler
if apiKey != "" {
    finalHandler = authMiddleware(apiKey, shutdownHandler.ServeHTTP)
}

finalCloseHandler := closeHandler
if apiKey != "" {
    finalCloseHandler = authMiddleware(apiKey, closeHandler.ServeHTTP)
}
````

**Recommendation**: Extract to helper function
````go
func applyAuthIfConfigured(apiKey string, handler http.HandlerFunc) http.HandlerFunc {
    if apiKey != "" {
        return authMiddleware(apiKey, handler)
    }
    return handler
}

// Usage
finalHandler := applyAuthIfConfigured(apiKey, shutdownHandler)
finalCloseHandler := applyAuthIfConfigured(apiKey, closeHandler)
````

**Estimated Impact**: Reduced duplication, easier maintenance  
**Effort**: 30 minutes

---

#### 2. **Misplaced Generic Logging Function** (server package)

**Issue**: Generic runtime error logging function is in auth-specific
file.

**Function**: `logRuntimeError()` in `internal/server/auth.go`

**Problem**: This function logs generic runtime errors and panics, not
authentication-specific errors.

**Current Location**: `internal/server/auth.go` (lines ~50-60)

**Recommendation**: Move to `internal/server/server.go` or create
`internal/server/errors.go` for error handling utilities.

**Estimated Impact**: Improved code organization, clearer file purpose  
**Effort**: 15 minutes

---

#### 3. **Large Schema Normalization Function in Types File** (mcp
package)

**Issue**: 86-line schema normalization logic mixed with type
definitions.

**Function**: `NormalizeInputSchema()` in `internal/mcp/types.go`

**Problem**: `types.go` should contain simple type definitions, not
complex transformation logic.

**Current**: 86 lines of schema transformation logic in types.go  
**Better**: Extract to `internal/mcp/schema.go` or
`internal/mcp/normalize.go`

**Recommendation**:
1. Create `internal/mcp/schema.go`
2. Move `NormalizeInputSchema()` to new file
3. Keep only type definitions in `types.go`

**Estimated Impact**: Clearer separation of concerns, easier to test  
**Effort**: 20 minutes

---

#### 4. **Unnecessary Validation Wrapper Function** (config package)

**Issue**: Thin wrapper function that adds no value.

**Function**: `validateServerConfig()` in
`internal/config/validation.go:104-106`

**Current Code**:
````go
func validateServerConfig(name string, srv ServerConfig, cfg *Config) error {
    return validateServerConfigWithCustomSchemas(name, srv, cfg, nil)
}
````

**Problem**: This wrapper just calls the main function with `nil` as the
last parameter.

**Recommendation**: Remove wrapper, call
`validateServerConfigWithCustomSchem...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes #1064

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for
you](https://github.com/github/gh-aw-mcpg/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot)
— coding agent works faster and does higher quality work when set up for
your repo.

Author: lpcox

internal/config/validation.go

@@ -100,11 +100,6 @@ func validateMounts(mounts []string, jsonPath string) error {
 	return nil
 }
 
-// validateServerConfig validates a server configuration (stdio or HTTP)
-func validateServerConfig(name string, server *StdinServerConfig) error {
-	return validateServerConfigWithCustomSchemas(name, server, nil)
-}
-
 // validateServerConfigWithCustomSchemas validates a server configuration with custom schema support
 func validateServerConfigWithCustomSchemas(name string, server *StdinServerConfig, customSchemas map[string]interface{}) error {
 	logValidation.Printf("Validating server config: name=%s, type=%s", name, server.Type)

internal/config/validation_test.go

@@ -352,7 +352,7 @@ func TestValidateStdioServer(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			err := validateServerConfig("test-server", tt.server)
+			err := validateServerConfigWithCustomSchemas("test-server", tt.server, nil)
 
 			if tt.shouldErr {
 				require.Error(t, err)

internal/mcp/schema.go

@@ -0,0 +1,89 @@
+package mcp
+
+import (
+	"github.com/github/gh-aw-mcpg/internal/logger"
+)
+
+var logSchema = logger.New("mcp:schema")
+
+// NormalizeInputSchema ensures tool input schemas are valid for the MCP SDK
+// The MCP SDK requires that object type schemas have a "properties" field,
+// even if it's empty. This function normalizes schemas to meet that requirement.
+//
+// Returns a normalized copy of the schema, never modifies the original.
+func NormalizeInputSchema(schema map[string]interface{}, toolName string) map[string]interface{} {
+	logSchema.Printf("Normalizing input schema for tool: %s", toolName)
+
+	// If backend didn't provide a schema, use a default empty object schema
+	// This allows the tool to be registered and clients will see it accepts any parameters
+	if schema == nil {
+		logSchema.Printf("Tool %s has nil schema, applying default empty object schema", toolName)
+		logger.LogWarn("backend", "Tool schema normalized: %s - backend provided no inputSchema, using default empty object schema", toolName)
+		return map[string]interface{}{
+			"type":       "object",
+			"properties": map[string]interface{}{},
+		}
+	}
+
+	// Check if this is an object type schema
+	typeVal, hasType := schema["type"]
+
+	logSchema.Printf("Tool %s schema analysis: hasType=%v", toolName, hasType)
+
+	// If schema has no type but has properties, it's implicitly an object type
+	// The MCP SDK requires "type": "object" to be present, so add it
+	if !hasType {
+		_, hasProperties := schema["properties"]
+		logSchema.Printf("Tool %s has no type field, hasProperties=%v", toolName, hasProperties)
+		if hasProperties {
+			logger.LogWarn("backend", "Tool schema normalized: %s - added 'type': 'object' to schema with properties", toolName)
+			// Create a copy of the schema to avoid modifying the original
+			normalized := make(map[string]interface{})
+			for k, v := range schema {
+				normalized[k] = v
+			}
+			normalized["type"] = "object"
+			logSchema.Printf("Tool %s schema normalized: added object type", toolName)
+			return normalized
+		}
+		// Schema without type and without properties - assume it's an empty object schema
+		logSchema.Printf("Tool %s has no type and no properties, using empty object schema", toolName)
+		logger.LogWarn("backend", "Tool schema normalized: %s - schema missing type, assuming empty object schema", toolName)
+		return map[string]interface{}{
+			"type":       "object",
+			"properties": map[string]interface{}{},
+		}
+	}
+
+	typeStr, isString := typeVal.(string)
+	if !isString || typeStr != "object" {
+		logSchema.Printf("Tool %s has non-object type or invalid type value, returning schema as-is", toolName)
+		return schema
+	}
+
+	// Check if properties field exists
+	_, hasProperties := schema["properties"]
+	_, hasAdditionalProperties := schema["additionalProperties"]
+
+	logSchema.Printf("Tool %s object type schema: hasProperties=%v, hasAdditionalProperties=%v",
+		toolName, hasProperties, hasAdditionalProperties)
+
+	// If it's an object type but missing both properties and additionalProperties,
+	// add an empty properties object to make it valid
+	if !hasProperties && !hasAdditionalProperties {
+		logger.LogWarn("backend", "Tool schema normalized: %s - added empty properties to object type schema", toolName)
+
+		// Create a copy of the schema to avoid modifying the original
+		normalized := make(map[string]interface{})
+		for k, v := range schema {
+			normalized[k] = v
+		}
+		normalized["properties"] = map[string]interface{}{}
+
+		logSchema.Printf("Tool %s schema normalized: added empty properties field", toolName)
+		return normalized
+	}
+
+	logSchema.Printf("Tool %s schema is valid, no normalization needed", toolName)
+	return schema
+}

internal/mcp/types.go

@@ -2,12 +2,8 @@ package mcp
 
 import (
 	"encoding/json"
-
-	"github.com/github/gh-aw-mcpg/internal/logger"
 )
 
-var logTypes = logger.New("mcp:types")
-
 // Request represents a JSON-RPC 2.0 request
 type Request struct {
 	JSONRPC string          `json:"jsonrpc"`
@@ -49,90 +45,3 @@ type ContentItem struct {
 	Type string `json:"type"`
 	Text string `json:"text,omitempty"`
 }
-
-// NormalizeInputSchema fixes common schema validation issues in tool definitions
-// that can cause downstream validation errors.
-//
-// Known issues fixed:
-//  1. Missing schema: When a backend returns no inputSchema (nil), we provide
-//     a default empty object schema that accepts any properties. This is required
-//     by the MCP SDK's Server.AddTool method.
-//  2. Object schemas without properties: When a schema declares "type": "object"
-//     but is missing the required "properties" field, we add an empty properties
-//     object to make it valid per JSON Schema standards.
-func NormalizeInputSchema(schema map[string]interface{}, toolName string) map[string]interface{} {
-	logTypes.Printf("Normalizing input schema for tool: %s", toolName)
-
-	// If backend didn't provide a schema, use a default empty object schema
-	// This allows the tool to be registered and clients will see it accepts any parameters
-	if schema == nil {
-		logTypes.Printf("Tool %s has nil schema, applying default empty object schema", toolName)
-		logger.LogWarn("backend", "Tool schema normalized: %s - backend provided no inputSchema, using default empty object schema", toolName)
-		return map[string]interface{}{
-			"type":       "object",
-			"properties": map[string]interface{}{},
-		}
-	}
-
-	// Check if this is an object type schema
-	typeVal, hasType := schema["type"]
-
-	logTypes.Printf("Tool %s schema analysis: hasType=%v", toolName, hasType)
-
-	// If schema has no type but has properties, it's implicitly an object type
-	// The MCP SDK requires "type": "object" to be present, so add it
-	if !hasType {
-		_, hasProperties := schema["properties"]
-		logTypes.Printf("Tool %s has no type field, hasProperties=%v", toolName, hasProperties)
-		if hasProperties {
-			logger.LogWarn("backend", "Tool schema normalized: %s - added 'type': 'object' to schema with properties", toolName)
-			// Create a copy of the schema to avoid modifying the original
-			normalized := make(map[string]interface{})
-			for k, v := range schema {
-				normalized[k] = v
-			}
-			normalized["type"] = "object"
-			logTypes.Printf("Tool %s schema normalized: added object type", toolName)
-			return normalized
-		}
-		// Schema without type and without properties - assume it's an empty object schema
-		logTypes.Printf("Tool %s has no type and no properties, using empty object schema", toolName)
-		logger.LogWarn("backend", "Tool schema normalized: %s - schema missing type, assuming empty object schema", toolName)
-		return map[string]interface{}{
-			"type":       "object",
-			"properties": map[string]interface{}{},
-		}
-	}
-
-	typeStr, isString := typeVal.(string)
-	if !isString || typeStr != "object" {
-		logTypes.Printf("Tool %s has non-object type or invalid type value, returning schema as-is", toolName)
-		return schema
-	}
-
-	// Check if properties field exists
-	_, hasProperties := schema["properties"]
-	_, hasAdditionalProperties := schema["additionalProperties"]
-
-	logTypes.Printf("Tool %s object type schema: hasProperties=%v, hasAdditionalProperties=%v",
-		toolName, hasProperties, hasAdditionalProperties)
-
-	// If it's an object type but missing both properties and additionalProperties,
-	// add an empty properties object to make it valid
-	if !hasProperties && !hasAdditionalProperties {
-		logger.LogWarn("backend", "Tool schema normalized: %s - added empty properties to object type schema", toolName)
-
-		// Create a copy of the schema to avoid modifying the original
-		normalized := make(map[string]interface{})
-		for k, v := range schema {
-			normalized[k] = v
-		}
-		normalized["properties"] = map[string]interface{}{}
-
-		logTypes.Printf("Tool %s schema normalized: added empty properties field", toolName)
-		return normalized
-	}
-
-	logTypes.Printf("Tool %s schema is valid, no normalization needed", toolName)
-	return schema
-}

internal/server/auth.go

@@ -1,9 +1,7 @@
 package server
 
 import (
-	"log"
 	"net/http"
-	"time"
 
 	"github.com/github/gh-aw-mcpg/internal/logger"
 )
@@ -48,23 +46,3 @@ func authMiddleware(apiKey string, next http.HandlerFunc) http.HandlerFunc {
 		next(w, r)
 	}
 }
-
-// logRuntimeError logs runtime errors to stdout per spec section 9.2
-func logRuntimeError(errorType, detail string, r *http.Request, serverName *string) {
-	logAuth.Printf("Logging runtime error: type=%s, detail=%s", errorType, detail)
-
-	timestamp := time.Now().UTC().Format(time.RFC3339)
-	requestID := r.Header.Get("X-Request-ID")
-	if requestID == "" {
-		requestID = "unknown"
-	}
-
-	server := "gateway"
-	if serverName != nil {
-		server = *serverName
-	}
-
-	// Spec 9.2: Log to stdout with timestamp, server name, request ID, error details
-	log.Printf("[ERROR] timestamp=%s server=%s request_id=%s error_type=%s detail=%s path=%s method=%s",
-		timestamp, server, requestID, errorType, detail, r.URL.Path, r.Method)
-}

internal/server/errors.go

@@ -0,0 +1,31 @@
+package server
+
+import (
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/github/gh-aw-mcpg/internal/logger"
+)
+
+var logErrors = logger.New("server:errors")
+
+// logRuntimeError logs runtime errors to stdout per spec section 9.2
+func logRuntimeError(errorType, detail string, r *http.Request, serverName *string) {
+	logErrors.Printf("Logging runtime error: type=%s, detail=%s", errorType, detail)
+
+	timestamp := time.Now().UTC().Format(time.RFC3339)
+	requestID := r.Header.Get("X-Request-ID")
+	if requestID == "" {
+		requestID = "unknown"
+	}
+
+	server := "gateway"
+	if serverName != nil {
+		server = *serverName
+	}
+
+	// Spec 9.2: Log to stdout with timestamp, server name, request ID, error details
+	log.Printf("[ERROR] timestamp=%s server=%s request_id=%s error_type=%s detail=%s path=%s method=%s",
+		timestamp, server, requestID, errorType, detail, r.URL.Path, r.Method)
+}

internal/server/transport.go

@@ -56,6 +56,15 @@ func withResponseLogging(handler http.Handler) http.Handler {
 	})
 }
 
+// applyAuthIfConfigured applies authentication middleware if an API key is provided
+// Returns the handler unchanged if apiKey is empty
+func applyAuthIfConfigured(apiKey string, handler http.HandlerFunc) http.HandlerFunc {
+	if apiKey != "" {
+		return authMiddleware(apiKey, handler)
+	}
+	return handler
+}
+
 // CreateHTTPServerForMCP creates an HTTP server that handles MCP over streamable HTTP transport
 // If apiKey is provided, all requests except /health require authentication (spec 7.1)
 func CreateHTTPServerForMCP(addr string, unifiedServer *UnifiedServer, apiKey string) *http.Server {
@@ -116,10 +125,7 @@ func CreateHTTPServerForMCP(addr string, unifiedServer *UnifiedServer, apiKey st
 	shutdownHandler := rejectIfShutdown(unifiedServer, loggedHandler, "server:transport")
 
 	// Apply auth middleware if API key is configured (spec 7.1)
-	finalHandler := shutdownHandler
-	if apiKey != "" {
-		finalHandler = authMiddleware(apiKey, shutdownHandler.ServeHTTP)
-	}
+	finalHandler := applyAuthIfConfigured(apiKey, shutdownHandler.ServeHTTP)
 
 	// Mount handler at /mcp endpoint (logging is done in the callback above)
 	mux.Handle("/mcp/", finalHandler)
@@ -133,10 +139,7 @@ func CreateHTTPServerForMCP(addr string, unifiedServer *UnifiedServer, apiKey st
 	closeHandler := handleClose(unifiedServer)
 
 	// Apply auth middleware if API key is configured (spec 7.1)
-	finalCloseHandler := closeHandler
-	if apiKey != "" {
-		finalCloseHandler = authMiddleware(apiKey, closeHandler.ServeHTTP)
-	}
+	finalCloseHandler := applyAuthIfConfigured(apiKey, closeHandler.ServeHTTP)
 	mux.Handle("/close", withResponseLogging(finalCloseHandler))
 
 	return &http.Server{