# 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 | | **How does the standalone MCP server know where my agent is?** | You don't configure it. On startup, the MCP server calls Forest Admin with your `FOREST_ENV_SECRET` and retrieves the agent URL registered for that environment. Every tool call is then forwarded to that URL using the authenticated user's OAuth token — so as long as your agent is reachable from the MCP server and registered in the same environment, no extra configuration is needed | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.forestadmin.com/developer-guide-agents-nodejs/agent-customization/ai/mcp-server.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.