Rename the port attributes in the MCPServer CRD to mcpPort and proxyPort

[jhrozek]

background

This issue captures a discussion about how to make the CRD port attributes less confusing. At the moment we have port which pertains to the service and the proxy runner and targetPort which pertains to the headless service and the MCP server. It is confusing to our users.

proposal

mcpPort - would pertain to the MCP server and the headless service. Defaults to a randomized value that gets propagated to the MCP server via the MCP_SERVER and FASTMCP_PORT environment variables
proxyPort - port that the proxy runs on and is exposed in Kubernetes

[jhrozek]

See e.g. #1431 (comment)

[jhrozek]

Also note that many SDKs honor the MCP_PORT variable already, the go SDK doesn't seem to though

[Cali0707]

+1 from me - this would resolve my confusion

[matzew]

I like this idea, @jhrozek

[ChrisJBurns]

@claude Can you go through the codebase and address the issue in the above. Bare in mind, this only concerns the operator and the proxy-runner

[claude]

Claude finished @ChrisJBurns's task —— View job • claude/issue-1452-20250827-1021 • Create PR ➔

---

I'll help you rename the port attributes in the MCPServer CRD to make them less confusing. Let me work through this systematically.

Tasks

• Analyze the current MCPServer CRD structure and find all references
• Update CRD definition to use mcpPort and proxyPort instead of port and targetPort
• Update operator controller logic to use new attribute names
• Update proxy-runner code to use new attribute names
• Update any test files that reference the old attributes
• Run linting and tests to ensure changes work correctly
• Commit and push changes
• Provide PR creation link

Analysis

I found the current structure in the MCPServer CRD:

• port (line 19-23): Port to expose the MCP server on - used for proxy service
• targetPort (line 25-29): Port that MCP server listens to - used for headless service

Based on the issue description:

• port → proxyPort (proxy runner port, exposed in Kubernetes)
• targetPort → mcpPort (MCP server port, used with headless service)

Summary of Changes

✅ CRD Types: Updated mcpserver_types.go to rename fields
✅ Controller Logic: Updated all references in mcpserver_controller.go
✅ Generated CRD: Updated YAML schema definition
✅ Examples: Updated 12 example YAML files
✅ Tests: Updated 6 test scenario files
✅ Keycloak: Updated deployment example

All changes maintain backward compatibility in the CLI flags (the operator still passes --target-port to the proxy runner as expected).

Create Pull Request