diff --git a/docs/public/schemas/mcp-gateway-config.schema.json b/docs/public/schemas/mcp-gateway-config.schema.json
index ae1f20cc12..2022ebf4be 100644
--- a/docs/public/schemas/mcp-gateway-config.schema.json
+++ b/docs/public/schemas/mcp-gateway-config.schema.json
@@ -225,6 +225,11 @@
           "description": "Tool invocation timeout in seconds. The gateway enforces this timeout for individual tool/method calls to MCP servers.",
           "minimum": 1,
           "default": 60
+        },
+        "payloadDir": {
+          "type": "string",
+          "description": "Directory path for storing large payload JSON files for authenticated clients.",
+          "minLength": 1
         }
       },
       "required": ["port", "domain", "apiKey"],
diff --git a/docs/src/content/docs/reference/mcp-gateway.md b/docs/src/content/docs/reference/mcp-gateway.md
index 6563f8a685..8f8f4d296a 100644
--- a/docs/src/content/docs/reference/mcp-gateway.md
+++ b/docs/src/content/docs/reference/mcp-gateway.md
@@ -7,7 +7,7 @@ sidebar:
 
 # MCP Gateway Specification
 
-**Version**: 1.7.0  
+**Version**: 1.8.0  
 **Status**: Draft Specification  
 **Latest Version**: [mcp-gateway](/gh-aw/reference/mcp-gateway/)  
 **JSON Schema**: [mcp-gateway-config.schema.json](/gh-aw/schemas/mcp-gateway-config.schema.json)  
@@ -245,6 +245,7 @@ The `gateway` section is required and configures gateway-specific behavior:
 | `apiKey` | string | Yes | API key for authentication |
 | `startupTimeout` | integer | No | Server startup timeout in seconds (default: 30) |
 | `toolTimeout` | integer | No | Tool invocation timeout in seconds (default: 60) |
+| `payloadDir` | string | No | Directory path for storing large payload JSON files for authenticated clients |
 
 #### 4.1.3a Top-Level Configuration Fields
 
@@ -1347,6 +1348,14 @@ Content-Type: application/json
 
 ## Change Log
 
+### Version 1.8.0 (Draft)
+
+- **Added**: `payloadDir` field to gateway configuration (Section 4.1.3)
+  - Optional directory path where the gateway places large payload JSON files for authenticated clients
+  - Enables efficient handling of large response payloads by offloading them to the filesystem
+  - Gateway implementations MUST ensure proper isolation between clients' payload files when this feature is used
+  - Payload files are accessible to clients authenticated with the corresponding API key
+
 ### Version 1.7.0 (Draft)
 
 - **Added**: Comprehensive volume mount documentation for stdio servers (Section 4.1.5)
diff --git a/pkg/workflow/schemas/mcp-gateway-config.schema.json b/pkg/workflow/schemas/mcp-gateway-config.schema.json
index ae65b8015d..9f9982bf94 100644
--- a/pkg/workflow/schemas/mcp-gateway-config.schema.json
+++ b/pkg/workflow/schemas/mcp-gateway-config.schema.json
@@ -189,6 +189,11 @@
           "description": "Tool invocation timeout in seconds. The gateway enforces this timeout for individual tool/method calls to MCP servers.",
           "minimum": 1,
           "default": 60
+        },
+        "payloadDir": {
+          "type": "string",
+          "description": "Directory path for storing large payload JSON files for authenticated clients.",
+          "minLength": 1
         }
       },
       "required": ["port", "domain", "apiKey"],