docs(mcp-server): document the tokenTtl option - #18
Merged
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![macroscopeapp[bot]](https://avatars.githubusercontent.com/in/900172?s=60&v=4){kind=small}
| Requirements: | ||
|
|
||
| - **`@forestadmin/agent` ≥ 1.84.0**. | ||
| - **The executor package**, installed at the **exact version your agent pins**. It's an *optional peer dependency* the agent loads dynamically at runtime, so `tsc` won't flag it when it's missing — but `agent.start()` throws _"The embedded workflow executor requires the `@forestadmin/workflow-executor` package"_. The pin is exact (a `^` range conflicts), so install that specific version — find it in your lockfile or with `npm info @forestadmin/agent peerDependencies`: |
There was a problem hiding this comment.
🟡 Medium workflows/forest-runtime.mdx:54
The suggested command npm info @forestadmin/agent peerDependencies queries the registry's latest agent version, not the version installed by the reader. When an older supported agent pins a different executor version, this returns the wrong exact version, so the subsequent npm install conflicts with that agent's peer dependency. Include the installed agent version in the command, e.g. npm info @forestadmin/agent@1.84.0 peerDependencies.
🚀 Reply "fix it for me" or copy this AI Prompt for your agent:
In file @product/process/workflows/forest-runtime.mdx around line 54:
The suggested command `npm info @forestadmin/agent peerDependencies` queries the registry's `latest` agent version, not the version installed by the reader. When an older supported agent pins a different executor version, this returns the wrong exact version, so the subsequent `npm install` conflicts with that agent's peer dependency. Include the installed agent version in the command, e.g. `npm info @forestadmin/agent@1.84.0 peerDependencies`.
Member
Author
There was a problem hiding this comment.
Both values are upper bounds — they only shorten what Forest Admin granted — and refreshTokenSeconds is anchored on the login rather than the last refresh, so the page states both explicitly: that is what surprises users. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Only accessTokenSeconds has an inert case. refreshTokenSeconds bounds the whole session, which Forest Admin re-extends on every refresh, so any value shortens it however large — stating otherwise told readers a working control does nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Without the numbers a reader cannot tell whether their value will bind. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Forest Admin re-grants its refresh lifetime on every refresh, so leaving refreshTokenSeconds unset means a working assistant never signs in again. Listing 8 days as the default steered readers away from the whole useful range. Also documents that refresh tokens predating the option anchor on their last refresh, giving one longer session before the bound applies. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The signed JWT carries the Forest token, so a leak stays exploitable against the agent past the cap. Say so rather than implying the cap bounds the leak. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Scra3
force-pushed
the
feat/mcp-token-ttl-doc
branch
from
July 29, 2026 08:50
dba7a89 to
c2f90df
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the new
tokenTtloption shipped in agent-nodejs#1788, requested by Spendesk to force periodic re-authentication and limit the blast radius of a leaked token.Adds a
## Token lifetimessection afterRestrict tools, the two env vars to the standalone table, and one bullet in## Securitylinking to it so it is findable from both angles.Two things get their own callout because they are what surprise users:
<Warning>). A value longer than Forest's own lifetime has no effect — the option cannot extend a token.refreshTokenSecondsis measured from the login, not from the last refresh. That distinction is the whole point: Forest grants a full refresh lifetime on every refresh, so a per-refresh bound would slide forever and never force a re-login.A small table contrasts the two settings by what the end user actually notices:
accessTokenSecondsis invisible (the assistant refreshes silently),refreshTokenSecondssends them back through the browser login.Branched from
main(the local clone was onfeat/wf-executor-doc).Note
Document
tokenTtloptions for configuring OAuth token lifetimes in the MCP serverAdds a new 'Token lifetimes' section and two new environment variable entries to mcp-server.mdx.
FOREST_MCP_ACCESS_TOKEN_TTL_SECONDSandFOREST_MCP_REFRESH_TOKEN_TTL_SECONDSenvironment variables and their equivalenttokenTtloptions onagent.mountAiMcpServerMacroscope summarized c2f90df.