From a2098eea276bb31d10545a6d36dba76b37663eb7 Mon Sep 17 00:00:00 2001
From: Omar Abdelwahab <omara@fb.com>
Date: Fri, 7 Nov 2025 13:50:23 -0800
Subject: [PATCH] docs: add comprehensive docstring for
 MCPProviderDataValidator

Adds inline documentation to help users understand:
- How to structure provider_data in HTTP requests
- Where to place mcp_headers vs mcp_authorization
- Security requirements (no Authorization in headers)
- Token format requirements (without Bearer prefix)
- Example usage with multiple MCP endpoints
---
 .../model_context_protocol/config.py          | 31 ++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/src/llama_stack/providers/remote/tool_runtime/model_context_protocol/config.py b/src/llama_stack/providers/remote/tool_runtime/model_context_protocol/config.py
index 73f891c20..c78a043a1 100644
--- a/src/llama_stack/providers/remote/tool_runtime/model_context_protocol/config.py
+++ b/src/llama_stack/providers/remote/tool_runtime/model_context_protocol/config.py
@@ -10,9 +10,38 @@ from pydantic import BaseModel
 
 
 class MCPProviderDataValidator(BaseModel):
-    # mcp_endpoint => dict of headers to send
+    """
+    Validator for MCP provider-specific data passed via request headers.
+
+    This data structure is passed in the X-LlamaStack-Provider-Data header
+    to provide MCP endpoint-specific configuration.
+
+    Example usage:
+        HTTP Request Headers:
+            X-LlamaStack-Provider-Data: {
+                "mcp_headers": {
+                    "http://weather-mcp.com": {
+                        "X-Trace-ID": "trace-123",
+                        "X-Request-ID": "req-456"
+                    }
+                },
+                "mcp_authorization": {
+                    "http://weather-mcp.com": "weather_api_token_xyz"
+                }
+            }
+
+    Security Note:
+        - Authorization header MUST NOT be placed in mcp_headers
+        - Use the dedicated mcp_authorization field instead
+        - Each MCP endpoint can have its own separate token
+        - Tokens are provided WITHOUT the "Bearer " prefix (added automatically)
+    """
+
+    # mcp_endpoint => dict of headers to send (excluding Authorization)
     mcp_headers: dict[str, dict[str, str]] | None = None
+
     # mcp_endpoint => authorization token (without "Bearer " prefix)
+    # Example: {"http://server.com": "token123"}
     mcp_authorization: dict[str, str] | None = None