RFC-0055: MCPServerEntry CRD for Direct Remote MCP Server Backends

[JAORMX]

Summary

Introduces MCPServerEntry, a new lightweight CRD (short name: mcpentry) that allows VirtualMCPServer to connect directly to remote MCP servers without deploying MCPRemoteProxy infrastructure. MCPServerEntry is a pod-less configuration resource that declares a remote MCP endpoint and belongs to an MCPGroup.

Motivation

vMCP currently requires MCPRemoteProxy (which spawns thv-proxyrunner pods) to reach remote MCP servers. This creates three problems:

1. Forced auth on public remotes (#3104): MCPRemoteProxy requires OIDC even when vMCP already handles client auth
2. Dual auth boundary confusion (#4109): externalAuthConfigRef serves two conflicting purposes (vMCP-to-proxy AND proxy-to-remote)
3. Resource waste: Every remote backend needs a Deployment + Service + Pod just to make an HTTP call

Design Highlights

• Zero infrastructure: MCPServerEntry deploys no pods, services, or deployments — pure configuration
• Single auth boundary: externalAuthConfigRef has one unambiguous purpose (auth to the remote)
• Validation-only controller: Validates references (MCPGroup, MCPExternalAuthConfig) but never probes remote URLs
• Both discovery modes: Works with static (operator-generated ConfigMap) and dynamic (vMCP runtime discovery) from THV-0014
• Header forwarding: Reuses existing headerForward pattern from THV-0026
• Custom CA support: caBundleRef for private remote servers with internal CAs
• Planned supersession: Will be superseded by MCPRemoteEndpoint (THV-0067), which unifies direct and proxy modes into a single CRD

Related RFCs

• THV-0008 (Virtual MCP Server)
• THV-0009 (Remote MCP Proxy)
• THV-0010 (MCPGroup CRD)
• THV-0014 (K8s-Aware vMCP)
• THV-0026 (Header Passthrough)
• THV-0067 (MCPRemoteEndpoint — future unified CRD)

Test plan

• Review RFC structure and completeness
• Validate CRD design against existing patterns
• Verify security considerations (auth boundaries, SSRF mitigations)
• Confirm MCPRemoteEndpoint supersession path is documented
• Review comparison guide (MCPRemoteProxy vs MCPServerEntry)

[yrobla]

This is a well-structured RFC with clear motivation, thorough security considerations, and good alternatives analysis. The naming convention (following Istio ServiceEntry) is a nice touch. A few issues worth addressing before implementation:

• groupRef type inconsistency (string vs object pattern) needs resolution
• caBundleRef resource type (Secret vs ConfigMap) is ambiguous across sections
• SSRF mitigation has a gap: HTTPS-only validation doesn't block private IP ranges
• Auth resolution timing in ListWorkloadsInGroup() description is unclear
• Static mode CA bundle propagation is unspecified
• toolConfigRef deferral creates an unacknowledged migration regression for MCPRemoteProxy users

[yrobla]

looks as a very good improvement to me

[amirejaz]

This looks good to me. Added one comment

[amirejaz]

Question: Would it make sense to rename MCPServerEntry to MCPRemoteServerEntry to improve clarity?

[jerm-dro]

Looks great! I appreciate the alternatives section.

[lorr1]

We need this!! I love it.

[ChrisJBurns]

Thanks for the detailed RFC — the three problems are real and worth solving, and the security thinking (no operator-side probing, HTTPS enforcement, credential separation) is solid throughout.

The core question this review raises is: does solving these three problems require a new CRD, or can they be addressed by extending what already exists?

After reading the RFC against the actual codebase, the case for a new CRD is weaker than it appears:

• Problem #1 (forced OIDC on public remotes) can be fixed by making oidcConfig optional on MCPRemoteProxy — a one-field change (see comment 2).
• Problem #2 (dual auth boundary confusion) turns out not to exist in the code — externalAuthConfigRef and oidcConfig already serve separate purposes in pkg/vmcp/workloads/k8s.go (see comment 1).
• Problem #3 (pod waste) can be solved by adding a direct: true flag to MCPRemoteProxy that skips ensureDeployment() and ensureService() and uses remoteURL as the backend URL directly — touching ~4 files vs. the RFC's ~20 (see comments 3, 4).

The RFC does consider alternatives but doesn't seriously evaluate the most natural one: extending MCPRemoteProxy itself. Its alternatives section argues against extending MCPServer (fair) and against config-only approaches (fair), but never evaluates a lightweight mode on the resource that already exists for this exact purpose (comment 3).

Beyond the alternatives analysis, there are several concrete concerns: the operational cost of a new CRD is significantly underestimated (comment 4); the new CRD creates naming confusion alongside MCPServer and MCPRemoteProxy (comment 9); the MCPGroup status model would need restructuring for a third backend type (comment 5); the CA bundle volume-mounting introduces new operator complexity (comment 8); and the SSRF trade-off of moving outbound calls into the vMCP pod deserves explicit acknowledgement (comment 7).

Suggested path forward: Before investing in a new CRD, implement the simpler approach — make oidcConfig optional and add direct: true to MCPRemoteProxy. If real-world usage reveals that the RBAC separation story (platform teams vs. product teams managing backends independently) is a genuine need that can't be satisfied by MCPRemoteProxy's existing RBAC surface, revisit the CRD proposal with that as the primary motivation rather than the pod-waste argument.

If the team decides a new CRD is still the right call after considering the above, comments 5–12 cover the design-level issues that should be resolved before implementation begins.

🤖 Review assisted by Claude Code

[jhrozek]

+1 to what @ChrisJBurns said, I think we should consider reusing the existing CRDs and be more explicit in why it's not an option. There's also the cognitive load on the users, the documentation load etc..

[JAORMX]

+1 to what @ChrisJBurns said, I think we should consider reusing the existing CRDs and be more explicit in why it's not an option. There's also the cognitive load on the users, the documentation load etc..

I actually disagree with this. I think re-using existing CRDs would do us a diservice and further increase technical depth by using APIs that are not fit for purpose because they had very different intentions.