​

What is the Model Context Protocol (MCP)?

​

What can the Forest MCP do?

• Access collection schemas
• Securely query and browse your data
• Execute actions on records
• Start Workflows on a record and follow their progress

​

Enabling 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

npm install @forestadmin/mcp-server

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

​

Standalone configuration

​

Mounted Forest MCP Server

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

info: [MCP] Server initialized successfully

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

​

Available tools

​

Read

​

Write

​

Actions

​

Workflows

​

Restrict tools

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

​

Restrict which AI clients can connect

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

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

​

Token lifetimes

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

​

Action file uploads

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

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

​

Client prerequisites

​

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.

​

Connect your AI assistant

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>"

​

Triggering workflows from an AI assistant

​

Discover → trigger → poll

1. Discover — listWorkflows returns the MCP-enabled workflows in the connected user’s rendering, with the collection each one operates on. Pass collectionName to narrow it to the collection of the record in context.
2. Trigger — triggerWorkflow starts a run on one record and returns its runId. The run continues server-side; nothing blocks.
3. Poll — getWorkflowRun returns the full run: its state plus the complete step-by-step history, each step with its definition and outcome, so the assistant can see exactly where the run is and how it got there.

​

listWorkflows

[
  {
    "workflowId": "9f1b0c4e-2f7a-4d5b-9e31-6c0a8b7d1234",
    "name": "KYC review",
    "collectionName": "customers"
  }
]

​

triggerWorkflow

{ "runId": "1234", "runState": "pending" }

​

getWorkflowRun

{
  "id": 1234,
  "workflowId": "9f1b0c4e-2f7a-4d5b-9e31-6c0a8b7d1234",
  "selectedRecordId": "42",
  "runState": "started",
  "triggerType": "mcp",
  "workflowHistory": [
    {
      "stepName": "Activity_ReviewKyb",
      "stepIndex": 0,
      "done": false,
      "context": {},
      "stepDefinition": {
        "type": "task",
        "taskType": "guideline",
        "title": "Review the KYB documents",
        "prompt": "Check the uploaded documents, then approve or reject",
        "executionType": "manual",
        "outgoing": [{ "stepId": "Event_CustomerApproved", "buttonText": "Approve" }]
      }
    }
  ]
}

{
  "id": 1234,
  "workflowId": "9f1b0c4e-2f7a-4d5b-9e31-6c0a8b7d1234",
  "selectedRecordId": "42",
  "runState": "finished",
  "triggerType": "mcp",
  "workflowHistory": [
    {
      "stepName": "Activity_ReviewKyb",
      "stepIndex": 0,
      "done": true,
      "context": { "manuallyCompleted": true },
      "stepDefinition": {
        "type": "task",
        "taskType": "guideline",
        "title": "Review the KYB documents",
        "prompt": "Check the uploaded documents, then approve or reject",
        "executionType": "manual",
        "outgoing": [{ "stepId": "Event_CustomerApproved", "buttonText": "Approve" }]
      }
    },
    {
      "stepName": "Event_CustomerApproved",
      "stepIndex": 1,
      "done": false,
      "context": {},
      "stepDefinition": {
        "type": "end",
        "title": "Customer approved",
        "executionType": "manual",
        "outgoing": []
      }
    }
  ]
}

​

Runs that need a human

​

Errors

​

Identity, auditing, and limits

• Identity — the run executes as the Forest user of the MCP session, established by the OAuth login. That user’s permissions bound everything the run reads and writes. The trigger itself is gated only by the user’s rendering and the workflow’s MCP toggle: neither the target record nor the workflow’s segments are checked when the run is created.
• Auditing — each trigger is recorded in the run history and in your Activity Logs, attributed to that user and labelled via MCP, so MCP-started runs are distinguishable from manual and webhook ones. An MCP trigger writes two complementary entries, and they are worded differently on purpose:
  • requested the workflow ”…” via MCP — written before the run starts, and the trigger is refused if it cannot be written. It has no run attached, because the run does not exist yet.
  • triggered the workflow ”…” via MCP — written once the run is committed, carrying its run id.
  Only the first is guaranteed: the run-attached entry is best-effort, so a successful trigger can leave just the request entry. Count triggered rows to count runs actually started, and requested rows to count what assistants asked for.
• Four tools are not audited — listWorkflows, getWorkflowRun, getActionForm and requestActionFileUpload leave no Activity Logs entry. Three of them have nothing to attach an entry to, since the Activity Logs route needs a collection: the two workflow reads operate on the orchestrator rather than a collection, and requestActionFileUpload is identified only by a filename and a checksum. getActionForm is the exception — it does receive a collection and record ids, so nothing stands in the way of auditing it; it simply predates this work and was never wired to the audit path. requestActionFileUpload is worth calling out separately: it is not a read — it mints a pre-authorized upload URL — and it is enabled by default, including when no storage backend is configured. Every other tool, read or write, writes an entry. Closing these gaps is on the roadmap.
• When the audit log itself fails — a write whose log cannot be created is blocked, so no side effect happens unaudited. A read proceeds with a warning, so an audit-store outage never takes the read surface down. An authorization refusal (the caller’s identity was rejected) propagates either way — it is not an outage.
• Rate limiting — the workflow tools have no dedicated limiter. They inherit the MCP server’s authentication, and no per-call rate limit applies; unlike the webhook trigger, there is no separately exposed HTTP endpoint to protect — every call happens inside an authenticated MCP session. The one-run-per-workflow-per-record rule prevents duplicate runs on the same record, but nothing bounds how many records an assistant can trigger on — walking a list view opens one run per record, each consuming Forest Runtime capacity. triggerWorkflow is annotated destructiveHint: true, but MCP annotations are advisory: whether a call is confirmed, auto-approved, or allowlisted for the rest of the session is entirely up to the client. Check and configure that behaviour in the MCP client you connect, and treat the per-workflow mcp toggle as the only guard Forest itself enforces.
• Turning it off — disable a single workflow’s MCP toggle, or set an enabledTools allowlist that leaves triggerWorkflow out to remove MCP triggering across all workflows (when enabledTools is unset, every tool is enabled — restricting means listing the tools you keep). Either way, manual and webhook starts of that workflow keep working. Revoking the connected user’s access stops new triggers immediately, and the assistant is told not to retry; a run already in flight is not aborted, and keeps going until it next touches data. By default the agent refreshes its permissions from Forest’s event stream, so a revocation lands within seconds; an agent started with instantCacheRefresh: false instead waits out its permission cache — 15 minutes by default, or whatever permissionsCacheDurationInSeconds is set to. Neither delay is a guarantee: abort a run explicitly if you need it stopped now. See Revoking MCP access.

​

Use cases

​

AI-assisted operations

• 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”

“Start the KYC review workflow on customer #482 and tell me where it gets to”

​

Security

• Respects all Forest permissions and roles
• Uses your environment’s authentication
• Logs every operation except four tools — getActionForm, requestActionFileUpload, listWorkflows and getWorkflowRun — for audit purposes (see Identity, auditing, and limits)
• Bounds what a run reads and writes by the connected user’s permissions. Note this does not bound the trigger: neither the target record nor the workflow’s segments are checked when a run is created
• Carries no record payload out of your infrastructure — records stay in Forest Runtime. Identifiers (selectedRecordId) and step error messages (context.error) can still contain customer data, so treat a run’s history as sensitive
• 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)
• Exposes no workflow until someone who can manage workflows opts that workflow in (see Triggering workflows)