AI-374: Warn against passing secrets through MCP factory_argument (#1688)

* AI-374: Warn against passing secrets through MCP factory_argument

`factory_argument` is serialized as an activity argument and therefore
recorded in workflow history, which is not obvious from the API surface.
Document that in the docstrings and READMEs for the MCP support in the
openai_agents and google_adk_agents contrib plugins, and point users at
resolving credentials worker-side inside the factory instead.

* AI-374: Correct and tighten the factory_argument secrets warning

Fix the claim that factory_argument is sent to every MCP activity, which
holds for stateless servers but not stateful ones, and document that a
zero-parameter stateless factory silently discards the value while it is
still written to history. Drop the maturity-badge glyph, qualify the web
UI claim for users running a payload codec, and state the factory-side
contract on the three provider docstrings.

* fix AI slop

Author: xumaple

temporalio/contrib/google_adk_agents/README.md

@@ -166,6 +166,10 @@ worker = Worker(
 )
 ```
 
+`TemporalMcpToolSet` also accepts an optional `factory_argument`. It is sent to the toolset activities and passed to the registered `toolset_factory` when the `McpToolset` is created.
+
+**Do not pass secrets, credentials, or API keys through `factory_argument`.** It is an activity argument, so it is recorded in workflow history and, without a payload codec, visible in the web UI. Resolve credentials worker-side inside the toolset factory instead.
+
 ### Local ADK Runs
 
 The same agent definitions can also be exercised outside Temporal with

temporalio/contrib/google_adk_agents/_mcp.py

@@ -221,10 +221,17 @@ def __init__(
     ):
         """Initializes the Temporal MCP toolset.
 
+        .. warning::
+            Do not pass secrets, credentials, or API keys through ``factory_argument``. It
+            is an activity argument, so it is recorded in workflow history and, without a
+            payload codec, visible in the web UI. Resolve credentials worker-side inside the
+            toolset factory instead.
+
         Args:
             name: Name of the toolset (used for activity naming).
             config: Optional activity configuration.
-            factory_argument: Optional argument passed to toolset factory.
+            factory_argument: Optional argument passed to ``toolset_factory``.
+                Must not contain secrets.
             not_in_workflow_toolset: Optional factory that returns the
                 underlying ``McpToolset`` to use when this wrapper executes
                 outside ``workflow.in_workflow()``, such as local ADK runs.

temporalio/contrib/openai_agents/README.md

@@ -447,6 +447,14 @@ For implementation details and examples, see the [samples repository](https://gi
 When using stateful servers, the dedicated worker maintaining the connection may fail due to network issues or server problems. When this happens, Temporal raises an `ApplicationError` and cannot automatically recover because it cannot restore the lost server state.
 To recover from such failures, you need to implement your own application-level retry logic.
 
+### Factory Arguments
+
+Both `stateless_mcp_server()` and `stateful_mcp_server()` accept an optional `factory_argument`, which is passed to the registered server factory when the MCP server is created.
+
+A stateless factory that declares no parameters — like the `lambda: MCPServerStdio(...)` example above — ignores the value, but it is still recorded in history.
+
+**Do not pass secrets, credentials, or API keys through `factory_argument`.** It is an activity argument, so it is recorded in workflow history and, without a payload codec, visible in the web UI. Resolve credentials worker-side inside the server factory instead.
+
 ### Hosted MCP Tool
 
 For network-accessible MCP servers, you can also use `HostedMCPTool` from the OpenAI Agents SDK, which uses an MCP client hosted by OpenAI.

temporalio/contrib/openai_agents/_mcp.py

@@ -152,7 +152,8 @@ def __init__(
         Args:
             name: The name of the MCP server.
             server_factory: A function which will produce MCPServer instances. It should return a new server each time
-                so that state is not shared between workflow runs.
+                so that state is not shared between workflow runs. It may accept a single positional parameter, which
+                receives a ``factory_argument`` from the workflow.
         """
         self._server_factory = server_factory
 
@@ -437,7 +438,8 @@ def __init__(
         Args:
             name: The name of the MCP server.
             server_factory: A function which will produce MCPServer instances. It should return a new server each time
-                so that state is not shared between workflow runs
+                so that state is not shared between workflow runs. It receives an optional ``factory_argument`` from the
+                workflow.
         """
         self._server_factory = server_factory
         self._name = name + "-stateful"

temporalio/contrib/openai_agents/workflow.py

@@ -291,12 +291,19 @@ def stateless_mcp_server(
     and you don't need to maintain state between operations. It should be preferred to stateful when possible due to its
     superior durability guarantees.
 
+    .. warning::
+        Do not pass secrets, credentials, or API keys through ``factory_argument``. It is an
+        activity argument, so it is recorded in workflow history and, without a payload codec,
+        visible in the web UI. Resolve credentials worker-side inside the server factory
+        instead.
+
     Args:
         name: A string name for the server. Should match that provided in the plugin.
         config: Optional activity configuration for MCP operation activities.
                Defaults to 1-minute start-to-close timeout.
         cache_tools_list: If true, the list of tools will be cached for the duration of the server
-        factory_argument: Optional argument to be provided to the factory when producing an MCPServer
+        factory_argument: Optional argument to be provided to the factory when producing an MCPServer.
+               Must not contain secrets.
     """
     from temporalio.contrib.openai_agents._mcp import (
         _StatelessMCPServerReference,
@@ -326,13 +333,20 @@ def stateful_mcp_server(
     The caller will have to handle cases where the dedicated worker fails, as Temporal is
     unable to seamlessly recreate any lost state in that case.
 
+    .. warning::
+        Do not pass secrets, credentials, or API keys through ``factory_argument``. It is an
+        activity argument, so it is recorded in workflow history and, without a payload codec,
+        visible in the web UI. Resolve credentials worker-side inside the server factory
+        instead.
+
     Args:
         name: A string name for the server. Should match that provided in the plugin.
         config: Optional activity configuration for MCP operation activities.
                Defaults to 1-minute start-to-close and 30-second schedule-to-start timeouts.
         server_session_config: Optional activity configuration for the connection activity.
                        Defaults to 1-hour start-to-close timeout.
-        factory_argument: Optional argument to be provided to the factory when producing an MCPServer
+        factory_argument: Optional argument to be provided to the factory when producing an MCPServer.
+               Must not contain secrets.
     """
     from temporalio.contrib.openai_agents._mcp import (
         _StatefulMCPServerReference,