Skip to content

Conversation

JAORMX
Copy link
Collaborator

@JAORMX JAORMX commented Oct 15, 2025

Summary

This PR introduces a proposal for adding MCPGroup support to the Kubernetes operator, enabling the Virtual MCP Server feature and logical grouping of MCPServer resources.

What does this PR do?

Adds a technical proposal document that outlines the design for MCPGroup Custom Resource Definition (CRD) in the Kubernetes operator.

Key Design Decisions

  • Explicit group field: Adds group field to MCPServer spec (matches CLI Workload.Group behavior)
  • Simple CRD: MCPGroup has minimal spec (just description), with status tracking servers
  • Namespace-scoped: Groups only select servers in the same namespace for security/isolation
  • Field selector support: Enables queries like spec.group=engineering-team
  • No client tracking: Removed RegisteredClients field (not applicable in K8s)

Why This Design?

  1. API consistency: Matches CLI runtime group behavior where workloads have explicit group membership
  2. Simplicity: Explicit spec.group field is predictable and easy to query
  3. Virtual MCP enablement: Required for PR Add Virtual MCP Server proposal #2106's Virtual MCP Server feature to discover backend servers
  4. Kubernetes-native: Follows standard patterns while keeping implementation simple

Benefits

  • Enables Virtual MCP Server aggregation in Kubernetes
  • Provides logical organization of MCPServer resources
  • Maintains consistency with CLI group concepts
  • Simple to implement and use

Related Issues

Copy link

codecov bot commented Oct 15, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 52.99%. Comparing base (71e2934) to head (254f920).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #2207   +/-   ##
=======================================
  Coverage   52.99%   52.99%           
=======================================
  Files         223      223           
  Lines       29057    29057           
=======================================
  Hits        15399    15399           
  Misses      12534    12534           
  Partials     1124     1124           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

eleftherias
eleftherias previously approved these changes Oct 15, 2025
@JAORMX
Copy link
Collaborator Author

JAORMX commented Oct 15, 2025

@eleftherias we can probably create a default group in k8s too; We can add a default group in the CRD and that would be fine. so if you don't specify one and existing MCPServers will belong to the default group.

I think one issue is going to be namespaces though.... meaning, two groups of the same name in different namespaces are going to effectively be different. I don't think we should support cross-namespace references as that will complicate things a lot.

dmjb
dmjb previously approved these changes Oct 15, 2025
This proposal introduces MCPGroup support to the Kubernetes operator,
enabling Virtual MCP Server and logical grouping of MCPServer resources.

Key design decisions:
- Explicit groupRef field in MCPServer spec (follows K8s naming conventions)
- Simple MCPGroup CRD with minimal spec (description) and status tracking
- Namespace-scoped groups for security/isolation
- No webhooks - controller-based validation for simplicity
- Optional group membership (unlike CLI where groups are required)

Design rationale:
- MCPGroup as first-class construct (not just labels) enables meta-mcp
  and virtual MCP to discover and aggregate backend servers
- Provides seamless CLI-to-Kubernetes transition with consistent API
- Explicit group lifecycle management and validation
- Foundation for growing ecosystem of ToolHive constructs

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

Co-Authored-By: Claude <[email protected]>
@JAORMX JAORMX dismissed stale reviews from dmjb and eleftherias via 254f920 October 15, 2025 11:25
@JAORMX JAORMX force-pushed the add-mcpgroup-proposal branch from ec430e1 to 254f920 Compare October 15, 2025 11:25
@JAORMX
Copy link
Collaborator Author

JAORMX commented Oct 15, 2025

Thanks for the thorough review, @ChrisJBurns! I've addressed all your feedback:

  1. Changed group to groupRef throughout to follow K8s naming conventions
  2. Fixed "Cluster-scoped" to "Namespace-scoped" in the Migration section
  3. Removed webhook recommendations - now using controller reconciliation with status conditions (much simpler!)
  4. Added note that MCPVirtualServer is just an example of future API
  5. Added standalone MCPServer example (without group) as the primary example

Regarding your excellent question about labels vs CRD - you're absolutely right to ask! I've added a section explaining the reasoning:

Main drivers:

  • Meta-MCP and Virtual MCP need to aggregate multiple MCP servers and discover group membership
  • Seamless CLI to K8s transition - CLI has explicit Groups, and we want the same mental model
  • Groups as a core concept in ToolHive's architecture (not just ad-hoc labels)

While labels could work technically, they lack discoverability, metadata storage, and explicit lifecycle management that these aggregation features need.

Also added a note about the CLI difference that @eleftherias mentioned - CLI requires groups (with default), K8s makes them optional.

Let me know if you'd like any other changes!

@JAORMX JAORMX merged commit 73707af into main Oct 15, 2025
27 checks passed
@JAORMX JAORMX deleted the add-mcpgroup-proposal branch October 15, 2025 12:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants