Implement ExternalAuthConfig discovery for VirtualMCPServer backends

[amirejaz]

Summary

This PR implements automatic discovery and resolution of MCPExternalAuthConfig resources for backend MCPServers in the VirtualMCPServer controller. The feature enables VirtualMCPServer to automatically discover and apply external authentication configurations (e.g., OAuth2 Token Exchange) from referenced MCPServer resources without requiring manual configuration.

Changes

Core Implementation

• buildOutgoingAuthConfig: New function that builds OutgoingAuthConfig by discovering ExternalAuthConfig from MCPServer resources when using "discovered" or "mixed" source modes
• convertExternalAuthConfigToStrategy: Converts MCPExternalAuthConfig CRD resources to internal BackendAuthStrategy format, handling token exchange configuration including client secrets, scopes, and token types
• convertBackendAuthConfigToVMCP: Converts inline BackendAuthConfig from CRD spec to BackendAuthStrategy, supporting both direct references and ExternalAuthConfigRef references
• Updated discoverBackends: Now uses the resolved OutgoingAuthConfig (including discovered external auth configs) when creating the UnifiedBackendDiscoverer
• Updated ensureVmcpConfigConfigMap: Ensures that fully resolved OutgoingAuthConfig (including discovered external auths) is written to the ConfigMap consumed by VirtualMCPServer pods

Features

• Three source modes supported:

  • discovered: Automatically discover auth configs from all referenced MCPServers
  • mixed: Discover from MCPServers but allow inline overrides per backend
  • inline: Use only explicitly specified auth configs (existing behavior)

• Token Exchange support: Full support for OAuth2 Token Exchange (RFC 8693) including:

  • Token URL, client ID, audience, scopes
  • Client secret references (via Kubernetes Secrets)
  • Subject token type normalization
  • Custom external token header names

Testing

• Unit tests: Comprehensive test coverage in virtualmcpserver_externalauth_test.go:

  • TestConvertExternalAuthConfigToStrategy: Tests conversion logic with various configurations
  • TestBuildOutgoingAuthConfig: Tests building OutgoingAuthConfig in all three modes
  • TestConvertBackendAuthConfigToVMCP: Tests inline config conversion
  • TestDiscoverBackendsWithExternalAuthConfigIntegration: Integration test for end-to-end discovery flow

• Manual testing: Added complete manual testing setup:

  • Test manifests for all three modes (manual-test-external-auth-discovery.yaml, manual-test-mixed-mode.yaml, manual-test-inline-mode.yaml)
  • Verification script (verify-external-auth.sh) to validate ConfigMap content and deployment configuration
  • Comprehensive guides (QUICK_START.md, MANUAL_TESTING_GUIDE.md) with step-by-step instructions

How It Works

1. When a VirtualMCPServer is created/updated, the controller discovers all referenced MCPServers from the specified groups
2. For each MCPServer with an ExternalAuthConfigRef, the controller:
   • Fetches the MCPExternalAuthConfig resource
   • Converts it to a BackendAuthStrategy with appropriate metadata
   • Adds it to the OutgoingAuthConfig for that backend
3. The resolved configuration (including discovered auth configs) is written to the vmcp ConfigMap
4. The VirtualMCPServer pod consumes this ConfigMap and uses the auth strategies when communicating with backends

Example Usage

l

MCPExternalAuthConfig defines token exchange configuration

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPExternalAuthConfig
metadata:
name: backend-1-auth-config
spec:
type: tokenExchange
tokenExchange:
tokenUrl: https://oauth.example.com/token
clientId: my-client-id
clientSecretRef:
name: oauth-secret
key: client-secret
audience: backend-service
scopes: [read, write]

MCPServer references the ExternalAuthConfig

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPServer
metadata:
name: backend-1
spec:
externalAuthConfigRef:
name: backend-1-auth-config

... other spec fields

VirtualMCPServer automatically discovers and applies the auth config

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: VirtualMCPServer
metadata:
name: my-vmcp
spec:
groups:
- name: my-group
outgoingAuth:
source: discovered # Automatically discover from MCPServers## Notes

• Client secret environment variables are referenced in the ConfigMap metadata but are not yet automatically mounted in the deployment (this will be addressed in a follow-up PR)
• The implementation gracefully handles missing or invalid MCPExternalAuthConfig resources by logging and skipping affected backends
• Inline configurations always take precedence over discovered configurations when both are present

Related Issues

Fixes the issue where ExternalAuthConfig was not being resolved and used by the VirtualMCPServer controller to populate backend authentication configurations.

Testing

• Unit tests pass
• Manual testing completed with Kind cluster
• Verified ConfigMap contains discovered auth configs
• Verified all three source modes work correctly

[codecov]

Codecov Report

❌ Patch coverage is 37.39496% with 149 lines in your changes missing coverage. Please review.
✅ Project coverage is 56.19%. Comparing base (e724609) to head (f979c24).

Files with missing lines	Patch %	Lines
...perator/controllers/virtualmcpserver_deployment.go	9.84%	119 Missing ⚠️
...perator/controllers/virtualmcpserver_controller.go	76.08%	14 Missing and 8 partials ⚠️
...perator/controllers/virtualmcpserver_vmcpconfig.go	42.85%	4 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2726      +/-   ##
==========================================
- Coverage   56.29%   56.19%   -0.10%     
==========================================
  Files         319      319              
  Lines       30753    30956     +203     
==========================================
+ Hits        17312    17396      +84     
- Misses      11953    12062     +109     
- Partials     1488     1498      +10     

☔ 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.

[amirejaz]

implements #2704

[github-actions]

Large PR Detected

This PR exceeds 1000 lines of changes and requires justification before it can be reviewed.

How to unblock this PR:

Add a section to your PR description with the following format:

## Large PR Justification

[Explain why this PR must be large, such as:]
- Generated code that cannot be split
- Large refactoring that must be atomic
- Multiple related changes that would break if separated
- Migration or data transformation

Alternative:

Consider splitting this PR into smaller, focused changes (< 1000 lines each) for easier review and reduced risk.

See our Contributing Guidelines for more details.

---

This review will be automatically dismissed once you add the justification section.