--- title: "MCP Server" slug: "mcp-server" updated: 2026-08-27T14:14:07Z published: 2026-08-27T14:14:07Z canonical: "docs.rocket.chat/mcp-server" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.rocket.chat/llms.txt > Use this file to discover all available pages before exploring further. # MCP Server ![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/Premium(1).svg) ![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/Alpha.svg) The MCP server exposes a native Model Context Protocol (MCP) endpoint at `POST /api/v1/mcp`, so external AI clients can call a curated set of workspace tools. Each client acts through the Rocket.Chat API as an authenticated user, so a tool call can only do what that user is already allowed to do. > [!NOTE] > - The MCP server ships as **Alpha** in Rocket.Chat 8.8.0 and is off by default. Treat it as a preview: its capabilities and its configuration can change in a later release. > - Three things must line up before a client can connect. The workspace license must include the Rocket.Chat AI add-on, the connecting user's role must hold the `access-mcp` permission, and an admin must turn on the `MCP_Enabled` setting. Miss any one of them and the endpoint stays closed. ## Prerequisites Before you begin, make sure you have: - Rocket.Chat 8.8.0 or later - A workspace license that includes the Rocket.Chat AI add-on. Contact the Sales team to obtain one. Without it, the MCP controls in AI Center stay locked and both settings stay off - Admin access to the AI Center settings in the administration area - The `access-mcp` permission on every role whose users connect an MCP client. It is granted to the `admin` role by default. See [Roles in Rocket.Chat](/roles-in-rocketchat) to grant it to other roles - [API credentials](/manage-personal-access-tokens) for each connecting user, which the client sends on every request the same way any other Rocket.Chat API client does ## Enable the MCP endpoint 1. Open **AI Center** in the administration area, then open its MCP controls. 2. Enable the **MCP** endpoint setting. It is off by default. 3. Save your changes. The endpoint starts accepting requests once the setting is on. While it is off, the endpoint behaves as though it does not exist. ## Choose which tools clients can call Two bounded tool sets are available, and a second setting selects between them. The full API is never published as tools. | `MCP_Expose_Extended_API` | Tools published to clients | | --- | --- | | Off (default) | A minimal curated set of workspace tools, hand-picked for common tasks such as reading and posting messages and looking up rooms and users. | | On | An extended, allow-listed set that adds further API operations on top of the curated ones. | > [!WARNING] > The extended set widens what a connected client can do on behalf of its user. Leave it off unless a client needs more than the curated set, and grant `access-mcp` to the smallest set of roles that needs it. ## Available tools Tool names start with the HTTP method and the [Rocket.Chat API](/rocketchat-api) operation, for example `get_rooms_get` represents `GET /api/v1/rooms.get`. Some REST operations accept alternative identifiers, such as `_by_roomId`, `_by_roomName` or `_by_channel`, `_by_userId`, and `_by_username`; Rocket.Chat publishes each alternative as its own tool so MCP clients get an unambiguous input schema. A tool appears in the catalog only when its underlying REST route is registered in the running Rocket.Chat version. ### Curated tool set (default) With `MCP_Expose_Extended_API` off, six REST operations produce 11 tools: - **Messages:** `post_chat_postMessage_by_roomId`, `post_chat_postMessage_by_channel`, `get_chat_getMessage` - **Channels and rooms:** `post_channels_create`, `get_channels_list_joined`, `get_rooms_get` - **Users:** `get_users_info_by_userId`, `get_users_info_by_username`, `get_users_info_by_importId`, `get_users_info_by_email`, `get_users_info_by_freeSwitchExtension` ### Extended tool set With `MCP_Expose_Extended_API` on, the 11 curated tools stay available and 120 more are added, for 131 tools in total. The extended set includes operations that modify messages, rooms, users, statuses, subscriptions, and teams, so grant `access-mcp` only to trusted roles when this is on. - **Messages:** pin, unpin, star, unstar, follow, unfollow, and react to a message; update a message's text or content; report a message; send a message; search, sync, or list messages, threads, mentions, starred messages, pinned messages, and discussions. - **Direct messages:** open, close, or set the topic of a DM; create a DM by username(s); list, search, or sync DM files, members, messages, and history; block a user in a DM. - **Search:** spotlight search across the workspace. - **Rooms:** check name availability; get room info; create or list discussions; autocomplete channels/private rooms and teams-eligible rooms; save room settings; change archival state; check membership; list members ordered by role; mute, unmute, ban, or unban a user; open, join, hide, invite to, favorite, or leave a room. - **Subscriptions:** get subscriptions; mark read or unread by room or by first unread message. - **Users and statuses:** get the current user; update a user or your own basic info; create a user; get preferences; check username availability; autocomplete users; list a user's teams; get or set presence and status; list and manage custom user statuses. - **Teams:** list teams; create a team; convert a team to a channel; add or remove rooms; update a room; list rooms, child teams, or members; add, update, or remove members; leave a team; get team info; autocomplete; update a team. To see the exact tool names available in your workspace, run the discovery call below. ## Grant the access-mcp permission A user without `access-mcp` cannot use the endpoint, even with valid credentials and the setting on. Grant the permission to the roles that need it from the workspace permissions page. See [Roles in Rocket.Chat](/roles-in-rocketchat) for how to edit the permissions of a role. ## Connect a client An MCP client points at `https://your-workspace-url/api/v1/mcp` and speaks the Model Context Protocol over HTTP. Requests are sent with `POST`; a `GET` on the same path returns `405`, because this endpoint offers no server-initiated stream. Authentication and rate limiting are the same machinery the rest of the [Rocket.Chat API](/rocketchat-api) uses, so a tool call runs through the target operation's own validation, permission checks, and limits. ### Discover the tool catalog Use the MCP `tools/list` method to get the authoritative catalog for your Rocket.Chat version, workspace configuration, and registered REST routes: ```plaintext curl -sS https://your-workspace-url/api/v1/mcp \  -H 'Content-Type: application/json' \  -H 'X-User-Id: ' \  -H 'X-Auth-Token: ' \  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' ``` Generate the `X-User-Id` and `X-Auth-Token` credentials from [Manage Personal Access Tokens](/manage-personal-access-tokens). If a client cannot connect, check these in order: 1. Whether the workspace license includes the AI add-on. 2. Whether `MCP_Enabled` is on. 3. Whether the connecting user's role holds `access-mcp`. 4. Whether the client is sending its credentials on every request, including the first one. ## Rate and resource limits MCP requests pass through two rate-limit layers when the Rocket.Chat API rate limiter is enabled. Both are skipped for a user holding the `api-bypass-rate-limit` permission. - **MCP endpoint limit:** `POST /api/v1/mcp` allows 60 requests per 60 seconds, keyed by the resolved client IP and the MCP route. A JSON-RPC batch counts as one request against this limit, but every tool inside it still counts against its own REST endpoint's limit. A rejected request returns `429` with `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. - **Underlying REST endpoint limits:** every tool call also runs against its underlying REST endpoint's own limit. Endpoints without an override use the workspace default of 10 calls per endpoint per 60 seconds; admins can change this under **Administration** > **Workspace** > **Settings** > **Rate Limiter** > **API Rate Limiter**. Endpoint-specific limits take precedence over the workspace default. These protocol-level bounds protect server memory and execution capacity; they are not rate quotas: - Maximum JSON-RPC batch size: 20 messages (requires protocol version 2025-03-26). - Maximum concurrent tool dispatches within a batch: 4. - Tool execution timeout: 20 seconds. - Maximum response body for one underlying REST tool call: 5 MiB. - Maximum final encoded MCP response: 5 MiB, shared across all calls in a batch. > [!NOTE] > If your workspace sits behind a reverse proxy, configure trusted forwarding headers and `HTTP_FORWARDED_COUNT` correctly so rate limits use the real client address instead of the proxy's. ## Limitations - Alpha and off by default. - `POST` only. A `GET` on the endpoint returns `405`. - Gated by the AI add-on, so a workspace without it cannot enable the feature at all. - Only the curated or the extended tool set is available. Neither exposes the whole API.