What is the Model Context Protocol (MCP)?

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external data and tools through natural language.

What can the Forest MCP do?

The Forest MCP server lets AI tools like Claude, Dust, and others to:

Access collection schemas
Securely query and browse your data
Execute actions on records

All of this while respecting the Roles & Permissions of your Forest project, and logging every activity, just like if they were performed through the UI. The Forest MCP Server also enables other third party apps to embed and access Forest data and actions, for example in Zendesk, or n8n.

Enabling the Forest MCP Server

There are 2 ways to configure the Forest MCP Server:

Standalone: the Forest MCP Server runs as an standalone service, pointing to your existing node.js or ruby back-end
Mounted: the Forest MCP Server runs as part of your node.js back-end

Standalone Forest MCP Server

To run your Forest MCP Server as a standalone service, you will first need to download the mcp-server package:

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:

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

Follow this guide to retrieve your AUTH and ENV secrets for the relevant environment.

Standalone configuration

The standalone Forest MCP Server is configured entirely through environment variables:

Variable	Required	Default	Description
`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).
`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). Minimum `60`.
`FOREST_MCP_REFRESH_TOKEN_TTL_SECONDS`	No	unbounded	Shortens the time between two interactive logins (see Token lifetimes). Minimum `60`.
`FOREST_MCP_ALLOWED_OAUTH_CLIENTS`	No	any registered client	Comma-separated domains of the OAuth clients allowed to connect (see Restrict which AI clients can connect).
`FOREST_MCP_FILE_UPLOADS`	No	on	`false` turns action file uploads off (see Action file uploads).
`FOREST_MCP_UPLOAD_STORAGE_MODULE`	No	in-memory store	Path to a module exporting the `fileUploads` options, for a real storage backend (see Action file uploads).

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.

Your Forest MCP Server will be accessible at this URL: {your-standalone-server-url}/mcp

Standalone: the AI agent hits the MCP server running as a separate service, which talks to your Forest back-end and your data

Mounted Forest MCP Server

This is only available with the node.js back-end. For other back-ends, refer to the Standalone method further down.

Mounted: the AI agent hits the /mcp endpoint mounted directly inside your Forest back-end, which talks to your data

In your node.js’s index.js file, simply call the mountAiMcpServer() method when creating the back-end, for example:

const agent = createAgent(options).addDataSource(/* ... */).mountAiMcpServer();

Upon restarting your back-end, the Forest MCP Server will automatically start, as confirmed by the following console log:

info: [MCP] Server initialized successfully

Your Forest MCP Server URL will be {your-agent-url}/mcp

Your back-end URL can be found in the Forest UI’s Project Settings, under the Environments tab.Note that each Environment has its own Back-end URL, and therefore its own Forest MCP Server URL.

When mounted, the MCP server intercepts the entire /oauth/* and /.well-known/* namespaces plus /mcp at your back-end’s root. Any request in those namespaces is captured by the MCP server — if it doesn’t serve that exact route (or your back-end already does), the request gets a 404/405 instead of reaching your back-end. So your own /oauth/callback or /.well-known/apple-app-site-association would break, not just OAuth.Pass a basePath to narrow the MCP server to a dedicated prefix so your routes are left untouched. The OAuth and protocol routes move under the prefix; the .well-known discovery documents stay at the root (as OAuth discovery requires) but are served at prefix-suffixed paths such as /.well-known/oauth-authorization-server/ai, narrowing the .well-known claim to just those two paths:

const agent = createAgent(options).addDataSource(/* ... */).mountAiMcpServer({ basePath: '/ai' });

