diff --git a/packages/workflow-executor/README.md b/packages/workflow-executor/README.md
index be223ab768..b23d571e9a 100644
--- a/packages/workflow-executor/README.md
+++ b/packages/workflow-executor/README.md
@@ -72,6 +72,20 @@ Both values are already in your agent's environment variables. `FOREST_ENV_SECRE
 
 ---
 
+## OAuth-protected MCP connectors
+
+When your workflows use OAuth-protected MCP connectors, the executor stores each user's OAuth credentials in its database, encrypted at rest. Provide the encryption key the same way as the other secrets (in `.env`, or with `-e` on `docker run`):
+
+| Variable | Description |
+| --- | --- |
+| `FOREST_EXECUTOR_ENCRYPTION_KEY` | At-rest encryption key (AES-256-GCM) for the OAuth credentials the executor stores. Generate with `openssl rand -hex 32`. Use a **separate** secret from `FOREST_AUTH_SECRET`. |
+
+- **Required only for OAuth-protected MCP connectors**, and read lazily — an executor that stores no such credentials boots and runs fine without it.
+- **Use the same value on every instance that shares a database.** Otherwise an instance cannot decrypt credentials stored by another.
+- **Treat it as permanent: there is no managed rotation.** Changing it forces every affected user to reconnect their OAuth-protected MCP connectors.
+
+---
+
 ## Testing only
 
 The following modes skip the database requirement but are **not suitable for production** — state is lost on restart.