From d06d170658cd733b35426c439e1b79e27f538dd0 Mon Sep 17 00:00:00 2001 From: Jeremy Drouillard Date: Thu, 8 Jan 2026 09:45:02 -0800 Subject: [PATCH 1/5] Update VirtualMCP docs for groupRef changes --- docs/toolhive/guides-vmcp/composite-tools.mdx | 8 +++---- docs/toolhive/guides-vmcp/configuration.mdx | 4 ++-- .../toolhive/guides-vmcp/tool-aggregation.mdx | 4 ++-- docs/toolhive/tutorials/quickstart-vmcp.mdx | 4 ++-- package-lock.json | 1 + static/api-specs/toolhive-crd-api.md | 23 ++++--------------- 6 files changed, 15 insertions(+), 29 deletions(-) diff --git a/docs/toolhive/guides-vmcp/composite-tools.mdx b/docs/toolhive/guides-vmcp/composite-tools.mdx index c1281184..d102368d 100644 --- a/docs/toolhive/guides-vmcp/composite-tools.mdx +++ b/docs/toolhive/guides-vmcp/composite-tools.mdx @@ -41,8 +41,8 @@ kind: VirtualMCPServer metadata: name: my-vmcp spec: - groupRef: - name: my-tools + config: + groupRef: my-tools # ... other configuration ... compositeTools: - name: my_workflow @@ -325,8 +325,8 @@ metadata: name: workflow-vmcp namespace: toolhive-system spec: - groupRef: - name: my-tools + config: + groupRef: my-tools incomingAuth: type: anonymous aggregation: diff --git a/docs/toolhive/guides-vmcp/configuration.mdx b/docs/toolhive/guides-vmcp/configuration.mdx index 5480a04b..dbd1b6b8 100644 --- a/docs/toolhive/guides-vmcp/configuration.mdx +++ b/docs/toolhive/guides-vmcp/configuration.mdx @@ -42,8 +42,8 @@ metadata: name: my-vmcp namespace: toolhive-system spec: - groupRef: - name: my-group + config: + groupRef: my-group incomingAuth: type: anonymous # Disables authentication; do not use in production ``` diff --git a/docs/toolhive/guides-vmcp/tool-aggregation.mdx b/docs/toolhive/guides-vmcp/tool-aggregation.mdx index db6f2177..27690bb9 100644 --- a/docs/toolhive/guides-vmcp/tool-aggregation.mdx +++ b/docs/toolhive/guides-vmcp/tool-aggregation.mdx @@ -208,8 +208,8 @@ metadata: name: demo-vmcp namespace: toolhive-system spec: - groupRef: - name: demo-tools + config: + groupRef: demo-tools incomingAuth: type: anonymous aggregation: diff --git a/docs/toolhive/tutorials/quickstart-vmcp.mdx b/docs/toolhive/tutorials/quickstart-vmcp.mdx index 944eae33..a8d5cd6c 100644 --- a/docs/toolhive/tutorials/quickstart-vmcp.mdx +++ b/docs/toolhive/tutorials/quickstart-vmcp.mdx @@ -123,8 +123,8 @@ metadata: namespace: toolhive-system spec: # Reference the MCPGroup containing fetch and osv servers - groupRef: - name: demo-tools + config: + groupRef: demo-tools # No incoming auth for development (anonymous access) incomingAuth: diff --git a/package-lock.json b/package-lock.json index db4e7a7c..86f2d01f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -22833,6 +22833,7 @@ "resolved": "https://registry.npmjs.org/styled-components/-/styled-components-6.1.19.tgz", "integrity": "sha512-1v/e3Dl1BknC37cXMhwGomhO8AkYmN41CqyX9xhUDxry1ns3BFQy2lLDRQXJRdVVWB9OHemv/53xaStimvWyuA==", "license": "MIT", + "peer": true, "dependencies": { "@emotion/is-prop-valid": "1.2.2", "@emotion/unitless": "0.8.1", diff --git a/static/api-specs/toolhive-crd-api.md b/static/api-specs/toolhive-crd-api.md index 598fb946..7e278d4e 100644 --- a/static/api-specs/toolhive-crd-api.md +++ b/static/api-specs/toolhive-crd-api.md @@ -1,3 +1,4 @@ +# API Reference ## Packages - [toolhive.stacklok.dev/v1alpha1](#toolhivestacklokdevv1alpha1) @@ -418,22 +419,6 @@ _Appears in:_ | `path` _string_ | Path is the path to the registry file within the repository | registry.json | Pattern: `^.*\.json$`
| -#### GroupRef - - - -GroupRef references an MCPGroup resource - - - -_Appears in:_ -- [VirtualMCPServerSpec](#virtualmcpserverspec) - -| Field | Description | Default | Validation | -| --- | --- | --- | --- | -| `name` _string_ | Name is the name of the MCPGroup resource in the same namespace | | Required: \{\}
| - - #### HeaderInjectionConfig @@ -1043,6 +1028,7 @@ _Appears in:_ | `telemetry` _[TelemetryConfig](#telemetryconfig)_ | Telemetry defines observability configuration for the proxy | | | | `resources` _[ResourceRequirements](#resourcerequirements)_ | Resources defines the resource requirements for the proxy container | | | | `trustProxyHeaders` _boolean_ | TrustProxyHeaders indicates whether to trust X-Forwarded-* headers from reverse proxies
When enabled, the proxy will use X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port,
and X-Forwarded-Prefix headers to construct endpoint URLs | false | | +| `endpointPrefix` _string_ | EndpointPrefix is the path prefix to prepend to SSE endpoint URLs.
This is used to handle path-based ingress routing scenarios where the ingress
strips a path prefix before forwarding to the backend. | | | | `resourceOverrides` _[ResourceOverrides](#resourceoverrides)_ | ResourceOverrides allows overriding annotations and labels for resources created by the operator | | | | `groupRef` _string_ | GroupRef is the name of the MCPGroup this proxy belongs to
Must reference an existing MCPGroup in the same namespace | | | @@ -1169,6 +1155,7 @@ _Appears in:_ | `externalAuthConfigRef` _[ExternalAuthConfigRef](#externalauthconfigref)_ | ExternalAuthConfigRef references a MCPExternalAuthConfig resource for external authentication.
The referenced MCPExternalAuthConfig must exist in the same namespace as this MCPServer. | | | | `telemetry` _[TelemetryConfig](#telemetryconfig)_ | Telemetry defines observability configuration for the MCP server | | | | `trustProxyHeaders` _boolean_ | TrustProxyHeaders indicates whether to trust X-Forwarded-* headers from reverse proxies
When enabled, the proxy will use X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port,
and X-Forwarded-Prefix headers to construct endpoint URLs | false | | +| `endpointPrefix` _string_ | EndpointPrefix is the path prefix to prepend to SSE endpoint URLs.
This is used to handle path-based ingress routing scenarios where the ingress
strips a path prefix before forwarding to the backend. | | | | `groupRef` _string_ | GroupRef is the name of the MCPGroup this server belongs to
Must reference an existing MCPGroup in the same namespace | | | @@ -1801,7 +1788,6 @@ TelemetryConfig defines observability configuration for the MCP server _Appears in:_ - [MCPRemoteProxySpec](#mcpremoteproxyspec) - [MCPServerSpec](#mcpserverspec) -- [VirtualMCPServerSpec](#virtualmcpserverspec) | Field | Description | Default | Validation | | --- | --- | --- | --- | @@ -2071,7 +2057,6 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `groupRef` _[GroupRef](#groupref)_ | GroupRef references an existing MCPGroup that defines backend workloads
The referenced MCPGroup must exist in the same namespace | | Required: \{\}
| | `incomingAuth` _[IncomingAuthConfig](#incomingauthconfig)_ | IncomingAuth configures authentication for clients connecting to the Virtual MCP server
Must be explicitly set - use "anonymous" type when no authentication is required | | Required: \{\}
| | `outgoingAuth` _[OutgoingAuthConfig](#outgoingauthconfig)_ | OutgoingAuth configures authentication from Virtual MCP to backend MCPServers | | | | `aggregation` _[AggregationConfig](#aggregationconfig)_ | Aggregation defines tool aggregation and conflict resolution strategies | | | @@ -2080,8 +2065,8 @@ _Appears in:_ | `operational` _[OperationalConfig](#operationalconfig)_ | Operational defines operational settings like timeouts and health checks | | | | `serviceType` _string_ | ServiceType specifies the Kubernetes service type for the Virtual MCP server | ClusterIP | Enum: [ClusterIP NodePort LoadBalancer]
| | `podTemplateSpec` _[RawExtension](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#rawextension-runtime-pkg)_ | PodTemplateSpec defines the pod template to use for the Virtual MCP server
This allows for customizing the pod configuration beyond what is provided by the other fields.
Note that to modify the specific container the Virtual MCP server runs in, you must specify
the 'vmcp' container name in the PodTemplateSpec.
This field accepts a PodTemplateSpec object as JSON/YAML. | | Type: object
| -| `telemetry` _[TelemetryConfig](#telemetryconfig)_ | Telemetry configures OpenTelemetry-based observability for the Virtual MCP server
including distributed tracing, OTLP metrics export, and Prometheus metrics endpoint | | | | `audit` _[AuditConfig](#auditconfig)_ | Audit configures audit logging for the Virtual MCP server
When enabled, audit logs include MCP protocol operations | | | +| `config` | Config is the Virtual MCP server configuration.

The only field currently required within config is `config.groupRef`. GroupRef references an existing MCPGRoup that defines backend workloads. The referenced MCPGroup must exist in the same namespace.

NOTE: All other `config` fields will be ignored in favor of their inline versions above. | | | #### VirtualMCPServerStatus From 2b43c88684d5780a18bb89ec034dcde8a8712532 Mon Sep 17 00:00:00 2001 From: Jeremy Drouillard Date: Thu, 8 Jan 2026 09:54:12 -0800 Subject: [PATCH 2/5] comments --- static/api-specs/toolhive-crd-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/static/api-specs/toolhive-crd-api.md b/static/api-specs/toolhive-crd-api.md index 7e278d4e..e9f741d0 100644 --- a/static/api-specs/toolhive-crd-api.md +++ b/static/api-specs/toolhive-crd-api.md @@ -2066,7 +2066,7 @@ _Appears in:_ | `serviceType` _string_ | ServiceType specifies the Kubernetes service type for the Virtual MCP server | ClusterIP | Enum: [ClusterIP NodePort LoadBalancer]
| | `podTemplateSpec` _[RawExtension](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#rawextension-runtime-pkg)_ | PodTemplateSpec defines the pod template to use for the Virtual MCP server
This allows for customizing the pod configuration beyond what is provided by the other fields.
Note that to modify the specific container the Virtual MCP server runs in, you must specify
the 'vmcp' container name in the PodTemplateSpec.
This field accepts a PodTemplateSpec object as JSON/YAML. | | Type: object
| | `audit` _[AuditConfig](#auditconfig)_ | Audit configures audit logging for the Virtual MCP server
When enabled, audit logs include MCP protocol operations | | | -| `config` | Config is the Virtual MCP server configuration.

The only field currently required within config is `config.groupRef`. GroupRef references an existing MCPGRoup that defines backend workloads. The referenced MCPGroup must exist in the same namespace.

NOTE: All other `config` fields will be ignored in favor of their inline versions above. | | | +| `config` __object__ | Config is the Virtual MCP server configuration.

The only field currently required within config is `config.groupRef`. GroupRef references an existing MCPGroup that defines backend workloads. The referenced MCPGroup must exist in the same namespace.

NOTE: All other `config` fields will be ignored in favor of their inline versions above. | | | #### VirtualMCPServerStatus From f24f889f9d984001cf08e78d6fb0ea03f9e89035 Mon Sep 17 00:00:00 2001 From: Jeremy Drouillard Date: Thu, 8 Jan 2026 10:05:45 -0800 Subject: [PATCH 3/5] include all from main --- static/api-specs/toolhive-crd-api.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/static/api-specs/toolhive-crd-api.md b/static/api-specs/toolhive-crd-api.md index e9f741d0..e2a9fd22 100644 --- a/static/api-specs/toolhive-crd-api.md +++ b/static/api-specs/toolhive-crd-api.md @@ -1788,6 +1788,7 @@ TelemetryConfig defines observability configuration for the MCP server _Appears in:_ - [MCPRemoteProxySpec](#mcpremoteproxyspec) - [MCPServerSpec](#mcpserverspec) +- [VirtualMCPServerSpec](#virtualmcpserverspec) | Field | Description | Default | Validation | | --- | --- | --- | --- | @@ -2065,8 +2066,9 @@ _Appears in:_ | `operational` _[OperationalConfig](#operationalconfig)_ | Operational defines operational settings like timeouts and health checks | | | | `serviceType` _string_ | ServiceType specifies the Kubernetes service type for the Virtual MCP server | ClusterIP | Enum: [ClusterIP NodePort LoadBalancer]
| | `podTemplateSpec` _[RawExtension](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#rawextension-runtime-pkg)_ | PodTemplateSpec defines the pod template to use for the Virtual MCP server
This allows for customizing the pod configuration beyond what is provided by the other fields.
Note that to modify the specific container the Virtual MCP server runs in, you must specify
the 'vmcp' container name in the PodTemplateSpec.
This field accepts a PodTemplateSpec object as JSON/YAML. | | Type: object
| +| `telemetry` _[TelemetryConfig](#telemetryconfig)_ | Telemetry configures OpenTelemetry-based observability for the Virtual MCP server
including distributed tracing, OTLP metrics export, and Prometheus metrics endpoint | | | | `audit` _[AuditConfig](#auditconfig)_ | Audit configures audit logging for the Virtual MCP server
When enabled, audit logs include MCP protocol operations | | | -| `config` __object__ | Config is the Virtual MCP server configuration.

The only field currently required within config is `config.groupRef`. GroupRef references an existing MCPGroup that defines backend workloads. The referenced MCPGroup must exist in the same namespace.

NOTE: All other `config` fields will be ignored in favor of their inline versions above. | | | +| `config` _[Config](#config)_ | Config is the Virtual MCP server configuration
NOTE: THIS IS NOT CURRENTLY USED AND IS DUPLICATED FROM THE SPEC FIELDS ABOVE. | | | #### VirtualMCPServerStatus From 43173423d1de47ecf4535cafa9f2e0a27d85d43f Mon Sep 17 00:00:00 2001 From: Jeremy Drouillard Date: Thu, 8 Jan 2026 10:08:39 -0800 Subject: [PATCH 4/5] put back comment --- static/api-specs/toolhive-crd-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/static/api-specs/toolhive-crd-api.md b/static/api-specs/toolhive-crd-api.md index e2a9fd22..ffa81cdc 100644 --- a/static/api-specs/toolhive-crd-api.md +++ b/static/api-specs/toolhive-crd-api.md @@ -2068,7 +2068,7 @@ _Appears in:_ | `podTemplateSpec` _[RawExtension](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#rawextension-runtime-pkg)_ | PodTemplateSpec defines the pod template to use for the Virtual MCP server
This allows for customizing the pod configuration beyond what is provided by the other fields.
Note that to modify the specific container the Virtual MCP server runs in, you must specify
the 'vmcp' container name in the PodTemplateSpec.
This field accepts a PodTemplateSpec object as JSON/YAML. | | Type: object
| | `telemetry` _[TelemetryConfig](#telemetryconfig)_ | Telemetry configures OpenTelemetry-based observability for the Virtual MCP server
including distributed tracing, OTLP metrics export, and Prometheus metrics endpoint | | | | `audit` _[AuditConfig](#auditconfig)_ | Audit configures audit logging for the Virtual MCP server
When enabled, audit logs include MCP protocol operations | | | -| `config` _[Config](#config)_ | Config is the Virtual MCP server configuration
NOTE: THIS IS NOT CURRENTLY USED AND IS DUPLICATED FROM THE SPEC FIELDS ABOVE. | | | +| `config` __object__ | Config is the Virtual MCP server configuration.

The only field currently required within config is `config.groupRef`. GroupRef references an existing MCPGroup that defines backend workloads. The referenced MCPGroup must exist in the same namespace.

NOTE: All other `config` fields will be ignored in favor of their inline versions above. | | | #### VirtualMCPServerStatus From aafd11b169528e65b82820f18d1156d3a3f590bd Mon Sep 17 00:00:00 2001 From: Jeremy Drouillard Date: Thu, 8 Jan 2026 10:27:50 -0800 Subject: [PATCH 5/5] remove API header --- static/api-specs/toolhive-crd-api.md | 1 - 1 file changed, 1 deletion(-) diff --git a/static/api-specs/toolhive-crd-api.md b/static/api-specs/toolhive-crd-api.md index ffa81cdc..52eb6e71 100644 --- a/static/api-specs/toolhive-crd-api.md +++ b/static/api-specs/toolhive-crd-api.md @@ -1,4 +1,3 @@ -# API Reference ## Packages - [toolhive.stacklok.dev/v1alpha1](#toolhivestacklokdevv1alpha1)