Add MCP server rate limit settings to the admin Network page

Terri Churequested to merge
629884-mcp-rate-limit-admin-settings into master

What does this MR do and why?

Adds a GitLab MCP server rate limits section to Admin > Settings > Network so administrators can enable and tune the MCP server throttle, which ships disabled and could previously only be set through the settings API or a Rails console. It also documents the limit for administrators and adds a troubleshooting entry for the 429 a client receives when it is throttled.

The MCP limit applies in addition to the authenticated API rate limit, not instead of it: every POST /api/v4/mcp request counts against both.

Implementation notes
  • The fieldset follows _dependency_proxy_limits.html.haml, not the shared _network_rate_limits.html.haml. The shared partial renders unauthenticated fields too, and there is no unauthenticated MCP throttle.
  • The three settings, throttle_authenticated_mcp_enabled, _requests_per_period and _period_in_seconds, already exist on master and are already permitted. This MR adds only the view.
  • The section anchor is js-mcp-limits-settings, so production change requests can link to it.
  • The 429 troubleshooting entry was checked on a running instance. A refused request returns text/plain (Retry later by default), not a JSON-RPC message, so a client typically shows a generic error. It is logged only by Workhorse, not in api_json.log or auth.log.
  • For #629885 (closed): the GitLab.com per-plan values are documented on the MCP server page, and doc/user/gitlab_com/rate_limits.md links to them rather than repeating the table, so there is one place to maintain them.

References

Screenshots or screen recordings

Before After
No MCP section on the Network page image

image

How to set up and validate locally

These steps test the admin setting, which is how GitLab Self-Managed and GitLab Dedicated limit MCP requests. Run them with SaaS mode off. GitLab.com does not use this setting. Its MCP limits come from the rate_limiter_mcp_limits_<plan>_{info,enforce} feature flags, so do not enable this setting in SaaS mode.

  1. Go to Admin > Settings > Network and expand GitLab MCP server rate limits. It sits between Files API rate limits and Search rate limits.

  2. Select Enable authenticated MCP server request rate limit, set Max authenticated MCP server requests per period per user to 3, and select Save changes. The page reloads at the #js-mcp-limits-settings anchor.

  3. Confirm the values persisted in rails console:

    ApplicationSetting.current.rate_limits.slice('throttle_authenticated_mcp_enabled', 'throttle_authenticated_mcp_requests_per_period')

  4. Wait about 60 seconds for the application settings cache to expire, then send more than three requests with a personal access token that has the mcp scope:

    curl --request POST "https://gdk.test:3443/api/v4/mcp" \
  --header "PRIVATE-TOKEN: <token>" --header "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' --include

    The fourth request returns 429 with RateLimit-Name: throttle_authenticated_mcp and a Retry-After header.

  5. Select Learn more in the section description. It opens the new Enable authenticated MCP server request rate limit section.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Terri Chu

Merge request reports