stacklok · ChrisJBurns · Jun 10, 2026 · Jun 10, 2026 · Jun 10, 2026 · Jun 10, 2026
diff --git a/.github/upstream-projects.yaml b/.github/upstream-projects.yaml
@@ -35,7 +35,7 @@ projects:
 
   - id: toolhive
     repo: stacklok/toolhive
-    version: v0.29.1
+    version: v0.29.3
     # toolhive is a monorepo covering the CLI, the Kubernetes
     # operator, and the vMCP gateway. It also introduces cross-
     # cutting features that land in concepts/, integrations/,

diff --git a/docs/toolhive/guides-k8s/deploy-operator.mdx b/docs/toolhive/guides-k8s/deploy-operator.mdx
@@ -72,7 +72,7 @@ groups using these values:
 | Value                     | Description                                           | Default |
 | ------------------------- | ----------------------------------------------------- | ------- |
 | `crds.install.server`     | Install server CRDs (MCPServer, MCPRemoteProxy, etc.) | `true`  |
-| `crds.install.registry`   | Install registry CRDs (MCPRegistry)                   | `true`  |
+| `crds.install.registry`   | Install registry CRDs (MCPRegistry, deprecated)       | `true`  |
 | `crds.install.virtualMcp` | Install vMCP CRDs (VirtualMCPServer, etc.)            | `true`  |
 | `crds.keep`               | Preserve CRDs when uninstalling the chart             | `true`  |
 

diff --git a/docs/toolhive/guides-registry/quickstart.mdx b/docs/toolhive/guides-registry/quickstart.mdx
@@ -16,6 +16,17 @@ This quickstart covers the standalone Registry Server that you host and curate
 yourself. If you're looking for the built-in catalog that ships with the
 ToolHive CLI and UI, see the [Introduction](./intro.mdx) for a comparison.
 
+:::warning[MCPRegistry CRD is deprecated]
+
+This quickstart uses the `MCPRegistry` CRD, which is deprecated and will be
+removed in a future release. The CRD remains fully functional and is the fastest
+path to a running Registry Server for experimentation. For new long-lived
+deployments, use the [toolhive-registry-server Helm chart](./deploy-helm.mdx)
+instead. See [Deploy the Registry Server](./deployment.mdx) for a comparison of
+the deployment methods.
+
+:::
+
 ## What you'll learn
 
 - How to install the ToolHive Operator, which bundles the `MCPRegistry` CRD

diff --git a/docs/toolhive/reference/crds/index.mdx b/docs/toolhive/reference/crds/index.mdx
@@ -57,7 +57,7 @@ references.
     type: 'link',
     href: '/toolhive/reference/crds/mcpregistry',
     label: 'MCPRegistry',
-    description: 'Deploy a ToolHive Registry Server.',
+    description: 'Deploy a ToolHive Registry Server (deprecated).',
   }}
 />
 

diff --git a/docs/toolhive/reference/crds/mcpregistry.mdx b/docs/toolhive/reference/crds/mcpregistry.mdx
@@ -8,6 +8,12 @@ toc_max_heading_level: 4
 
 `MCPRegistry` deploys a [ToolHive Registry Server](../../guides-registry/intro.mdx) in the cluster. The operator watches `MCPRegistry` resources and provisions the Registry Server, its PostgreSQL backing, and the configured sources (Git, ConfigMap, URL, or Kubernetes discovery) that populate its catalog of MCP server definitions.
 
