docs(mcp-server): document the tokenTtl option

product/embed/mcp-server.mdx

@@ -55,6 +55,8 @@ The standalone Forest MCP Server is configured entirely through environment vari
 | `MCP_SERVER_PORT` | No | `3931` | Port the standalone server listens on. |
 | `FOREST_MCP_ENABLED_TOOLS` | No | all tools | Comma-separated allowlist of tools to expose (see [Restrict tools](#restrict-tools)). |
 | `FOREST_AGENT_URL` | No | your environment's back-end URL | URL the MCP Server uses to reach your back-end's data layer. |
+| `FOREST_MCP_ACCESS_TOKEN_TTL_SECONDS` | No | `3600` (1 hour) | Shortens the OAuth access token lifetime (see [Token lifetimes](#token-lifetimes)). Minimum `60`. |
+| `FOREST_MCP_REFRESH_TOKEN_TTL_SECONDS` | No | unbounded | Shortens the time between two interactive logins (see [Token lifetimes](#token-lifetimes)). Minimum `60`. |
 
 <Note>
   Set `FOREST_AGENT_URL` when the MCP Server runs next to a self-hosted back-end reachable at an internal address (e.g. `http://localhost:3310`), so tool calls hit it directly instead of the public back-end URL registered in Forest.
@@ -168,6 +170,50 @@ When `enabledTools` is not set, all tools are enabled by default.
   `describeCollection` is always enabled, even if omitted from the list, as it is required for the MCP server to function properly.
 </Info>
 
+## Token lifetimes
+
+The MCP server issues OAuth tokens whose lifetimes come from Forest: **1 hour** (3600s) for an access token, **8 days** (691200s) for a refresh token. Forest re-grants those 8 days on *every* refresh, so without `refreshTokenSeconds` an assistant that keeps working is never asked to sign in again. You can shorten them with `tokenTtl`, to reduce how long a leaked token stays usable and to force users to log in again periodically.
+
+<CodeGroup>
+
+```javascript Mounted on agent
+agent.mountAiMcpServer({
+  tokenTtl: {
+    accessTokenSeconds: 900,
+    refreshTokenSeconds: 86400,
+  },
+});
+```
+
+```bash Standalone
+FOREST_MCP_ACCESS_TOKEN_TTL_SECONDS=900 \
+  FOREST_MCP_REFRESH_TOKEN_TTL_SECONDS=86400 \
+  FOREST_ENV_SECRET=xxx FOREST_AUTH_SECRET=xxx npx forest-mcp-server
+```
+
+</CodeGroup>
+
+The two settings differ in what your users notice:
+
+| Setting               | Forest default | What it bounds                                | Effect on the user                                          |
+| --------------------- | -------------------- | --------------------------------------------- | ----------------------------------------------------------- |
+| `accessTokenSeconds`  | 1 hour               | How long an issued access token drives the MCP server | None — the AI assistant silently obtains a new one   |
+| `refreshTokenSeconds` | unbounded            | The time between two **interactive logins**   | Once it elapses, the user logs in through the browser again |
+
+`refreshTokenSeconds` is measured from the login itself, not from the last refresh, so an assistant that keeps working cannot keep extending its own session. Refresh tokens issued before you enabled the option carry no login timestamp, so their window is measured from their last refresh instead — one longer session each, then bounded.
+
+<Warning>
+  Both values are upper bounds: they can only **shorten** what Forest granted, never extend it. For `accessTokenSeconds`, a value above Forest's own token lifetime has no effect. `refreshTokenSeconds` bounds the whole session, which Forest otherwise re-extends on every refresh, so any value shortens it however large it is.
+</Warning>
+
+<Warning>
+  `accessTokenSeconds` bounds what a leaked token can do through the MCP server — its scopes stop applying and its calls stop being audited. It does **not** shorten the Forest token carried inside that JWT, which is signed rather than encrypted: treat a leak as a Forest token leak and revoke at the source.
+</Warning>
+
+<Info>
+  The minimum for either value is 60 seconds; a lower value is raised to it. An invalid value (zero, negative or fractional) stops the server at startup rather than silently leaving your tokens uncapped.
+</Info>
+
 ## Connect your AI assistant
 
 Your MCP endpoint is available at `/mcp` (`<your-agent-url>/mcp` when mounted, `<your-standalone-server-url>/mcp` when standalone). On first connection, a browser window opens for you to log in with your Forest credentials; the assistant then operates with that user's permissions.
@@ -248,6 +294,7 @@ The Forest MCP server:
 - Uses your environment's authentication
 - Logs all operations for audit purposes
 - Never exposes sensitive data without proper access
+- Lets you shorten the OAuth token lifetimes (see [Token lifetimes](#token-lifetimes))
 
 <Warning>
   Only provide MCP server access to trusted AI tools and users. The server can perform any operation that the authenticated user can perform.