Summary
A systematic comparison of the Kubernetes Operator guides (docs/toolhive/guides-k8s/) against the auto-generated CRD reference (docs/toolhive/reference/crd-spec.md) and the ToolHive operator source code reveals a number of documentation gaps and inaccuracies. This analysis is scoped to the MCPServer CRD and the operator itself - VirtualMCPServer and ToolHiveRegistryServer CRDs are excluded since they have their own guide sections.
Related issues and PRs
Inaccuracies in existing docs
| # |
Issue |
Location |
Details |
| 1 |
permissionProfile in YAML examples |
auth-k8s.mdx (5 instances, lines 103, 189, 253, 494, 682) |
This CRD field is not implemented in the operator - it does nothing. Network isolation in K8s is left to users' existing network security / service mesh capabilities. Remove from all examples to avoid implying it has an effect. |
| 2 |
Deprecated port field in examples |
auth-k8s.mdx (lines 102, 188, 252, 682) |
4 of 5 auth examples use deprecated port instead of proxyPort. The 5th (line 493) already uses proxyPort. |
High-priority gaps
| # |
Gap |
Details |
| 1 |
MCPGroup / groupRef for MCPServer |
groupRef on MCPServer is not documented. Only shown for MCPRemoteProxy (remote-mcp-proxy.mdx) and in a generic logging example. No guide for creating an MCPGroup and associating MCPServer resources for vMCP aggregation. |
| 2 |
Pod restart mechanism |
Operator supports mcpserver.toolhive.stacklok.dev/restarted-at annotation with rolling (default) and immediate strategies. Completely undocumented. |
| 3 |
ResourceOverrides |
Override annotations, labels, env vars, and image pull secrets on the proxy Deployment and Service. Not documented. |
| 4 |
ServiceAccount customization |
serviceAccount field to use an existing SA instead of auto-created. run-mcp-k8s.mdx documents auto-created RBAC but not this option. |
| 5 |
OpenShift support |
Operator auto-detects OpenShift and applies appropriate security contexts. Not documented. |
| 6 |
Inline authorization for MCPServer |
auth-k8s.mdx only shows ConfigMap-based Cedar policies for MCPServer. CRD also supports type: inline with policies directly in the spec (shown for MCPRemoteProxy in remote-mcp-proxy.mdx but not for MCPServer). |
| 7 |
Helm feature flags |
features.server, features.registry, features.virtualMCP, features.experimental control which controllers are enabled. deploy-operator.mdx covers CRD group selection but not these operator-level flags. |
Medium-priority gaps
CRD fields missing from guides
| # |
Field |
Description |
| 1 |
proxyMode |
Proxy mode for stdio transport (sse vs streamable-http) |
| 2 |
endpointPrefix |
Path prefix for SSE endpoint URLs - relevant for path-based ingress but absent from connect-clients.mdx |
| 3 |
trustProxyHeaders |
Trust X-Forwarded-* headers - relevant when behind ingress |
| 4 |
sessionAffinity |
Service session affinity (ClientIP vs None) - only in vMCP scaling guide, not MCPServer guides |
| 5 |
oidcConfig.resourceUrl |
RFC 9728 OAuth resource URL for discovery |
| 6 |
oidcConfig.kubernetes.useClusterAuth |
Use cluster auth paths for JWKS validation |
| 7 |
Advanced oidcConfig.inline fields |
jwksAuthTokenPath, jwksAllowPrivateIP, insecureAllowHTTP, scopes, etc. (partial overlap with #466) |
| 8 |
telemetry.openTelemetry.headers |
Auth headers for OTEL endpoint |
| 9 |
telemetry.openTelemetry.useLegacyAttributes |
Legacy OTEL attribute names |
Operator features missing from guides
| # |
Feature |
Description |
| 1 |
Image validation |
Operator validates images against enforced registries; sets ImageValidated condition |
| 2 |
Status conditions reference |
7 condition types (ImageValidated, GroupRefValidated, PodTemplateValid, CABundleRefValidated, ExternalAuthConfigValidated, StdioReplicaCapped, SessionStorageWarning) - not documented as a troubleshooting/operational reference |
| 3 |
HPA configuration |
Helm chart HPA settings (disabled by default); only briefly mentioned in deploy-operator.mdx |
| 4 |
Operator resource tuning |
Go memory tuning (gomemlimit, gogc) in Helm values |
Lower-priority gaps
| # |
Gap |
| 1 |
resourceOverrides sub-fields (proxy env vars, image pull secrets) |
| 2 |
RunConfig ConfigMap internals and checksum-based rollout |
| 3 |
Finalizer behavior during cleanup |
| 4 |
Operator leader election config |
Deprecated fields in guides
| Deprecated |
Replacement |
Action needed |
port |
proxyPort |
4 examples in auth-k8s.mdx still use deprecated field |
targetPort |
mcpPort |
Audit all K8s guide YAML examples |
tools (inline list) |
toolConfigRef |
customize-tools.mdx already notes this |
thvCABundlePath |
caBundleRef |
Tracked in #466 |
Methodology
This analysis compared three sources:
- K8s guides in
docs/toolhive/guides-k8s/ (13 files)
- Auto-generated CRD reference in
docs/toolhive/reference/crd-spec.md (MCPServer section)
- ToolHive operator source code (CRD type definitions, controller logic, Helm values)
Out of scope: VirtualMCPServer and ToolHiveRegistryServer CRDs (covered by their own guide sections).
