Skip to content

docs(mcp): point a deployed standalone server at FOREST_MCP_SERVER_URL #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Scra3 merged 4 commits into from
Aug 18, 2026
Merged

docs(mcp): point a deployed standalone server at FOREST_MCP_SERVER_URL #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
90fccff
docs(mcp): point a deployed standalone server at FOREST_MCP_SERVER_URL
Aug 18, 2026
91dd7a8
docs(reference): fileUploads and requestActionFileUpload in the mount…
Aug 18, 2026
c4af033
docs(mcp): show FOREST_MCP_SERVER_URL in the standalone launch command
Aug 18, 2026
a20b1f9
docs(reference): fileUploads in the mountAiMcpServer signature, and t…
Aug 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions product/embed/mcp-server.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,10 @@ You will then need to provide your FOREST\_ENV\_SECRET and FOREST\_AUTH\_SECRET

```text
FOREST_ENV_SECRET=xxx FOREST_AUTH_SECRET=xxx npx forest-mcp-server

# deployed
FOREST_MCP_SERVER_URL=https://mcp.example.com \
FOREST_ENV_SECRET=xxx FOREST_AUTH_SECRET=xxx npx forest-mcp-server
```

<Note>
Expand All @@ -53,6 +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:<port>` | 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`. |
Expand Down Expand Up @@ -298,12 +303,9 @@ FOREST_MCP_UPLOAD_STORAGE_MODULE=./my-storage.js npx forest-mcp-server
</CodeGroup>

<Warning>
**A deployed standalone server cannot serve remote clients today.** Everything it advertises
derives from `http://localhost:<port>`, 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.** Set `FOREST_MCP_SERVER_URL`, or it
advertises `http://localhost:<port>` to clients and none of them can connect. Mounted deployments
are unaffected: their URLs derive from the back-end URL registered in Forest.
</Warning>

### Client prerequisites
Expand Down
4 changes: 3 additions & 1 deletion reference/agent-api/nodejs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -224,6 +224,7 @@ agent.mountAiMcpServer(options?: {
accessTokenSeconds?: number;
refreshTokenSeconds?: number;
};
fileUploads?: false | FileUploadsOptions;
}): Agent;
```

Expand All @@ -235,8 +236,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. |
Comment thread
macroscopeapp[bot] marked this conversation as resolved.

**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:**

Expand Down