Your Forest MCP Server URL then becomes {your-agent-url}/ai/mcp. Because OAuth discovery must stay at the origin root, basePath requires your agent to be served at the domain root (it throws at startup if the agent URL already includes a path), and root /.well-known/* requests must still reach the agent.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.

Available tools

The Forest MCP server exposes the following capabilities:

Read

Tool	Description
`describeCollection`	Get schema of a collection (fields, types, relations)
`list`	Search and list records with filters and pagination
`listRelated`	List related records

Write

Tool	Description
`create`	Create a new record
`update`	Update an existing record
`delete`	Delete one or more records
`associate`	Link records through a relation
`dissociate`	Unlink records from a relation

Actions

Tool	Description
`getActionForm`	Get form fields for a smart action
`executeAction`	Execute a smart action
`requestActionFileUpload`	Get an upload destination for an action’s `File` or `FileList` field

Restrict tools

You can restrict which tools the MCP server exposes using enabledTools. Only the tools you list will be available, and new tools added in future releases will NOT be automatically enabled, so your configuration stays safe over time.

agent.mountAiMcpServer({
  enabledTools: ['describeCollection', 'list', 'listRelated'],
});

FOREST_MCP_ENABLED_TOOLS="describeCollection,list,listRelated" \
  FOREST_ENV_SECRET=xxx FOREST_AUTH_SECRET=xxx npx forest-mcp-server

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.

Restrict which AI clients can connect

By default, any OAuth client application can register against the MCP server through Dynamic Client Registration and, once one of your users signs in, obtain tokens. Use allowedOAuthClients (@forestadmin/agent ≥ 1.92.0, @forestadmin/mcp-server ≥ 1.21.0) to accept only approved client applications:

agent.mountAiMcpServer({
  allowedOAuthClients: ['dust.tt'],
});

FOREST_MCP_ALLOWED_OAUTH_CLIENTS="dust.tt" \
  FOREST_ENV_SECRET=xxx FOREST_AUTH_SECRET=xxx npx forest-mcp-server

A client is allowed only when every redirect URI it registered is an http(s) URI on a listed domain or one of its subdomains (dust.tt matches eu.dust.tt). Matching uses redirect URIs because they are the one piece of registration metadata an impostor cannot benefit from — the authorization code is only ever delivered there. Self-declared fields such as the client name are ignored, and custom (non-http(s)) scheme URIs are rejected even on an allowed domain, because they deliver the callback to whatever local application registered the scheme. Every other client is rejected with a standard OAuth invalid_client error telling the user to contact their administrator; the response does not reveal the allowed domains. Registration itself still succeeds — it happens on the Forest server — the client just cannot use it against your MCP server. Access tokens issued before you enabled the option stay valid until they expire (1 hour at most); refreshes are blocked immediately.

Native desktop clients (Claude Desktop, MCP Inspector, …) register localhost redirect URIs, so they are always rejected when the allowlist is set. There is deliberately no loopback exemption: allowing localhost would allow every local application. Omit the option in environments that need native clients (e.g. development).

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.

agent.mountAiMcpServer({
  tokenTtl: {
    accessTokenSeconds: 900,
    refreshTokenSeconds: 86400,
  },
});

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

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.

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.

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.

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.

Action file uploads

Actions with File fields work over MCP out of the box. The file never travels through the AI’s context window: the model asks for an upload destination, sends the bytes there directly, and passes a signed reference — a handle — as the field value.

requestActionFileUpload {filename, mimeType, sha256}  →  uploadUrl + method + headers + fileHandle
send the bytes to uploadUrl, with that method and every returned header
executeAction {Document: fileHandle}                   →  the action receives the real file

Step 2 happens outside the MCP protocol, and the returned method and headers are not decoration: a pinned sha256 is signed into a checksum header on S3, and the upload is rejected without it. Apply them as returned rather than assuming PUT with no headers. fileHandle is a string of the form $uploadedFile:<signed token> — pass it through unchanged, the prefix is already there. Nothing to provision: by default the back-end holds uploaded files in memory and serves its own upload endpoint at <your-agent-url>/mcp/uploads, or <your-agent-url>/<basePath>/mcp/uploads if you passed basePath to mountAiMcpServer — that host is the one to get allowed in the next section. Objects are lost on restart, and it is correct for a single back-end instance only: with several replicas or on a serverless runtime, the upload and the action can land on different instances. Plug a storage backend (S3 presigned URLs, GCS, Azure SAS) for those deployments, or turn the feature off:

agent.mountAiMcpServer({
  // any object implementing createUploadUrl / download / getSize —
  // see the @forestadmin/mcp-server README for the contract and an S3 example
  fileUploads: { storage: myUploadStorage },
});

agent.mountAiMcpServer({ fileUploads: false });

# only 'true' or 'false' — any other value fails at startup
FOREST_MCP_FILE_UPLOADS=false npx forest-mcp-server

# or point it at a storage module. FOREST_MCP_FILE_UPLOADS=false wins over it,
# so do not set both unless you mean to turn uploads off.
FOREST_MCP_UPLOAD_STORAGE_MODULE=./my-storage.js npx forest-mcp-server

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.

Client prerequisites

The upload itself is an ordinary HTTPS request made by the AI client, outside the MCP protocol. Whether the client can make it depends on where it runs:

Client	Works when
Claude Code	The upload host is reachable from the machine running Claude Code — so a `localhost` back-end works, as long as it runs on that same machine
Claude Desktop, Claude.ai, Cowork	The upload host is publicly reachable (never `localhost`) and its domain is allowed for outbound traffic in the client’s code-execution sandbox

On a managed (Team/Enterprise) Claude workspace, two settings belong to the workspace admin, not the end user: the right to add a custom connector at all, and the sandbox’s outbound domain allowlist. Ask for both in the same request — one per Forest back-end (or storage) domain.

Integrity

The upload URL is pre-authorized and expires after 15 minutes by default (fileUploads.uploadUrlTtlSeconds); against the built-in in-memory store it accepts a single upload.
The handle is a signed token bound to the user who requested it, expiring after 45 minutes by default (fileUploads.handleTtlSeconds).
The AI is instructed to pin the file’s sha256: the digest is re-verified when the action runs, so content substituted after the upload is rejected.
Files are capped at 20 MiB each by default (fileUploads.maxBytes).
The in-memory store holds 64 MiB across all pending uploads (fileUploads.ephemeralMaxTotalBytes). Redeeming a file does not free it — it lives until the handle expires — so on the defaults that is about three max-size files per 45-minute window, not a rolling 64 MiB. Past that an upload is refused with a 413 when it is what exceeds the total, or a 507 when the store was already full — in both cases the response body names the store. A 413 alone does not distinguish this from a file over maxBytes, so branch on the body, not the status.

The four fileUploads.* settings above are code-only — they are passed to mountAiMcpServer, and there is no environment variable for any of them. On a standalone server they are set in the module FOREST_MCP_UPLOAD_STORAGE_MODULE points at, which carries the whole fileUploads object and not just the storage.

The filename is whatever the AI client reports, and sandboxes have been observed normalizing it (a dropped hyphen) while the bytes stay exact. In your action code, treat file.name as a label, not an identifier.

This capability is experimental: the MCP specification is designing its own file transfer story (SEP-2631). The UploadStorage contract is expected to survive — safe to write an adapter against — but the requestActionFileUpload tool and the handle format may change to follow the specification.

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.

claude mcp add --transport http forest-admin <your-mcp-endpoint>

{
  "mcpServers": {
    "forest-admin": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "<your-mcp-endpoint>"]
    }
  }
}

{
  "mcpServers": {
    "forest-admin": {
      "url": "<your-mcp-endpoint>"
    }
  }
}

{
  "servers": {
    "forest-admin": {
      "type": "http",
      "url": "<your-mcp-endpoint>"
    }
  }
}

[mcp_servers.forest-admin]
url = "<your-mcp-endpoint>"

Use the MCP transport type "http" (not "sse" or "url"): the Forest MCP server uses Streamable HTTP. Your URL should still use https://. Clients that rely on mcp-remote (Claude Desktop, Windsurf, JetBrains) require Node.js 18+ (some versions need 20+).

Use cases

AI-assisted operations

Use Claude or other AI assistants to:

Answer questions about your data
Generate reports and insights
Automate routine tasks
Perform data analysis

Example prompts

“Show me all pending orders from the last 24 hours”

“What customers have the highest lifetime value?”

“Execute the ‘Send Invoice’ action on order #12345”

Security

The Forest MCP server:

Respects all Forest permissions and roles
Uses your environment’s authentication
Logs all operations for audit purposes
Never exposes sensitive data without proper access
Lets you restrict which AI client applications can connect (see Restrict which AI clients can connect)
Lets you shorten the OAuth token lifetimes (see Token lifetimes)

Only provide MCP server access to trusted AI tools and users. The server can perform any operation that the authenticated user can perform.

Overview

Connect

Process

Build

Execute

Collaborate

Manage

Embed

Control

Project Settings

Forest MCP Server

What is the Model Context Protocol (MCP)?

What can the Forest MCP do?

Enabling the Forest MCP Server

Standalone Forest MCP Server

Standalone configuration

Mounted Forest MCP Server

Available tools

Read

Write

Actions

Restrict tools

Restrict which AI clients can connect

Token lifetimes

Action file uploads

Client prerequisites

Integrity

Connect your AI assistant

Use cases

AI-assisted operations

Example prompts

Security

​What is the Model Context Protocol (MCP)?

​What can the Forest MCP do?

​Enabling the Forest MCP Server

​Standalone Forest MCP Server

​Standalone configuration

​Mounted Forest MCP Server

​Available tools

​Read

​Write

​Actions

​Restrict tools

​Restrict which AI clients can connect

​Token lifetimes

​Action file uploads

​Client prerequisites

​Integrity

​Connect your AI assistant

​Use cases

​AI-assisted operations

​Example prompts

​Security

What is the Model Context Protocol (MCP)?

What can the Forest MCP do?

Enabling the Forest MCP Server

Standalone Forest MCP Server

Standalone configuration

Mounted Forest MCP Server

Available tools

Read

Write

Actions

Restrict tools

Restrict which AI clients can connect

Token lifetimes

Action file uploads

Client prerequisites

Integrity

Connect your AI assistant

Use cases

AI-assisted operations

Example prompts

Security