# MCP Server {% hint style="success" %} This is the official documentation of the `@forestadmin/agent` Node.js agent. {% endhint %} ## MCP Server The MCP Server exposes your Forest Admin agent to external AI assistants (like Claude Desktop) via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). ### Enable MCP {% tabs %} {% tab title="Mounted on agent" %} ```javascript const agent = createAgent(options).addDataSource(/* ... */).mountAiMcpServer(); ``` Your MCP endpoint will be available at `{your-agent-url}/mcp`. {% hint style="warning" %} If your application already uses OAuth routes (`/oauth/*`, `/.well-known/*`), use standalone mode instead. {% endhint %} {% endtab %} {% tab title="Standalone" %} Run the MCP server as a separate process: ```bash npm install @forestadmin/mcp-server ``` ```bash FOREST_ENV_SECRET=xxx FOREST_AUTH_SECRET=xxx npx forest-mcp-server ``` | Variable | Required | Default | Description | | -------------------------- | -------- | ------- | ---------------------------------------- | | `FOREST_ENV_SECRET` | Yes | - | Your Forest Admin environment secret | | `FOREST_AUTH_SECRET` | Yes | - | Authentication secret (must match agent) | | `MCP_SERVER_PORT` | No | `3931` | HTTP server port | | `FOREST_MCP_ENABLED_TOOLS` | No | - | Comma separated list of tools to enable | Endpoint: `{your-standalone-server-url}/mcp` {% endtab %} {% endtabs %} ### Available tools #### 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 | ### Restrict tools You can restrict which tools the MCP server exposes using `enabledTools`. Only the tools you list will be available — **new tools added in future releases will NOT be automatically enabled**, so your configuration stays safe over time. #### Read-only mode {% tabs %} {% tab title="Mounted on agent" %} ```javascript agent.mountAiMcpServer({ enabledTools: ['describeCollection', 'list', 'listRelated'], }); ``` {% endtab %} {% tab title="Standalone" %} ```bash FOREST_MCP_ENABLED_TOOLS="describeCollection,list,listRelated" \ FOREST_ENV_SECRET=xxx FOREST_AUTH_SECRET=xxx npx forest-mcp-server ``` {% endtab %} {% endtabs %} This keeps only `describeCollection`, `list` and `listRelated` available. When `enabledTools` is not set, all tools are enabled by default. {% hint style="info" %} `describeCollection` is always enabled, even if omitted from the list, as it is required for the MCP server to function properly. {% endhint %} ### Authentication The MCP server uses OAuth. Users authenticate with their Forest Admin credentials, and the AI assistant operates with the same permissions as the authenticated user. ### Connect your AI assistant Your MCP endpoint is available at `/mcp`. Use the URL that matches your setup: | Setup | URL to use | | ---------------- | ---------------------------------- | | Mounted on agent | `/mcp` | | Standalone | `/mcp` | {% tabs %} {% tab title="Claude Code" %} ```bash claude mcp add --transport http forest-admin ``` Or in `.mcp.json`: ```json { "mcpServers": { "forest-admin": { "type": "http", "url": "" } } } ``` {% endtab %} {% tab title="Claude Desktop" %} Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { "mcpServers": { "forest-admin": { "command": "npx", "args": ["-y", "mcp-remote", ""] } } } ``` Restart Claude Desktop after saving. Requires Node.js 18+. {% endtab %} {% tab title="Cursor" %} In `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project): ```json { "mcpServers": { "forest-admin": { "url": "" } } } ``` {% endtab %} {% tab title="VS Code" %} In `.vscode/mcp.json`: ```json { "servers": { "forest-admin": { "type": "http", "url": "" } } } ``` {% endtab %} {% tab title="Zed" %} In your Zed settings: ```json { "context_servers": { "forest-admin": { "url": "" } } } ``` {% endtab %} {% tab title="Codex (OpenAI)" %} In `~/.codex/config.toml`: ```toml [mcp_servers.forest-admin] url = "" ``` {% endtab %} {% tab title="Dust" %} **Spaces → Tools → Add Tool → Add MCP Server** * **URL**: `` * **Authentication**: Automatic (OAuth) {% endtab %} {% tab title="Windsurf / JetBrains" %} In your MCP config file: ```json { "mcpServers": { "forest-admin": { "command": "npx", "args": ["-y", "mcp-remote", ""] } } } ``` {% hint style="info" %} These clients use `mcp-remote` as a bridge. Requires Node.js 18+. {% endhint %} {% endtab %} {% endtabs %} On first connection, a browser window opens for you to log in with your Forest Admin credentials. #### FAQ | Question | Answer | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **What type should I use?** | `"http"` — this is the [MCP transport name](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports), not the URL scheme. Your URL should still use `https://` | | **What about `"sse"` or `"url"`?** | Not supported. Our server uses Streamable HTTP, which is `"http"` | | **Getting "Does not adhere to MCP server configuration schema" error?** | You used the wrong type. Set `"type": "http"` in your `.mcp.json` | | **Getting "Connection refused" error?** | Your agent/server is not running, or the URL is wrong | | **Getting "File is not defined" error?** | Upgrade to Node.js 20+ (`nvm install 20`). `mcp-remote` requires Node.js 18+, but some versions need 20+ | | **Getting "404 on OAuth" error?** | Verify `FOREST_ENV_SECRET` is correct and matches your environment | | **Browser opens but nothing happens?** | Check that `FOREST_AUTH_SECRET` matches between your agent and MCP server | | **Getting "method\_not\_allowed" error on GET /mcp?** | This is expected. The server responds 405 to an optional GET request, then the POST works normally. If you're stuck and using `mcp-remote`, clear its OAuth cache and restart your client. To clear all servers: `rm -rf ~/.mcp-auth`. To clear a specific server: look at `~/.mcp-auth/mcp-remote-*/*_client_info.json` to identify the hash, then `rm ~/.mcp-auth/mcp-remote-*/_*` | | **Login page says screen size is not supported?** | During OAuth login, Forest Admin requires a minimum browser window size. Resize your browser window to be larger and the login form will appear |