dhyansraj · dhyansraj · Aug 6, 2026 · Aug 6, 2026
diff --git a/.github/workflows/helm-release.yml b/.github/workflows/helm-release.yml
@@ -7,9 +7,9 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: "Version tag (e.g., v3.5.1)"
+        description: "Version tag (e.g., v3.5.2)"
         required: true
-        default: "v3.5.1"
+        default: "v3.5.2"
 
 jobs:
   release:

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -8,9 +8,9 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: "Version (e.g., v3.5.1)"
+        description: "Version (e.g., v3.5.2)"
         required: true
-        default: "v3.5.1"
+        default: "v3.5.2"
       environment:
         description: "Environment"
         type: choice

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -1,6 +1,42 @@
 # MCP Mesh Release Notes
 
-[Unreleased changes](https://github.com/dhyansraj/mcp-mesh/compare/v3.5.1...HEAD)
+[Unreleased changes](https://github.com/dhyansraj/mcp-mesh/compare/v3.5.2...HEAD)
+
+[Full Changelog](https://github.com/dhyansraj/mcp-mesh/compare/v3.5.1...v3.5.2)
+
+## v3.5.2 (2026-08-06)
+
+A provider can now withdraw itself from dependency resolution while a health check it declares reports unhealthy, and returns automatically once the check passes again — in all three runtimes, with no pod restart. v3.5.1's notes said Java and TypeScript readiness could not yet reflect a dependency outage; this closes that. It also fixes a live defect in 3.5.1: Python `@mesh.route` and A2A agents serve none of the probe endpoints the agent chart points at, so a Python gateway is restart-looped by the kubelet. No wire-protocol, registry-schema or dependency-resolution changes, and the only declaration-syntax change is the additive, opt-in health check itself.
+
+> **⚠️ Python `@mesh.route` and A2A agents need the 3.5.2 image.** On chart 3.5.1 every probe 404s and Kubernetes restarts a healthy gateway. TypeScript `/health` and `/ready` also change shape. Both in Notes.
+
+### 🩺 Health checks
+
+- **A provider withdraws itself while its own health check fails, in all three runtimes.** Declare `health_check` (Python, #1473), `@MeshHealthCheck` (Java, #1475) or `healthCheck` (TypeScript, #1481): while it reports unhealthy the agent stops heartbeating, the registry ages it out and consumers resolve to another provider. The process keeps running throughout and comes back on its own when the check passes again.
+- **A check that throws, or that cannot reach a conclusion, is `degraded` and keeps heartbeating**, so a broken probe cannot take a working agent out of the mesh. Python's malformed-return case mapped to unhealthy and was aligned with the other two (#1477).
+- **A health check never withdraws a `mesh.route` or A2A agent.** They are fan-out points, and withdrawing one takes down every path that enters through it, so the verdict never reaches the heartbeat there whatever the check reports — nor, since #1489, a Java gateway's `/ready`.
+
+### 🐍 Python probes and cadence
+
+- **⚠️ Route and A2A agents now serve `/livez`, `/ready` and `/health` (#1494).** They served **none** of them, so a Python gateway deployed with the agent chart — which has probed `/livez` and `/ready` since 3.5.1 — 404s every probe and gets restart-looped by the kubelet. This is a live bug in 3.5.1 rather than something 3.5.2 introduces, and hand-rolling a `/health`, as the examples do, does not satisfy the two probes the chart actually uses. A path the app already declares wins; the others are still registered.
+- **`MCP_MESH_HEALTH_CHECK_TTL` is honoured on Python (#1493).** TypeScript and Java already read it; Python took the cadence only from the `health_check_ttl` decorator argument, which is baked into the image. It is now tunable at deploy time from Helm values — which matters in the release that makes the TTL govern how fast a provider withdraws and how fast it returns.
+
+### 📘 TypeScript probes
+
+- **⚠️ `/ready` and `/health` reflect the health verdict instead of FastMCP's built-ins (#1487).** `/ready` answered a hardcoded 200 and `/health` a fixed string, so a TypeScript provider whose vendor was down kept receiving direct Service traffic after mesh consumers had already failed over. Both changes are breaking for anything that parses them — see Notes.
+
+### 🛠 Scaffold
+
+- **Vendor probes are selected by the resolved vendor rather than a substring match on the model string (#1484).** A gateway-prefixed model such as `bedrock/anthropic.claude-*` or `vertex_ai/gemini-*` matched the underlying vendor's name and got a probe for credentials it does not have — which, now that the check is load-bearing, withdrew a fully working provider. Those models get the generic skeleton instead; discovery tags still follow the model family.
+- **Generated helm values wire only credentials the agent can use (#1487, #1496).** An `llm-provider` gets the selected vendor's API key and, for a gateway model, none at all. `api`, `basic` and `llm-agent` get none either: an `llm-agent` resolves a provider through mesh DI, and the provider holds the credentials.
+- **Generated compose healthchecks probe `/livez`, not `/health` (#1495).** `/health` answers 503 while a declared check reports degraded or unhealthy, so a vendor outage blocked every dependent gated on `depends_on: condition: service_healthy` and made `docker compose ps` report a serving agent as unhealthy.
+
+### ⚠️ Notes
+
+- **⚠️ Upgrade Python route and A2A agents to the 3.5.2 image.** Chart 3.5.1 points startup and liveness at `/livez` and readiness at `/ready`, and no Python gateway has ever served either, so the kubelet restarts it on the startup probe. The image is the whole fix — no chart or code change is needed — and MCP agents, which have served all three endpoints for far longer, are unaffected.
+- **⚠️ TypeScript `/health` is now JSON.** It previously returned the literal `text/plain` string `✓ Ok`. Anything string-matching that response breaks; a check on the HTTP status still works.
+- **⚠️ TypeScript `/ready` and `/health` now answer 503** when a declared `healthCheck` reports `unhealthy` **or** `degraded`, so a failing agent leaves its Kubernetes Service endpoints. This matches Python and Java. **Agents with no `healthCheck` are unaffected.**
+- **Regenerating a scaffold changes two of its generated files.** Helm values no longer wire vendor API keys the agent cannot use — every arm removed was `optional: true`, so there is no runtime effect — and compose healthchecks move from `/health` to `/livez`. Files you have already generated are untouched until you regenerate them.
 
 [Full Changelog](https://github.com/dhyansraj/mcp-mesh/compare/v3.5.0...v3.5.1)
 

diff --git a/cmd/meshctl/templates/java/a2a-consumer/Dockerfile.tmpl b/cmd/meshctl/templates/java/a2a-consumer/Dockerfile.tmpl
@@ -1,5 +1,5 @@
 # Dockerfile for {{ .Name }} A2A consumer bridge (Java/Spring Boot)
-FROM mcpmesh/java-runtime:3.5.1
+FROM mcpmesh/java-runtime:3.5.2
 
 WORKDIR /app
 

diff --git a/cmd/meshctl/templates/java/a2a-consumer/pom.xml.tmpl b/cmd/meshctl/templates/java/a2a-consumer/pom.xml.tmpl
@@ -26,7 +26,7 @@
 
     <properties>
         <java.version>17</java.version>
-        <mcp-mesh.version>3.5.1</mcp-mesh.version>
+        <mcp-mesh.version>3.5.2</mcp-mesh.version>
     </properties>
 
     <dependencies>

diff --git a/cmd/meshctl/templates/java/api/Dockerfile.tmpl b/cmd/meshctl/templates/java/api/Dockerfile.tmpl
@@ -1,5 +1,5 @@
 # Dockerfile for {{ .Name }} MCP Mesh API gateway (Java/Spring Boot)
-FROM mcpmesh/java-runtime:3.5.1
+FROM mcpmesh/java-runtime:3.5.2
 
 WORKDIR /app
 

diff --git a/cmd/meshctl/templates/java/api/pom.xml.tmpl b/cmd/meshctl/templates/java/api/pom.xml.tmpl
@@ -21,7 +21,7 @@
 
     <properties>
         <java.version>17</java.version>
-        <mcp-mesh.version>3.5.1</mcp-mesh.version>
+        <mcp-mesh.version>3.5.2</mcp-mesh.version>
     </properties>
 
     <dependencies>

diff --git a/cmd/meshctl/templates/java/basic/Dockerfile.tmpl b/cmd/meshctl/templates/java/basic/Dockerfile.tmpl
@@ -1,5 +1,5 @@
 # Dockerfile for {{ .Name }} MCP Mesh agent (Java/Spring Boot)
-FROM mcpmesh/java-runtime:3.5.1
+FROM mcpmesh/java-runtime:3.5.2
 
 WORKDIR /app
 

diff --git a/cmd/meshctl/templates/java/basic/pom.xml.tmpl b/cmd/meshctl/templates/java/basic/pom.xml.tmpl
@@ -21,7 +21,7 @@
 
     <properties>
         <java.version>17</java.version>
-        <mcp-mesh.version>3.5.1</mcp-mesh.version>
+        <mcp-mesh.version>3.5.2</mcp-mesh.version>
     </properties>
 
     <dependencies>

diff --git a/cmd/meshctl/templates/java/llm-agent/Dockerfile.tmpl b/cmd/meshctl/templates/java/llm-agent/Dockerfile.tmpl
@@ -1,5 +1,5 @@
 # Dockerfile for {{ .Name }} MCP Mesh LLM agent (Java/Spring Boot)
-FROM mcpmesh/java-runtime:3.5.1
+FROM mcpmesh/java-runtime:3.5.2
 
 WORKDIR /app
 

diff --git a/cmd/meshctl/templates/java/llm-agent/pom.xml.tmpl b/cmd/meshctl/templates/java/llm-agent/pom.xml.tmpl
@@ -21,7 +21,7 @@
 
     <properties>
         <java.version>17</java.version>
-        <mcp-mesh.version>3.5.1</mcp-mesh.version>
+        <mcp-mesh.version>3.5.2</mcp-mesh.version>
     </properties>
 
     <dependencies>

diff --git a/cmd/meshctl/templates/java/llm-provider/Dockerfile.tmpl b/cmd/meshctl/templates/java/llm-provider/Dockerfile.tmpl
@@ -1,5 +1,5 @@
 # Dockerfile for {{ .Name }} MCP Mesh agent (Java/Spring Boot)
-FROM mcpmesh/java-runtime:3.5.1
+FROM mcpmesh/java-runtime:3.5.2
 
 WORKDIR /app
 

diff --git a/cmd/meshctl/templates/java/llm-provider/pom.xml.tmpl b/cmd/meshctl/templates/java/llm-provider/pom.xml.tmpl
@@ -21,7 +21,7 @@
 
     <properties>
         <java.version>17</java.version>
-        <mcp-mesh.version>3.5.1</mcp-mesh.version>
+        <mcp-mesh.version>3.5.2</mcp-mesh.version>
     </properties>
 
     <dependencies>

diff --git a/cmd/meshctl/templates/python/a2a-consumer/Dockerfile.tmpl b/cmd/meshctl/templates/python/a2a-consumer/Dockerfile.tmpl
@@ -1,5 +1,5 @@
 # Dockerfile for {{ .Name }} A2A consumer bridge
-FROM mcpmesh/python-runtime:3.5.1
+FROM mcpmesh/python-runtime:3.5.2
 
 WORKDIR /app
 

diff --git a/cmd/meshctl/templates/python/api/Dockerfile.tmpl b/cmd/meshctl/templates/python/api/Dockerfile.tmpl
@@ -1,5 +1,5 @@
 # Dockerfile for {{ .Name }} MCP Mesh API gateway
-FROM mcpmesh/python-runtime:3.5.1
+FROM mcpmesh/python-runtime:3.5.2
 
 WORKDIR /app
 

diff --git a/cmd/meshctl/templates/python/basic/Dockerfile.tmpl b/cmd/meshctl/templates/python/basic/Dockerfile.tmpl
@@ -1,5 +1,5 @@
 # Dockerfile for {{ .Name }} MCP Mesh agent
-FROM mcpmesh/python-runtime:3.5.1
+FROM mcpmesh/python-runtime:3.5.2
 
 WORKDIR /app
 

diff --git a/cmd/meshctl/templates/python/llm-agent/Dockerfile.tmpl b/cmd/meshctl/templates/python/llm-agent/Dockerfile.tmpl
@@ -1,5 +1,5 @@
 # Dockerfile for {{ .Name }} MCP Mesh LLM agent
-FROM mcpmesh/python-runtime:3.5.1
+FROM mcpmesh/python-runtime:3.5.2
 
 WORKDIR /app
 

diff --git a/cmd/meshctl/templates/python/llm-provider/Dockerfile.tmpl b/cmd/meshctl/templates/python/llm-provider/Dockerfile.tmpl
@@ -1,5 +1,5 @@
 # Dockerfile for {{ .Name }} MCP Mesh LLM provider
-FROM mcpmesh/python-runtime:3.5.1
+FROM mcpmesh/python-runtime:3.5.2
 
 WORKDIR /app
 

diff --git a/cmd/meshctl/templates/python/llm-provider/requirements.txt.tmpl b/cmd/meshctl/templates/python/llm-provider/requirements.txt.tmpl
@@ -9,5 +9,5 @@
 # is NOT part of the base install or the python-runtime base image. Without
 # this line the agent starts and registers normally, then fails on its first
 # LLM call.
-mcp-mesh[litellm]==3.5.1
+mcp-mesh[litellm]==3.5.2
 {{- end }}
diff --git a/cmd/meshctl/templates/typescript/a2a-consumer/Dockerfile.tmpl b/cmd/meshctl/templates/typescript/a2a-consumer/Dockerfile.tmpl
@@ -1,5 +1,5 @@
 # Dockerfile for {{ .Name }} A2A consumer bridge
-FROM mcpmesh/typescript-runtime:3.5.1
+FROM mcpmesh/typescript-runtime:3.5.2
 
 WORKDIR /app
 

diff --git a/cmd/meshctl/templates/typescript/a2a-consumer/package.json.tmpl b/cmd/meshctl/templates/typescript/a2a-consumer/package.json.tmpl
@@ -13,7 +13,7 @@
     "dev": "tsx watch src/index.ts"
   },
   "dependencies": {
-    "@mcpmesh/sdk": "^3.5.1",
+    "@mcpmesh/sdk": "^3.5.2",
     "fastmcp": "^3.34.0",
     "zod": "^3.24.0"
   },

diff --git a/cmd/meshctl/templates/typescript/api/Dockerfile.tmpl b/cmd/meshctl/templates/typescript/api/Dockerfile.tmpl
@@ -1,5 +1,5 @@
 # Dockerfile for {{ .Name }} MCP Mesh API gateway
-FROM mcpmesh/typescript-runtime:3.5.1
+FROM mcpmesh/typescript-runtime:3.5.2
 
 WORKDIR /app
 

diff --git a/cmd/meshctl/templates/typescript/api/package.json.tmpl b/cmd/meshctl/templates/typescript/api/package.json.tmpl
@@ -12,7 +12,7 @@
     "dev": "tsx watch src/index.ts"
   },
   "dependencies": {
-    "@mcpmesh/sdk": "^3.5.1",
+    "@mcpmesh/sdk": "^3.5.2",
     "express": "^4.21.2"
   },
   "devDependencies": {

diff --git a/cmd/meshctl/templates/typescript/basic/Dockerfile.tmpl b/cmd/meshctl/templates/typescript/basic/Dockerfile.tmpl
@@ -1,5 +1,5 @@
 # Dockerfile for {{ .Name }} MCP Mesh agent
-FROM mcpmesh/typescript-runtime:3.5.1
+FROM mcpmesh/typescript-runtime:3.5.2
 
 WORKDIR /app
 

diff --git a/cmd/meshctl/templates/typescript/basic/package.json.tmpl b/cmd/meshctl/templates/typescript/basic/package.json.tmpl
@@ -12,7 +12,7 @@
     "dev": "tsx watch src/index.ts"
   },
   "dependencies": {
-    "@mcpmesh/sdk": "^3.5.1"
+    "@mcpmesh/sdk": "^3.5.2"
   },
   "devDependencies": {
     "@types/node": "^22.18.0",

diff --git a/cmd/meshctl/templates/typescript/llm-agent/Dockerfile.tmpl b/cmd/meshctl/templates/typescript/llm-agent/Dockerfile.tmpl
@@ -1,5 +1,5 @@
 # Dockerfile for {{ .Name }} MCP Mesh LLM agent
-FROM mcpmesh/typescript-runtime:3.5.1
+FROM mcpmesh/typescript-runtime:3.5.2
 
 WORKDIR /app
 

diff --git a/cmd/meshctl/templates/typescript/llm-agent/package.json.tmpl b/cmd/meshctl/templates/typescript/llm-agent/package.json.tmpl
@@ -12,7 +12,7 @@
     "dev": "tsx watch src/index.ts"
   },
   "dependencies": {
-    "@mcpmesh/sdk": "^3.5.1"
+    "@mcpmesh/sdk": "^3.5.2"
   },
   "devDependencies": {
     "@types/node": "^22.18.0",

diff --git a/cmd/meshctl/templates/typescript/llm-provider/Dockerfile.tmpl b/cmd/meshctl/templates/typescript/llm-provider/Dockerfile.tmpl
@@ -1,5 +1,5 @@
 # Dockerfile for {{ .Name }} MCP Mesh LLM provider
-FROM mcpmesh/typescript-runtime:3.5.1
+FROM mcpmesh/typescript-runtime:3.5.2
 
 WORKDIR /app
 

diff --git a/cmd/meshctl/templates/typescript/llm-provider/package.json.tmpl b/cmd/meshctl/templates/typescript/llm-provider/package.json.tmpl
@@ -12,7 +12,7 @@
     "dev": "tsx watch src/index.ts"
   },
   "dependencies": {
-    "@mcpmesh/sdk": "^3.5.1"
+    "@mcpmesh/sdk": "^3.5.2"
   },
   "devDependencies": {
     "@types/node": "^22.18.0",

diff --git a/docs/00-why-mcp-mesh/index.md b/docs/00-why-mcp-mesh/index.md
@@ -121,7 +121,7 @@ meshctl scaffold --compose --observability
 
 # Or deploy to Kubernetes (OCI registry)
 helm install my-mesh oci://ghcr.io/dhyansraj/mcp-mesh/mcp-mesh-core \
-  --version 3.5.1 -n mcp-mesh --create-namespace
+  --version 3.5.2 -n mcp-mesh --create-namespace
 ```
 
 ### 5. Built-in Observability

diff --git a/docs/02-local-development.md b/docs/02-local-development.md
@@ -97,7 +97,7 @@ graph LR
     <dependency>
         <groupId>io.mcp-mesh</groupId>
         <artifactId>mcp-mesh-spring-boot-starter</artifactId>
-        <version>3.5.1</version>
+        <version>3.5.2</version>
     </dependency>
     ```