@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.

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.