--- title: "MCP Server" slug: "mcp-server" status: "update" updated: 2026-11-19T01:45:03Z published: 2026-11-19T01:45:03Z 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 Rocket.Chat Model Context Protocol (MCP) server allows external AI clients to interact with your workspace through a defined set of tools. Connected clients can perform supported workspace operations, such as searching messages, reading threads, posting messages, and managing rooms. All operations are performed on behalf of an authenticated user and are subject to their existing roles and permissions. > [!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. ## Prerequisites Before configuring MCP, 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 a license. - Admin access to **Manage > Workspace > AI center**. By default, only users with the `admin` role can view or change MCP settings. - The `access-mcp` permission granted to every role whose users need to connect MCP clients. This permission is granted to the `admin` role by default. See [Roles in Rocket.Chat](/v1/docs/roles-in-rocketchat) for details. - [Personal access token](/v1/docs/manage-personal-access-tokens) credentials for each user connecting an external client. ## Configure the MCP server 1. Go to **Manage > Workspace > AI center** and click **Configure** on the MCP card. 2. Toggle on Enable MCP endpoint. It exposes the MCP endpoint at `/api/v1/mcp` . 3. Update the following setting: | Setting | Description | | --- | --- | | **Expose extended MCP toolset** | Controls the tools that are available to connected clients. - When disabled, clients get a minimal curated set of workspace tools, hand-picked for common tasks such as reading and posting messages and looking up rooms and users. - When enabled, clients get an extended list that adds further API operations on top of the curated ones.The extended set includes additional operations that can modify messages, rooms, users, statuses, subscriptions, and teams. The full Rocket.Chat API is never exposed as tools. > [!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. | | **Allow dynamic client registration** | Allows MCP clients to register themselves as OAuth clients without an administrator creating an OAuth application first. Anyone who can reach the workspace can register a client. Each user must still sign in and approve the client before it can access their account. > [!NOTE] > Available from Rocket.Chat 9.0.0 and later. | ## 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](https://developer.rocket.chat/apidocs) uses, so a tool call runs through the target operation's own validation, permission checks, and limits. ## Rocket.Chat MCP tools Tool names start with the HTTP method and the [Rocket.Chat API](https://developer.rocket.chat/apidocs) 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. ### Default tool set When **Expose extended MCP toolset** setting is disabled 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_sipExtension` ### Extended tool set With **Expose extended MCP toolset** setting is 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 ### 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](/v1/docs/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. 5. For a client that signs in with OAuth, whether it is registered: **Allow dynamic client registration** is on, or an OAuth app exists for it in **Third-party login**. ## 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 **Manage** > **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. - OAuth access tokens carry no scopes, so OAuth can't limit a client to read-only access.