@forestadmin/mcp-server

Model Context Protocol (MCP) server for Forest Admin with OAuth authentication support.

Overview

This MCP server provides HTTP REST API access to Forest Admin operations, enabling AI assistants and other MCP clients to interact with your Forest Admin data through a standardized protocol.

Available Tools

Usage

With Forest Admin Agent

The MCP server is included with the Forest Admin agent. Simply call mountAiMcpServer():

import { createAgent } from '@forestadmin/agent';

const agent = createAgent(options)
  .addDataSource(myDataSource)
  .mountAiMcpServer();

agent.mountOnExpress(app);
agent.start();
Copy

The MCP server will be automatically initialized and mounted on your application.

Standalone Server

You can run the MCP server standalone using the CLI:

npx forest-mcp-server
Copy

Or from the package directory:

yarn start           # Production
yarn start:dev       # Development (loads .env file automatically)
Copy

Environment Variables

Example Configuration

Create a .env file in the package directory:

FOREST_ENV_SECRET="your-env-secret"
FOREST_AUTH_SECRET="your-auth-secret"
Copy

Then run:

yarn start:dev
Copy

Or set the variables inline:

FOREST_ENV_SECRET="your-env-secret" FOREST_AUTH_SECRET="your-auth-secret" npx forest-mcp-server
Copy

Restrict Tools

You can restrict which tools the MCP server exposes using enabledTools. Only the listed tools will be available. New tools added in future releases will NOT be automatically enabled — you must explicitly add them.

For example, to set up a read-only mode where the AI assistant can only browse data (no create, update, delete or action execution):

// With Forest Admin Agent — read-only example
agent.mountAiMcpServer({
  enabledTools: ['describeCollection', 'list', 'listRelated'],
});
Copy

# Standalone
export FOREST_MCP_ENABLED_TOOLS="describeCollection,list,listRelated"
npx forest-mcp-server
Copy

When enabledTools is not set, all tools are enabled by default.

See Available Tools for the full list. describeCollection is always enabled as it is required for the MCP server to function properly.

Shorten Token Lifetimes

Forest grants 1 hour (3600s) for an access token and 8 days (691200s) for a refresh token — but it re-grants those 8 days on every refresh, so without refreshTokenSeconds a client that keeps working is never asked to sign in again.

Both values are upper bounds: they can only shorten that, never extend it. For accessTokenSeconds a value above 3600 therefore 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.

// With Forest Agent
agent.mountAiMcpServer({
  tokenTtl: { accessTokenSeconds: 900, refreshTokenSeconds: 86400 },
});
Copy

# Standalone
export FOREST_MCP_ACCESS_TOKEN_TTL_SECONDS=900
export FOREST_MCP_REFRESH_TOKEN_TTL_SECONDS=86400
npx forest-mcp-server
Copy

The two settings differ in what the user notices:

• accessTokenSeconds shortens how long a leaked access token can drive this server: the MCP path closes, its scopes stop applying and its calls stop being audited. It does not shorten the Forest token carried inside that JWT — the JWT is signed, not encrypted, so treat a leak as a Forest token leak and revoke at the source. It is transparent to users — the assistant silently obtains a new one.
• refreshTokenSeconds bounds the time between two interactive logins: once it elapses, the assistant can no longer refresh and the user signs in through the browser again. It is measured from the login itself, so an active assistant cannot keep extending its 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.

The minimum for either value is 60 seconds; anything lower is raised to it. An invalid value (zero, negative, fractional) fails at startup rather than silently leaving the tokens uncapped.

API Endpoints

Once running, the MCP server exposes the following endpoints:

The /mcp endpoint expects MCP protocol messages (JSON-RPC 2.0) and requires a valid OAuth Bearer token with at least the mcp:read scope.

Features

• HTTP Transport: Uses streamable HTTP transport for MCP communication
• OAuth Authentication: Built-in OAuth 2.0 with scopes (mcp:read, mcp:write, mcp:action, mcp:admin)
• CORS Enabled: Allows cross-origin requests
• Express-based: Built on top of Express.js for reliability and extensibility

Development

Building

yarn build
Copy

Watch Mode

yarn build:watch
Copy

Linting

yarn lint
Copy

Testing

yarn test
Copy

Cleaning

yarn clean
Copy

Internal Environment Variables

These are only needed by Forest Admin developers (e.g. to point to a local or staging server):

Architecture

The server consists of:

• ForestMCPServer: Main server class managing the MCP server lifecycle
• McpServer: Core MCP protocol implementation
• StreamableHTTPServerTransport: HTTP transport layer for MCP
• Express App: HTTP server handling incoming requests

License

GPL-3.0

Repository

https://github.com/ForestAdmin/agent-nodejs

Support

For issues and feature requests, please visit the GitHub repository.