MCP Server

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.

• 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 to grant it to other roles

• API credentials 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.

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 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 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 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:

curl -sS https://your-workspace-url/api/v1/mcp \
  -H 'Content-Type: application/json' \
  -H 'X-User-Id: <user-id>' \
  -H 'X-Auth-Token: <personal-access-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.

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.

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.