From 72bf28c97f2192f3626e4630ca461a51574eb16a Mon Sep 17 00:00:00 2001 From: alban bertolini Date: Tue, 7 Jul 2026 12:53:45 +0200 Subject: [PATCH 1/3] docs(mcp-server): document the agentUrl option MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document mountAiMcpServer({ agentUrl }) — keeps the internal tool->agent callbacks on a private network in self-hosted setups instead of the public api_endpoint, without changing the advertised OAuth URLs. Adds the param, a dedicated reference section, the FOREST_AGENT_URL env var, and a self-hosted note on the product page. Co-Authored-By: Claude Opus 4.8 (1M context) --- product/embed/mcp-server.mdx | 10 ++++++++++ reference/agent-api/nodejs.mdx | 18 +++++++++++++++++- 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/product/embed/mcp-server.mdx b/product/embed/mcp-server.mdx index 960056c..3d29aca 100644 --- a/product/embed/mcp-server.mdx +++ b/product/embed/mcp-server.mdx @@ -98,6 +98,16 @@ Your Forest MCP Server URL will be `{your-agent-url}/mcp` The prefix applies to every route, including the protocol endpoint — so `basePath: '/mcp'` would make the endpoint `/mcp/mcp`. Prefer a distinct prefix such as `/ai` to avoid the repetition. + + When a tool runs, the MCP server calls back into your agent's data layer over HTTP using the environment's **public** back-end URL — so this traffic leaves over the public internet even when the server is mounted in-process. In a self-hosted setup, pass `agentUrl` to keep those callbacks on your internal network: + + ```text + const agent = createAgent(options).addDataSource(/* ... */).mountAiMcpServer({ agentUrl: 'http://forest-agent.internal:3310' }); + ``` + + This only affects the internal tool→agent calls; the OAuth URLs advertised to MCP clients stay public. + + # Available tools The Forest MCP server exposes the following capabilities: diff --git a/reference/agent-api/nodejs.mdx b/reference/agent-api/nodejs.mdx index 140cf6d..52cc38e 100644 --- a/reference/agent-api/nodejs.mdx +++ b/reference/agent-api/nodejs.mdx @@ -251,6 +251,7 @@ Enable a Model Context Protocol (MCP) server on the agent, allowing AI assistant agent.mountAiMcpServer(options?: { enabledTools?: ToolName[]; basePath?: string; + agentUrl?: string; }): Agent; ``` @@ -260,6 +261,7 @@ agent.mountAiMcpServer(options?: { |--------|------|-------------| | `enabledTools` | `ToolName[]` | Restrict which MCP tools are exposed. Defaults to all tools. | | `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. | +| `agentUrl` | `string` | Internal URL the MCP tools use to call back into the agent's data layer (e.g. `'http://forest-agent.internal:3310'`). Defaults to the environment's public `api_endpoint`. Does not change the advertised OAuth URLs. | **Available tool names:** `'describeCollection'`, `'list'`, `'listRelated'`, `'create'`, `'update'`, `'delete'`, `'associate'`, `'dissociate'`, `'getActionForm'`, `'executeAction'` @@ -311,7 +313,21 @@ The prefix applies to **all** routes, including the protocol endpoint — so `ba Because the `.well-known` discovery documents must stay at the origin root, `basePath` requires the agent to be served at the **domain root**. If your agent's URL already includes a path (e.g. `https://host/api`), setting `basePath` throws at startup. And root `/.well-known/*` requests must still reach the agent — a reverse proxy that forwards only `//*` will break discovery. -You can also configure enabled tools via the `FOREST_MCP_ENABLED_TOOLS` environment variable (comma-separated tool names), or set the server port with `MCP_SERVER_PORT` (default: `3931`). +**Keeping tool traffic on your internal network:** + +When a tool runs (`list`, `create`, `executeAction`…), the MCP server calls back into the agent's data layer over HTTP. By default it uses the environment's **public `api_endpoint`** (the URL Forest has on file), so this traffic leaves over the public internet — even when the MCP server is mounted inside the agent. In a self-hosted setup you can keep it on your private network with `agentUrl`: + +```typescript +agent.mountAiMcpServer({ agentUrl: 'http://forest-agent.internal:3310' }); +``` + +`agentUrl` only redirects the internal tool→agent calls. The advertised OAuth URLs (issuer, `.well-known` metadata, authorize/token endpoints) stay public, so external MCP clients still authenticate normally. An invalid value (non-`http(s)`, or one carrying a query string or fragment) throws at startup. + + +`agentUrl` and `basePath` are independent: `basePath` changes where the MCP server's *inbound* routes are mounted, while `agentUrl` changes where the tools send their *outbound* callbacks to the agent. + + +You can also configure enabled tools via the `FOREST_MCP_ENABLED_TOOLS` environment variable (comma-separated tool names), set the server port with `MCP_SERVER_PORT` (default: `3931`), or set the internal agent URL with `FOREST_AGENT_URL` (standalone MCP server). --- From 4b141846d7174da98c502f43ac735ced13e0fd3c Mon Sep 17 00:00:00 2001 From: alban bertolini Date: Tue, 7 Jul 2026 12:59:12 +0200 Subject: [PATCH 2/3] docs(mcp-server): clarify agentUrl must include the agent mount prefix Co-Authored-By: Claude Opus 4.8 (1M context) --- reference/agent-api/nodejs.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/reference/agent-api/nodejs.mdx b/reference/agent-api/nodejs.mdx index 52cc38e..0842f0b 100644 --- a/reference/agent-api/nodejs.mdx +++ b/reference/agent-api/nodejs.mdx @@ -321,6 +321,8 @@ When a tool runs (`list`, `create`, `executeAction`…), the MCP server calls ba agent.mountAiMcpServer({ agentUrl: 'http://forest-agent.internal:3310' }); ``` +Point it at the agent's own base URL, **including any mount prefix** (the tools reach the agent's `/forest/*` routes under it) — e.g. `http://forest-agent.internal:3310/backend` if the agent is mounted at `/backend`. + `agentUrl` only redirects the internal tool→agent calls. The advertised OAuth URLs (issuer, `.well-known` metadata, authorize/token endpoints) stay public, so external MCP clients still authenticate normally. An invalid value (non-`http(s)`, or one carrying a query string or fragment) throws at startup. From de6b943cff2fad959dae13c7f618bd909a564ef8 Mon Sep 17 00:00:00 2001 From: alban bertolini Date: Tue, 7 Jul 2026 18:53:00 +0200 Subject: [PATCH 3/3] docs(mcp-server): scope agentUrl to the standalone server agentUrl is no longer a mountAiMcpServer option (mounted mode dispatches tool calls in-process). Document it only as the standalone server's FOREST_AGENT_URL env var. Co-Authored-By: Claude Opus 4.8 (1M context) --- product/embed/mcp-server.mdx | 14 ++++---------- reference/agent-api/nodejs.mdx | 20 +------------------- 2 files changed, 5 insertions(+), 29 deletions(-) diff --git a/product/embed/mcp-server.mdx b/product/embed/mcp-server.mdx index 3d29aca..8c90129 100644 --- a/product/embed/mcp-server.mdx +++ b/product/embed/mcp-server.mdx @@ -44,6 +44,10 @@ FOREST_ENV_SECRET=xxx FOREST_AUTH_SECRET=xxx npx forest-mcp-server Follow [this guide](/get-started/connect/environment-variables) to retrieve your AUTH and ENV secrets for the relevant environment. + + By default the standalone server reaches your back-end at the environment's public URL. In a self-hosted setup, set `FOREST_AGENT_URL` to an internal address (e.g. `http://forest-agent.internal:3310`) to keep that traffic on your private network. It only affects how the server reaches your back-end; the OAuth URLs advertised to MCP clients are unchanged. + + Your Forest MCP Server will be accessible at this URL: `{your-standalone-server-url}/mcp` - - When a tool runs, the MCP server calls back into your agent's data layer over HTTP using the environment's **public** back-end URL — so this traffic leaves over the public internet even when the server is mounted in-process. In a self-hosted setup, pass `agentUrl` to keep those callbacks on your internal network: - - ```text - const agent = createAgent(options).addDataSource(/* ... */).mountAiMcpServer({ agentUrl: 'http://forest-agent.internal:3310' }); - ``` - - This only affects the internal tool→agent calls; the OAuth URLs advertised to MCP clients stay public. - - # Available tools The Forest MCP server exposes the following capabilities: diff --git a/reference/agent-api/nodejs.mdx b/reference/agent-api/nodejs.mdx index 0842f0b..140cf6d 100644 --- a/reference/agent-api/nodejs.mdx +++ b/reference/agent-api/nodejs.mdx @@ -251,7 +251,6 @@ Enable a Model Context Protocol (MCP) server on the agent, allowing AI assistant agent.mountAiMcpServer(options?: { enabledTools?: ToolName[]; basePath?: string; - agentUrl?: string; }): Agent; ``` @@ -261,7 +260,6 @@ agent.mountAiMcpServer(options?: { |--------|------|-------------| | `enabledTools` | `ToolName[]` | Restrict which MCP tools are exposed. Defaults to all tools. | | `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. | -| `agentUrl` | `string` | Internal URL the MCP tools use to call back into the agent's data layer (e.g. `'http://forest-agent.internal:3310'`). Defaults to the environment's public `api_endpoint`. Does not change the advertised OAuth URLs. | **Available tool names:** `'describeCollection'`, `'list'`, `'listRelated'`, `'create'`, `'update'`, `'delete'`, `'associate'`, `'dissociate'`, `'getActionForm'`, `'executeAction'` @@ -313,23 +311,7 @@ The prefix applies to **all** routes, including the protocol endpoint — so `ba Because the `.well-known` discovery documents must stay at the origin root, `basePath` requires the agent to be served at the **domain root**. If your agent's URL already includes a path (e.g. `https://host/api`), setting `basePath` throws at startup. And root `/.well-known/*` requests must still reach the agent — a reverse proxy that forwards only `//*` will break discovery. -**Keeping tool traffic on your internal network:** - -When a tool runs (`list`, `create`, `executeAction`…), the MCP server calls back into the agent's data layer over HTTP. By default it uses the environment's **public `api_endpoint`** (the URL Forest has on file), so this traffic leaves over the public internet — even when the MCP server is mounted inside the agent. In a self-hosted setup you can keep it on your private network with `agentUrl`: - -```typescript -agent.mountAiMcpServer({ agentUrl: 'http://forest-agent.internal:3310' }); -``` - -Point it at the agent's own base URL, **including any mount prefix** (the tools reach the agent's `/forest/*` routes under it) — e.g. `http://forest-agent.internal:3310/backend` if the agent is mounted at `/backend`. - -`agentUrl` only redirects the internal tool→agent calls. The advertised OAuth URLs (issuer, `.well-known` metadata, authorize/token endpoints) stay public, so external MCP clients still authenticate normally. An invalid value (non-`http(s)`, or one carrying a query string or fragment) throws at startup. - - -`agentUrl` and `basePath` are independent: `basePath` changes where the MCP server's *inbound* routes are mounted, while `agentUrl` changes where the tools send their *outbound* callbacks to the agent. - - -You can also configure enabled tools via the `FOREST_MCP_ENABLED_TOOLS` environment variable (comma-separated tool names), set the server port with `MCP_SERVER_PORT` (default: `3931`), or set the internal agent URL with `FOREST_AGENT_URL` (standalone MCP server). +You can also configure enabled tools via the `FOREST_MCP_ENABLED_TOOLS` environment variable (comma-separated tool names), or set the server port with `MCP_SERVER_PORT` (default: `3931`). ---