diff --git a/agent.py b/agent.py
index a47a501..6e3fdd5 100644
--- a/agent.py
+++ b/agent.py
@@ -73,10 +73,25 @@ class AgentBuilder(A2AAgent[BuilderConfig, NoAuth]):
         public: bool = True,
         version: str = "0.1.0",
     ) -> dict:
-        bucket = getattr(ctx.workspace, "bucket", None)
+        # ctx.workspace is a property that raises PermissionError when no
+        # workspace was provisioned by the runtime (e.g. when this agent
+        # is invoked over the MCP gateway, which has no grant flow). Catch
+        # it and surface a clean "I need to run through the orchestrator"
+        # error rather than letting it bubble up as a 500.
+        try:
+            bucket = getattr(ctx.workspace, "bucket", None)
+        except PermissionError:
+            bucket = None
         if not bucket:
-            return {"error": "no workspace grant; refusing to run"}
-        cp_jwt = ctx.cp_jwt
+            return {
+                "error": (
+                    "no workspace grant; this agent only runs through the "
+                    "a2acloud platform orchestrator (not the local MCP "
+                    "gateway), because it needs a scoped MinIO bucket and "
+                    "a CP JWT to write + deploy your project."
+                ),
+            }
+        cp_jwt = getattr(ctx, "cp_jwt", None)
         if not cp_jwt:
             return {
                 "error": "no CP JWT forwarded — caller must run me through "