From 90fccff9e12df65412355631793bc6d6d1ca9dc1 Mon Sep 17 00:00:00 2001 From: alban bertolini Date: Tue, 18 Aug 2026 10:43:22 +0200 Subject: [PATCH 1/4] docs(mcp): point a deployed standalone server at FOREST_MCP_SERVER_URL --- product/embed/mcp-server.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/product/embed/mcp-server.mdx b/product/embed/mcp-server.mdx index aac6761..4021403 100644 --- a/product/embed/mcp-server.mdx +++ b/product/embed/mcp-server.mdx @@ -53,6 +53,7 @@ The standalone Forest MCP Server is configured entirely through environment vari | `FOREST_ENV_SECRET` | Yes | — | Your environment secret, used to authenticate and reach the right back-end. | | `FOREST_AUTH_SECRET` | Yes | — | Your authentication secret. Must match the one of the corresponding back-end. | | `MCP_SERVER_PORT` | No | `3931` | Port the standalone server listens on. | +| `FOREST_MCP_SERVER_URL` | Yes, when deployed | `http://localhost:` | Public URL the server is reachable at, an http(s) origin with no path, query or credentials. Everything advertised to clients derives from it. An invalid value fails at startup. | | `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`. | @@ -298,12 +299,11 @@ FOREST_MCP_UPLOAD_STORAGE_MODULE=./my-storage.js npx forest-mcp-server - **A deployed standalone server cannot serve remote clients today.** Everything it advertises - derives from `http://localhost:`, which is all the standalone server knows about itself: - the OAuth endpoints a client discovers, and the upload URLs of the in-memory store. Configuring a - storage backend fixes the upload URLs — they then come from the backend — but not OAuth - discovery, so remote clients still cannot connect. Mounted deployments are unaffected: their URLs - derive from the back-end URL registered in Forest. + **A deployed standalone server must be told its public URL.** Everything it advertises to clients + derives from it — the OAuth endpoints they discover, and the upload URLs of the in-memory store — + and a process cannot work out its own public URL. Set `FOREST_MCP_SERVER_URL` to it; without it + the server advertises `http://localhost:` and no remote client can connect. Mounted + deployments are unaffected: their URLs derive from the back-end URL registered in Forest. ### Client prerequisites From 91dd7a81a3644c349dee6ffcd685f0af53bedbd1 Mon Sep 17 00:00:00 2001 From: alban bertolini Date: Tue, 18 Aug 2026 10:45:08 +0200 Subject: [PATCH 2/4] docs(reference): fileUploads and requestActionFileUpload in the mountAiMcpServer options --- reference/agent-api/nodejs.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/reference/agent-api/nodejs.mdx b/reference/agent-api/nodejs.mdx index d419174..49137a7 100644 --- a/reference/agent-api/nodejs.mdx +++ b/reference/agent-api/nodejs.mdx @@ -235,8 +235,9 @@ agent.mountAiMcpServer(options?: { | `basePath` | `string` | Path prefix for the MCP OAuth and protocol routes (e.g. `'/ai'`); the `.well-known` discovery documents stay at the origin root (prefix-suffixed). Requires the agent at the domain root. Defaults to the host root. | | `allowedOAuthClients` | `string[]` | Accept only OAuth clients whose registered redirect URIs are all `http(s)` URIs on the listed domains or their subdomains; every other client gets a standard `invalid_client` rejection. Must be non-empty when set (an empty array throws at startup). Defaults to accepting any registered client. See [Restrict which AI clients can connect](/product/embed/mcp-server#restrict-which-ai-clients-can-connect). Since `@forestadmin/agent` 1.92.0. | | `tokenTtl` | `{ accessTokenSeconds?: number; refreshTokenSeconds?: number }` | Shorten the OAuth token lifetimes issued by the MCP server (defaults: 1 hour for access tokens, unbounded session for refresh). Upper bounds only — they can never extend what Forest grants; minimum `60` seconds each. See [Token lifetimes](/product/embed/mcp-server#token-lifetimes). Since `@forestadmin/agent` 1.91.0. | +| `fileUploads` | `false \| { storage?, maxBytes?, ... }` | Configure action file uploads, which are **on by default** with the files held in memory — pass `false` to turn the feature off, or an object to set a `storage` backend, size limits and TTLs. Experimental. See [Action file uploads](/product/embed/mcp-server#action-file-uploads). Since `@forestadmin/agent` 1.95.0. | -**Available tool names:** `'describeCollection'`, `'list'`, `'listRelated'`, `'create'`, `'update'`, `'delete'`, `'associate'`, `'dissociate'`, `'getActionForm'`, `'executeAction'` +**Available tool names:** `'describeCollection'`, `'list'`, `'listRelated'`, `'create'`, `'update'`, `'delete'`, `'associate'`, `'dissociate'`, `'getActionForm'`, `'executeAction'`, `'requestActionFileUpload'` **Example:** From c4af033662b41295f9ea3e8e37446f553108c54d Mon Sep 17 00:00:00 2001 From: alban bertolini Date: Tue, 18 Aug 2026 10:45:44 +0200 Subject: [PATCH 3/4] docs(mcp): show FOREST_MCP_SERVER_URL in the standalone launch command --- product/embed/mcp-server.mdx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/product/embed/mcp-server.mdx b/product/embed/mcp-server.mdx index 4021403..5ad4dc8 100644 --- a/product/embed/mcp-server.mdx +++ b/product/embed/mcp-server.mdx @@ -37,7 +37,12 @@ npm install @forestadmin/mcp-server You will then need to provide your FOREST\_ENV\_SECRET and FOREST\_AUTH\_SECRET variables to start the Forest MCP Server, to ensure it can authenticate and access the right back-end, corresponding to your project and environment of choice: ```text +# on your machine FOREST_ENV_SECRET=xxx FOREST_AUTH_SECRET=xxx npx forest-mcp-server + +# deployed: FOREST_MCP_SERVER_URL is what clients are told to use, and is required +FOREST_MCP_SERVER_URL=https://mcp.example.com \ + FOREST_ENV_SECRET=xxx FOREST_AUTH_SECRET=xxx npx forest-mcp-server ``` From a20b1f9dd4cd30cc9a24b737b8ce91bbcb9e1e92 Mon Sep 17 00:00:00 2001 From: alban bertolini Date: Tue, 18 Aug 2026 10:49:39 +0200 Subject: [PATCH 4/4] docs(reference): fileUploads in the mountAiMcpServer signature, and trim the standalone prose --- product/embed/mcp-server.mdx | 13 +++++-------- reference/agent-api/nodejs.mdx | 1 + 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/product/embed/mcp-server.mdx b/product/embed/mcp-server.mdx index 5ad4dc8..de9cc95 100644 --- a/product/embed/mcp-server.mdx +++ b/product/embed/mcp-server.mdx @@ -37,10 +37,9 @@ npm install @forestadmin/mcp-server You will then need to provide your FOREST\_ENV\_SECRET and FOREST\_AUTH\_SECRET variables to start the Forest MCP Server, to ensure it can authenticate and access the right back-end, corresponding to your project and environment of choice: ```text -# on your machine FOREST_ENV_SECRET=xxx FOREST_AUTH_SECRET=xxx npx forest-mcp-server -# deployed: FOREST_MCP_SERVER_URL is what clients are told to use, and is required +# deployed FOREST_MCP_SERVER_URL=https://mcp.example.com \ FOREST_ENV_SECRET=xxx FOREST_AUTH_SECRET=xxx npx forest-mcp-server ``` @@ -58,7 +57,7 @@ The standalone Forest MCP Server is configured entirely through environment vari | `FOREST_ENV_SECRET` | Yes | — | Your environment secret, used to authenticate and reach the right back-end. | | `FOREST_AUTH_SECRET` | Yes | — | Your authentication secret. Must match the one of the corresponding back-end. | | `MCP_SERVER_PORT` | No | `3931` | Port the standalone server listens on. | -| `FOREST_MCP_SERVER_URL` | Yes, when deployed | `http://localhost:` | Public URL the server is reachable at, an http(s) origin with no path, query or credentials. Everything advertised to clients derives from it. An invalid value fails at startup. | +| `FOREST_MCP_SERVER_URL` | Yes, when deployed | `http://localhost:` | Public URL the server is reachable at — an http(s) origin, no path. An invalid value fails at startup. | | `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`. | @@ -304,11 +303,9 @@ FOREST_MCP_UPLOAD_STORAGE_MODULE=./my-storage.js npx forest-mcp-server - **A deployed standalone server must be told its public URL.** Everything it advertises to clients - derives from it — the OAuth endpoints they discover, and the upload URLs of the in-memory store — - and a process cannot work out its own public URL. Set `FOREST_MCP_SERVER_URL` to it; without it - the server advertises `http://localhost:` and no remote client can connect. Mounted - deployments are unaffected: their URLs derive from the back-end URL registered in Forest. + **A deployed standalone server must be told its public URL.** Set `FOREST_MCP_SERVER_URL`, or it + advertises `http://localhost:` to clients and none of them can connect. Mounted deployments + are unaffected: their URLs derive from the back-end URL registered in Forest. ### Client prerequisites diff --git a/reference/agent-api/nodejs.mdx b/reference/agent-api/nodejs.mdx index 49137a7..17c3b7f 100644 --- a/reference/agent-api/nodejs.mdx +++ b/reference/agent-api/nodejs.mdx @@ -224,6 +224,7 @@ agent.mountAiMcpServer(options?: { accessTokenSeconds?: number; refreshTokenSeconds?: number; }; + fileUploads?: false | FileUploadsOptions; }): Agent; ```