Rename MCPServer CRD port attributes for clarity

- Rename `port` to `proxyPort` - represents proxy runner port
- Rename `targetPort` to `mcpPort` - represents MCP server port

This change addresses user confusion about port semantics as discussed
in issue #1452. The new names clearly indicate which port corresponds
to which component:
- proxyPort: Port exposed by the proxy runner in Kubernetes
- mcpPort: Port that the MCP server listens on internally

Updated all relevant files:
- CRD types definition and generated YAML
- Operator controller logic
- All example and test YAML files
- Keycloak deployment example

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: Chris Burns <[email protected]>

Author: claude[bot]

cmd/thv-operator/api/v1alpha1/mcpserver_types.go

@@ -16,17 +16,17 @@ type MCPServerSpec struct {
 	// +kubebuilder:default=stdio
 	Transport string `json:"transport,omitempty"`
 
-	// Port is the port to expose the MCP server on
+	// ProxyPort is the port to expose the proxy runner on
 	// +kubebuilder:validation:Minimum=1
 	// +kubebuilder:validation:Maximum=65535
 	// +kubebuilder:default=8080
-	Port int32 `json:"port,omitempty"`
+	ProxyPort int32 `json:"proxyPort,omitempty"`
 
-	// TargetPort is the port that MCP server listens to
+	// McpPort is the port that MCP server listens to
 	// +kubebuilder:validation:Minimum=1
 	// +kubebuilder:validation:Maximum=65535
 	// +optional
-	TargetPort int32 `json:"targetPort,omitempty"`
+	McpPort int32 `json:"mcpPort,omitempty"`
 
 	// Args are additional arguments to pass to the MCP server
 	// +optional

cmd/thv-operator/controllers/mcpserver_controller.go

@@ -214,7 +214,7 @@ func (r *MCPServerReconciler) Reconcile(ctx context.Context, req ctrl.Request) (
 
 	// Update the MCPServer status with the service URL
 	if mcpServer.Status.URL == "" {
-		mcpServer.Status.URL = createServiceURL(mcpServer.Name, mcpServer.Namespace, mcpServer.Spec.Port)
+		mcpServer.Status.URL = createServiceURL(mcpServer.Name, mcpServer.Namespace, mcpServer.Spec.ProxyPort)
 		err = r.Status().Update(ctx, mcpServer)
 		if err != nil {
 			ctxLogger.Error(err, "Failed to update MCPServer status")
@@ -407,13 +407,13 @@ func (r *MCPServerReconciler) deploymentForMCPServer(m *mcpv1alpha1.MCPServer) *
 
 	// Prepare container args
 	args := []string{"run", "--foreground=true"}
-	args = append(args, fmt.Sprintf("--proxy-port=%d", m.Spec.Port))
+	args = append(args, fmt.Sprintf("--proxy-port=%d", m.Spec.ProxyPort))
 	args = append(args, fmt.Sprintf("--name=%s", m.Name))
 	args = append(args, fmt.Sprintf("--transport=%s", m.Spec.Transport))
 	args = append(args, fmt.Sprintf("--host=%s", getProxyHost()))
 
-	if m.Spec.TargetPort != 0 {
-		args = append(args, fmt.Sprintf("--target-port=%d", m.Spec.TargetPort))
+	if m.Spec.McpPort != 0 {
+		args = append(args, fmt.Sprintf("--target-port=%d", m.Spec.McpPort))
 	}
 
 	// Generate pod template patch for secrets and merge with user-provided patch
@@ -454,7 +454,7 @@ func (r *MCPServerReconciler) deploymentForMCPServer(m *mcpv1alpha1.MCPServer) *
 		// Add OAuth discovery resource URL for RFC 9728 compliance
 		resourceURL := m.Spec.OIDCConfig.ResourceURL
 		if resourceURL == "" {
-			resourceURL = createServiceURL(m.Name, m.Namespace, m.Spec.Port)
+			resourceURL = createServiceURL(m.Name, m.Namespace, m.Spec.ProxyPort)
 		}
 		args = append(args, fmt.Sprintf("--resource-url=%s", resourceURL))
 	}
@@ -626,7 +626,7 @@ func (r *MCPServerReconciler) deploymentForMCPServer(m *mcpv1alpha1.MCPServer) *
 						VolumeMounts: volumeMounts,
 						Resources:    resources,
 						Ports: []corev1.ContainerPort{{
-							ContainerPort: m.Spec.Port,
+							ContainerPort: m.Spec.ProxyPort,
 							Name:          "http",
 							Protocol:      corev1.ProtocolTCP,
 						}},
@@ -753,8 +753,8 @@ func (r *MCPServerReconciler) serviceForMCPServer(m *mcpv1alpha1.MCPServer) *cor
 		Spec: corev1.ServiceSpec{
 			Selector: ls, // Keep original labels for selector
 			Ports: []corev1.ServicePort{{
-				Port:       m.Spec.Port,
-				TargetPort: intstr.FromInt(int(m.Spec.Port)),
+				Port:       m.Spec.ProxyPort,
+				TargetPort: intstr.FromInt(int(m.Spec.ProxyPort)),
 				Protocol:   corev1.ProtocolTCP,
 				Name:       "http",
 			}},
@@ -884,7 +884,7 @@ func deploymentNeedsUpdate(deployment *appsv1.Deployment, mcpServer *mcpv1alpha1
 		}
 
 		// Check if the port has changed
-		portArg := fmt.Sprintf("--proxy-port=%d", mcpServer.Spec.Port)
+		portArg := fmt.Sprintf("--proxy-port=%d", mcpServer.Spec.ProxyPort)
 		found = false
 		for _, arg := range container.Args {
 			if arg == portArg {
@@ -937,7 +937,7 @@ func deploymentNeedsUpdate(deployment *appsv1.Deployment, mcpServer *mcpv1alpha1
 		}
 
 		// Check if the container port has changed
-		if len(container.Ports) > 0 && container.Ports[0].ContainerPort != mcpServer.Spec.Port {
+		if len(container.Ports) > 0 && container.Ports[0].ContainerPort != mcpServer.Spec.ProxyPort {
 			return true
 		}
 
@@ -1009,12 +1009,12 @@ func deploymentNeedsUpdate(deployment *appsv1.Deployment, mcpServer *mcpv1alpha1
 			return true
 		}
 
-		// Check if the targetPort has changed
-		if mcpServer.Spec.TargetPort != 0 {
-			targetPortArg := fmt.Sprintf("--target-port=%d", mcpServer.Spec.TargetPort)
+		// Check if the mcpPort has changed
+		if mcpServer.Spec.McpPort != 0 {
+			mcpPortArg := fmt.Sprintf("--target-port=%d", mcpServer.Spec.McpPort)
 			found := false
 			for _, arg := range container.Args {
-				if arg == targetPortArg {
+				if arg == mcpPortArg {
 					found = true
 					break
 				}
@@ -1067,7 +1067,7 @@ func deploymentNeedsUpdate(deployment *appsv1.Deployment, mcpServer *mcpv1alpha1
 // serviceNeedsUpdate checks if the service needs to be updated
 func serviceNeedsUpdate(service *corev1.Service, mcpServer *mcpv1alpha1.MCPServer) bool {
 	// Check if the service port has changed
-	if len(service.Spec.Ports) > 0 && service.Spec.Ports[0].Port != mcpServer.Spec.Port {
+	if len(service.Spec.Ports) > 0 && service.Spec.Ports[0].Port != mcpServer.Spec.ProxyPort {
 		return true
 	}
 

deploy/charts/operator-crds/templates/toolhive.stacklok.dev_mcpservers.yaml

@@ -8303,9 +8303,9 @@ spec:
                     - containers
                     type: object
                 type: object
-              port:
+              proxyPort:
                 default: 8080
-                description: Port is the port to expose the MCP server on
+                description: ProxyPort is the port to expose the proxy runner on
                 format: int32
                 maximum: 65535
                 minimum: 1
@@ -8422,8 +8422,8 @@ spec:
                   ServiceAccount is the name of an already existing service account to use by the MCP server.
                   If not specified, a ServiceAccount will be created automatically and used by the MCP server.
                 type: string
-              targetPort:
-                description: TargetPort is the port that MCP server listens to
+              mcpPort:
+                description: McpPort is the port that MCP server listens to
                 format: int32
                 maximum: 65535
                 minimum: 1

deploy/keycloak/mcpserver-with-auth.yaml

@@ -13,8 +13,8 @@ spec:
         - name: INSECURE_DISABLE_URL_VALIDATION
           value: "true"
   transport: streamable-http
-  port: 9090
-  targetPort: 9090
+  proxyPort: 9090
+  mcpPort: 9090
   env:
 
   # OIDC authentication with Keycloak

examples/operator/mcp-servers/mcpserver_fetch.yaml

@@ -6,8 +6,8 @@ metadata:
 spec:
   image: ghcr.io/stackloklabs/gofetch/server
   transport: streamable-http
-  port: 8080
-  targetPort: 8080
+  proxyPort: 8080
+  mcpPort: 8080
   permissionProfile:
     type: builtin
     name: network

examples/operator/mcp-servers/mcpserver_fetch_tools_filter.yaml

@@ -8,8 +8,8 @@ spec:
   transport: streamable-http
   tools:
     - fetch
-  port: 8080
-  targetPort: 8080
+  proxyPort: 8080
+  mcpPort: 8080
   permissionProfile:
     type: builtin
     name: network

examples/operator/mcp-servers/mcpserver_github.yaml

@@ -6,7 +6,7 @@ metadata:
 spec:
   image: ghcr.io/github/github-mcp-server
   transport: stdio
-  port: 8080
+  proxyPort: 8080
   permissionProfile:
     type: builtin
     name: network

examples/operator/mcp-servers/mcpserver_mkp.yaml

@@ -6,7 +6,7 @@ metadata:
 spec:
   image: ghcr.io/stackloklabs/mkp/server
   transport: sse
-  port: 8080
+  proxyPort: 8080
   permissionProfile:
     type: builtin
     name: network

examples/operator/mcp-servers/mcpserver_with_configmap_oidc.yaml

@@ -17,7 +17,7 @@ metadata:
 spec:
   image: docker.io/mcp/fetch
   transport: stdio
-  port: 8080
+  proxyPort: 8080
   permissionProfile:
     type: builtin
     name: network

examples/operator/mcp-servers/mcpserver_with_inline_oidc.yaml

@@ -6,7 +6,7 @@ metadata:
 spec:
   image: docker.io/mcp/fetch
   transport: stdio
-  port: 8080
+  proxyPort: 8080
   permissionProfile:
     type: builtin
     name: network