Add documentation for ToolHive v0.20.0 (#715)

* Add documentation for ToolHive v0.20.0

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Fix MCPTelemetryConfig example and add CRD spec admonitions

Address review feedback:
- Fix API group from .com to .dev in MCPTelemetryConfig example
- Use correct nested openTelemetry/prometheus spec structure
- Move serviceName from MCPTelemetryConfig to telemetryConfigRef
- Soften rolling update claim (remove specific TelemetryConfigHash reference)
- Add admonition noting telemetryConfigRef is a v0.20.0 feature
- Add admonition noting groupRef struct change is a v0.20.0 feature

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Remove weekly product update blog post

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Update docs/toolhive/guides-vmcp/configuration.mdx

Co-authored-by: Dan Barr <danbarr@users.noreply.github.com>

* Remove deprecated inline telemetry docs and groupRef info note

Address PR review feedback:
- Remove "two ways" framing and deprecated inline telemetry config
  section, keeping only the shared MCPTelemetryConfig approach
- Update config table and Jaeger example to use new field paths
- Remove groupRef v0.20.0 info note from configuration page since
  CRD ref and migration guide already cover this

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Dan Barr <danbarr@users.noreply.github.com>

Author: 3 people

docs/toolhive/guides-cli/run-mcp-servers.mdx

@@ -648,6 +648,21 @@ uses Server-Sent Events (SSE), specify the transport flag:
 thv run https://api.example.com/sse --transport sse
 ```
 
+#### Stateless remote servers
+
+Some remote MCP servers only accept POST requests and don't support SSE streams.
+For these servers, use the `--stateless` flag:
+
+```bash
+thv run https://example.com/mcp --name my-server --transport streamable-http --stateless
+```
+
+When `--stateless` is set:
+
+- GET, HEAD, and DELETE requests return HTTP 405 at the proxy instead of being
+  forwarded to the remote server
+- Health checks use a POST-based JSON-RPC ping instead of SSE
+
 :::info[What's happening?]
 
 When you run a remote MCP server, ToolHive:
@@ -727,6 +742,24 @@ thv run https://api.example.com/mcp \
   --remote-auth-scopes read,write,admin
 ```
 
+#### Non-standard OAuth scope parameter name
+
+Some OAuth providers use a non-standard query parameter name for scopes in the
+authorization URL. For example, Slack uses `user_scope` instead of the standard
+`scope` parameter. Use the `--remote-auth-scope-param-name` flag to override the
+parameter name:
+
+```bash
+thv run https://mcp.slack.com/mcp \
+  --name slack \
+  --transport streamable-http \
+  --remote-auth-client-id <CLIENT_ID> \
+  --remote-auth-callback-port 3118 \
+  --remote-auth-authorize-url "https://slack.com/oauth/v2_user/authorize" \
+  --remote-auth-token-url "https://slack.com/api/oauth.v2.user.access" \
+  --remote-auth-scope-param-name user_scope
+```
+
 #### Resource indicator (RFC 8707)
 
 When authenticating to remote MCP servers, you can specify a resource indicator

docs/toolhive/guides-k8s/logging.mdx

@@ -126,9 +126,9 @@ metadata:
   name: <SERVER_NAME>
   namespace: toolhive-system
 spec:
+  groupRef:
+    name: <GROUP_NAME>
   config:
-    groupRef: <GROUP_NAME>
-
     # Enable audit logging
     audit:
       enabled: true

docs/toolhive/guides-k8s/mcp-server-entry.mdx

@@ -98,7 +98,8 @@ metadata:
   name: my-remote-tool
   namespace: toolhive-system
 spec:
-  groupRef: my-group
+  groupRef:
+    name: my-group
   remoteURL: https://mcp.example.com/mcp
   transport: streamable-http
 ```
@@ -163,7 +164,8 @@ metadata:
   name: internal-tool
   namespace: toolhive-system
 spec:
-  groupRef: my-group
+  groupRef:
+    name: my-group
   remoteURL: https://internal-mcp.corp.example.com/mcp
   transport: streamable-http
   # highlight-next-line
@@ -196,7 +198,8 @@ metadata:
   name: internal-tool
   namespace: toolhive-system
 spec:
-  groupRef: my-group
+  groupRef:
+    name: my-group
   remoteURL: https://internal-mcp.corp.example.com/mcp
   transport: streamable-http
   # highlight-start
@@ -220,7 +223,8 @@ metadata:
   name: my-remote-tool
   namespace: toolhive-system
 spec:
-  groupRef: my-group
+  groupRef:
+    name: my-group
   remoteURL: https://mcp.example.com/mcp
   transport: streamable-http
   # highlight-start
@@ -276,7 +280,8 @@ metadata:
   name: partner-tools
   namespace: toolhive-system
 spec:
-  groupRef: engineering-tools
+  groupRef:
+    name: engineering-tools
   remoteURL: https://mcp.partner.example.com/mcp
   transport: streamable-http
   externalAuthConfigRef:

docs/toolhive/guides-vmcp/audit-logging.mdx

@@ -28,8 +28,9 @@ metadata:
   name: my-vmcp
   namespace: toolhive-system
 spec:
+  groupRef:
+    name: my-group
   config:
-    groupRef: my-group
     # highlight-start
     audit:
       enabled: true

docs/toolhive/guides-vmcp/authentication.mdx

@@ -522,8 +522,8 @@ metadata:
   name: my-vmcp
   namespace: toolhive-system
 spec:
-  config:
-    groupRef: my-backends
+  groupRef:
+    name: my-backends
   # highlight-start
   authServerConfig:
     issuer: https://auth.example.com

docs/toolhive/guides-vmcp/backend-discovery.mdx

@@ -78,8 +78,8 @@ metadata:
   name: my-vmcp
   namespace: toolhive-system
 spec:
-  config:
-    groupRef: my-group
+  groupRef:
+    name: my-group
   incomingAuth:
     type: anonymous
   outgoingAuth:
@@ -144,8 +144,9 @@ metadata:
   name: my-vmcp
   namespace: toolhive-system
 spec:
+  groupRef:
+    name: my-group
   config:
-    groupRef: my-group
     # highlight-start
     backends:
       - name: github-mcp
@@ -336,8 +337,9 @@ restarting the vMCP pod.
 
    ```yaml
    spec:
+     groupRef:
+       name: my-group
      config:
-       groupRef: my-group
        backends:
          - name: github-mcp
            url: http://github-mcp.toolhive-system.svc.cluster.local:8080
@@ -361,9 +363,9 @@ restarting the vMCP pod.
 
    ```yaml
    spec:
-     config:
-       groupRef: my-group
-       # Remove backends array
+     groupRef:
+       name: my-group
+     # Remove config.backends array if present
      outgoingAuth:
        source: discovered
    ```
@@ -420,7 +422,8 @@ metadata:
   name: github-mcp
   namespace: toolhive-system
 spec:
-  groupRef: engineering-tools
+  groupRef:
+    name: engineering-tools
   image: ghcr.io/example/github-mcp-server:v1.2.3
   transport: sse
   externalAuthConfigRef:
@@ -434,8 +437,8 @@ metadata:
   name: engineering-vmcp
   namespace: toolhive-system
 spec:
-  config:
-    groupRef: engineering-tools
+  groupRef:
+    name: engineering-tools
   incomingAuth:
     type: oidc
     oidc:

docs/toolhive/guides-vmcp/composite-tools.mdx

@@ -44,8 +44,9 @@ metadata:
 spec:
   incomingAuth:
     type: anonymous
+  groupRef:
+    name: my-tools
   config:
-    groupRef: my-tools
     # ... other configuration ...
     compositeTools:
       - name: my_workflow
@@ -667,8 +668,9 @@ metadata:
 spec:
   incomingAuth:
     type: anonymous
+  groupRef:
+    name: research-tools
   config:
-    groupRef: research-tools
     aggregation:
       conflictResolution: prefix
       conflictResolutionConfig:
@@ -718,8 +720,9 @@ spec:
 
 ```yaml title="VirtualMCPServer resource"
 spec:
+  groupRef:
+    name: my-tools
   config:
-    groupRef: my-tools
     compositeToolRefs:
       - name: my-reusable-workflow
       - name: another-workflow

docs/toolhive/guides-vmcp/configuration.mdx

@@ -45,7 +45,8 @@ metadata:
   name: fetch
   namespace: toolhive-system
 spec:
-  groupRef: my-group # Reference to the MCPGroup
+  groupRef:
+    name: my-group # Reference to the MCPGroup
   image: ghcr.io/stackloklabs/gofetch/server
   transport: streamable-http
 ```
@@ -62,7 +63,8 @@ metadata:
   name: context7-proxy
   namespace: toolhive-system
 spec:
-  groupRef: my-group # Reference to the MCPGroup
+  groupRef:
+    name: my-group # Reference to the MCPGroup
   remoteURL: https://mcp.context7.com/mcp
   transport: streamable-http
   proxyPort: 8080
@@ -102,7 +104,8 @@ metadata:
   name: my-remote-tool
   namespace: toolhive-system
 spec:
-  groupRef: my-group # Reference to the MCPGroup
+  groupRef:
+    name: my-group # Reference to the MCPGroup
   remoteURL: https://mcp.example.com/mcp
   transport: streamable-http # or sse
 ```
@@ -114,7 +117,7 @@ custom headers, and SSRF protection details, see
 ## Create a VirtualMCPServer
 
 At minimum, a VirtualMCPServer requires a reference to an MCPGroup (via
-`config.groupRef`) and an authentication type:
+`groupRef`) and an authentication type:
 
 ```yaml
 apiVersion: toolhive.stacklok.dev/v1alpha1
@@ -123,8 +126,8 @@ metadata:
   name: my-vmcp
   namespace: toolhive-system
 spec:
-  config:
-    groupRef: my-group
+  groupRef:
+    name: my-group
   incomingAuth:
     type: anonymous # Disables authentication; do not use in production
 ```
@@ -202,8 +205,9 @@ metadata:
   name: my-vmcp
   namespace: toolhive-system
 spec:
+  groupRef:
+    name: my-group
   config:
-    groupRef: my-group
     operational:
       failureHandling:
         # Health check interval (how often to check each backend)

docs/toolhive/guides-vmcp/failure-handling.mdx

@@ -73,8 +73,9 @@ metadata:
   name: my-vmcp
   namespace: toolhive-system
 spec:
+  groupRef:
+    name: my-group
   config:
-    groupRef: my-group
     # highlight-start
     operational:
       failureHandling:
@@ -136,8 +137,9 @@ metadata:
   name: my-vmcp
   namespace: toolhive-system
 spec:
+  groupRef:
+    name: my-group
   config:
-    groupRef: my-group
     operational:
       failureHandling:
         # highlight-next-line
@@ -269,8 +271,9 @@ metadata:
   name: production-vmcp
   namespace: toolhive-system
 spec:
+  groupRef:
+    name: production-backends
   config:
-    groupRef: production-backends
     operational:
       failureHandling:
         # Check every 10 seconds
@@ -303,8 +306,9 @@ metadata:
   name: dev-vmcp
   namespace: toolhive-system
 spec:
+  groupRef:
+    name: dev-backends
   config:
-    groupRef: dev-backends
     operational:
       failureHandling:
         healthCheckInterval: 30s

docs/toolhive/guides-vmcp/optimizer.mdx

@@ -108,8 +108,8 @@ spec:
   embeddingServerRef:
     name: my-embedding
   # highlight-end
-  config:
-    groupRef: my-group
+  groupRef:
+    name: my-group
   incomingAuth:
     type: anonymous
 ```
@@ -191,8 +191,9 @@ in your VirtualMCPServer resource:
 
 ```yaml title="VirtualMCPServer resource"
 spec:
+  groupRef:
+    name: my-group
   config:
-    groupRef: my-group
     # highlight-start
     optimizer:
       embeddingServiceTimeout: 30s
@@ -289,8 +290,9 @@ metadata:
 spec:
   embeddingServerRef:
     name: full-embedding
+  groupRef:
+    name: my-tools
   config:
-    groupRef: my-tools
     optimizer:
       embeddingServiceTimeout: 15s
       maxToolsToReturn: 10