+:::warning[Deprecated]
+
+The `MCPRegistry` CRD is deprecated and will be removed in a future release. The CRD remains fully functional, but `kubectl` now prints a deprecation warning on apply or get and the operator emits a `Warning` event recommending the [`toolhive-registry-server` Helm chart](https://github.com/stacklok/toolhive-registry-server). For new deployments, see [Deploy with Helm](../../guides-registry/deploy-helm.mdx).
+
+:::
+
 **API:** `toolhive.stacklok.dev/v1beta1`
  · **Scope:** Namespaced · **Short names:** `mcpreg`, `registry`
 

diff --git a/scripts/lib/crd-intros.mjs b/scripts/lib/crd-intros.mjs
@@ -82,11 +82,11 @@ export const intros = {
   MCPRegistry: {
     slug: 'mcpregistry',
     group: 'core',
-    summary: 'Deploy a ToolHive Registry Server.',
+    summary: 'Deploy a ToolHive Registry Server (deprecated).',
     description:
       'Schema reference for MCPRegistry, which declares a ToolHive Registry Server deployment managed by the operator.',
     intro:
-      '`MCPRegistry` deploys a [ToolHive Registry Server](../../guides-registry/intro.mdx) in the cluster. The operator watches `MCPRegistry` resources and provisions the Registry Server, its PostgreSQL backing, and the configured sources (Git, ConfigMap, URL, or Kubernetes discovery) that populate its catalog of MCP server definitions.',
+      '`MCPRegistry` deploys a [ToolHive Registry Server](../../guides-registry/intro.mdx) in the cluster. The operator watches `MCPRegistry` resources and provisions the Registry Server, its PostgreSQL backing, and the configured sources (Git, ConfigMap, URL, or Kubernetes discovery) that populate its catalog of MCP server definitions.\n\n:::warning[Deprecated]\n\nThe `MCPRegistry` CRD is deprecated and will be removed in a future release. The CRD remains fully functional, but `kubectl` now prints a deprecation warning on apply or get and the operator emits a `Warning` event recommending the [`toolhive-registry-server` Helm chart](https://github.com/stacklok/toolhive-registry-server). For new deployments, see [Deploy with Helm](../../guides-registry/deploy-helm.mdx).\n\n:::',
   },
 
   // Shared configuration - grouping, then auth, then observability/behavior,

diff --git a/static/api-specs/crds/index.json b/static/api-specs/crds/index.json
@@ -148,7 +148,7 @@
       "registry"
     ],
     "scope": "Namespaced",
-    "description": "MCPRegistry is the Schema for the mcpregistries API",
+    "description": "MCPRegistry is the Schema for the mcpregistries API.\n\nThe MCPRegistry CRD is deprecated and will be removed in a future release.\nInstall the ToolHive registry server via the toolhive-registry-server Helm chart\ninstead: https://github.com/stacklok/toolhive-registry-server",
     "references": [],
     "referencedBy": [],
     "slug": "mcpregistry"

diff --git a/static/api-specs/crds/mcpexternalauthconfigs.schema.json b/static/api-specs/crds/mcpexternalauthconfigs.schema.json
@@ -376,7 +376,7 @@
                       "type": "object"
                     },
                     "tls": {
-                      "description": "TLS configures TLS for connections to the Redis/Valkey master.\nPresence of this field enables TLS. Omit to use plaintext.",
+                      "description": "TLS configures TLS for connections to the Redis/Valkey master or cluster nodes.\nPresence of this field enables TLS. Omit to use plaintext.",
                       "properties": {
                         "caCertSecretRef": {
                           "description": "CACertSecretRef references a Secret containing a PEM-encoded CA certificate\nfor verifying the server. When not specified, system root CAs are used.",

diff --git a/static/api-specs/crds/mcpregistries.schema.json b/static/api-specs/crds/mcpregistries.schema.json
@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "MCPRegistry",
-  "description": "MCPRegistry is the Schema for the mcpregistries API",
+  "description": "MCPRegistry is the Schema for the mcpregistries API.\n\nThe MCPRegistry CRD is deprecated and will be removed in a future release.\nInstall the ToolHive registry server via the toolhive-registry-server Helm chart\ninstead: https://github.com/stacklok/toolhive-registry-server",
   "x-kubernetes-group": "toolhive.stacklok.dev",
   "x-kubernetes-kind": "MCPRegistry",
   "x-kubernetes-version": "v1beta1",

diff --git a/static/api-specs/crds/mcpremoteproxies.schema.json b/static/api-specs/crds/mcpremoteproxies.schema.json
@@ -228,7 +228,7 @@
           "type": "object"
         },
         "oidcConfigRef": {
-          "description": "OIDCConfigRef references a shared MCPOIDCConfig resource for OIDC authentication.\nThe referenced MCPOIDCConfig must exist in the same namespace as this MCPRemoteProxy.\nPer-server overrides (audience, scopes) are specified here; shared provider config\nlives in the MCPOIDCConfig resource.",
+          "description": "OIDCConfigRef references a shared MCPOIDCConfig resource for OIDC authentication.\nThe referenced MCPOIDCConfig must exist in the same namespace as this MCPRemoteProxy.\nPer-server overrides (audience, scopes) are specified here; shared provider config\nlives in the MCPOIDCConfig resource.\n\nSECURITY: if this field is omitted and no other authentication source is configured,\nthe proxy runs UNAUTHENTICATED. It accepts every request that can reach its port and\nforwards it to the remote MCP server under a synthetic local-user identity, with no\ntoken or credential check. Set this field to enforce identity-based access control\nper request.",
           "properties": {
             "audience": {
               "description": "Audience is the expected audience for token validation.\nThis MUST be unique per server to prevent token replay attacks.",

diff --git a/static/api-specs/crds/mcpservers.schema.json b/static/api-specs/crds/mcpservers.schema.json
@@ -224,7 +224,7 @@
           "type": "integer"
         },
         "oidcConfigRef": {
-          "description": "OIDCConfigRef references a shared MCPOIDCConfig resource for OIDC authentication.\nThe referenced MCPOIDCConfig must exist in the same namespace as this MCPServer.\nPer-server overrides (audience, scopes) are specified here; shared provider config\nlives in the MCPOIDCConfig resource.",
+          "description": "OIDCConfigRef references a shared MCPOIDCConfig resource for OIDC authentication.\nThe referenced MCPOIDCConfig must exist in the same namespace as this MCPServer.\nPer-server overrides (audience, scopes) are specified here; shared provider config\nlives in the MCPOIDCConfig resource.\n\nSECURITY: if this field is omitted and no other authentication source is configured,\nthe proxy runs UNAUTHENTICATED. It accepts every request that can reach its port and\nforwards it to the MCP server under a synthetic local-user identity, with no token or\ncredential check. Set this field to enforce identity-based access control per request.",
           "properties": {
             "audience": {
               "description": "Audience is the expected audience for token validation.\nThis MUST be unique per server to prevent token replay attacks.",

diff --git a/static/api-specs/crds/virtualmcpservers.schema.json b/static/api-specs/crds/virtualmcpservers.schema.json
@@ -267,7 +267,7 @@
                       "type": "object"
                     },
                     "tls": {
-                      "description": "TLS configures TLS for connections to the Redis/Valkey master.\nPresence of this field enables TLS. Omit to use plaintext.",
+                      "description": "TLS configures TLS for connections to the Redis/Valkey master or cluster nodes.\nPresence of this field enables TLS. Omit to use plaintext.",
                       "properties": {
                         "caCertSecretRef": {
                           "description": "CACertSecretRef references a Secret containing a PEM-encoded CA certificate\nfor verifying the server. When not specified, system root CAs are used.",

diff --git a/static/api-specs/publisher-provided.schema.json b/static/api-specs/publisher-provided.schema.json
@@ -105,6 +105,11 @@
           "minimum": 1,
           "maximum": 65535
         },
+        "stateless": {
+          "type": "boolean",
+          "description": "Whether the server only supports POST requests (no SSE/GET).",
+          "default": false
+        },
         "oauth_config": {
           "description": "OAuth/OIDC configuration for remote servers",
           "$ref": "#/$defs/oauth_config"

diff --git a/static/api-specs/toolhive-api.yaml b/static/api-specs/toolhive-api.yaml
@@ -3321,6 +3321,9 @@ components:
           description: RepositoryURL is the URL to the source code repository for
             the server
           type: string
+        stateless:
+          description: Stateless indicates the server only supports POST (no SSE/GET)
+          type: boolean
         status:
           description: Status indicates whether the server is currently active or
             deprecated
@@ -3525,6 +3528,9 @@ components:
           description: RepositoryURL is the URL to the source code repository for
             the server
           type: string
+        stateless:
+          description: Stateless indicates the server only supports POST (no SSE/GET)
+          type: boolean
         status:
           description: Status indicates whether the server is currently active or
             deprecated