## Problem The MCP Server has no rate limit of its own. Every `POST /api/v4/mcp` request falls into the general authenticated API throttle, which is not tool-aware and is not sized for agent traffic. A limit is required for GA. ## Proposal Add a per-user rate limit on requests to the MCP endpoint, enforced by the Labkit Rack middleware, with a Free/Paid split on GitLab.com. Because the middleware runs before Rails routing it cannot read the JSON-RPC body, so this counts every request to the endpoint — `initialize` and `tools/list` included, not just `tools/call`. That is a deliberate reduction for this round. Numbers: 60/minute Free, 600/minute paid, per user. The flat limit ships disabled and behind a feature flag; GitLab.com is enabled separately by production change request. ## Implementation ### Merged path | Step | MR | What it does | |---|---|---| | Settings | !256468 | `throttle_authenticated_mcp_enabled`, `throttle_authenticated_mcp_requests_per_period`, `throttle_authenticated_mcp_period_in_seconds` on the `rate_limits` jsonb column, a `Gitlab::Throttle` options entry reading them, the settings API and admin attributes, and the `doc/api/settings.md` rows. Nothing enforces yet. | | The rule | !257035 | Registration in `all_throttle_definitions` plus a registry entry in a new `rack_request_mcp` limiter with `claims: true`, matching the MCP path, the `setting_authenticated_mcp` fact and the `rate_limit_mcp_server` feature flag fact. This is the flat per-user limit, and it is what self-managed and Dedicated get. | Registration could not ship with the settings: a spec asserts `ThrottleRegistry` covers every throttle in `all_throttle_definitions`, so registering without the registry entry breaks it. ### The Free/Paid split — options under consideration All three put one rule per tier on the `rack_request_mcp` limiter. They differ in where the plan comes from and where the numbers live. | Option | MR | Plan comes from | Numbers live in | Trade-off | |---|---|---|---|---| | A | !257072 | the tier-aware `requester_plan` fact | literals in `PlanRules`, as every other tier rule does | Smallest diff and reuses the platform fact. The fact is behind a feature flag another group owns, so if that flag goes off the split silently degrades to the flat limit. | | B | !257085 | resolved here, through `TierResolver`, guarded to MCP paths | same | Independent of that flag, so the split cannot be switched off by another group's rollout. Costs one extra call on MCP requests and a small duplication to keep in step with the platform fact. | | C | not written | either of the above | a new `plan_limits` column, read through a cache | Numbers become tunable per plan through the Plan Limits API with no deploy, and self-managed gets the same knob. Costs a migration and a column on a wide table, and does **not** remove the plan-detection dependency — it only moves where 60 and 600 are stored. | Asked the rate-limiting DRIs to weigh in on !257085. Open questions there: whether to consume their fact or resolve the plan ourselves, whether an MCP-scoped tiered rule belongs in `PlanRules`, and how observe mode should work for rules that are not registry entries. Whichever lands, the split is GitLab.com only. Plans mean nothing off SaaS, so self-managed and Dedicated use the single configured value. ## Rollout plan The flat limit and the split roll out separately, and each observes before it rejects. **Flat limit, GitLab.com** 1. Merge with the setting disabled and `rate_limit_mcp_server` off. 1. Add `throttle_authenticated_mcp` to `GITLAB_THROTTLE_DRY_RUN` in the gprd values of `k8s-workloads`. In dry run the limiter builds the rule to count and log rather than block. 1. Enable the setting by production change request, at the shipped defaults. 1. Ramp the feature flag, watching the rate-limiting dashboard at each step. 1. Measure for a full weekly traffic cycle: p95 and p99 requests per user per minute, and how many users would have been rejected at the configured value. Tune the setting if the data calls for it — no deploy needed. 1. Remove the throttle name from `GITLAB_THROTTLE_DRY_RUN`, in its own change request. That is the point at which clients start receiving `429`. Rollback is adding the name back. **Feature flag removal is a GA blocker.** Self-managed and Dedicated read no feature flags, so while the flag exists an administrator who enables the setting gets nothing. **Split** Dry run does not cover it: `GITLAB_THROTTLE_DRY_RUN` applies to registry throttles, and the tier rules are plan rules. Observe mode therefore has to be built, either as rules that only count until a follow-up flips them, or as a counting twin per rule selected by an enforce flag, which is the shape the platform's own per-plan rules use. This is one of the open questions with the DRIs. Platform-wide per-plan limits for paid tiers are enforced on a schedule owned by the rate-limiting group, later than ours. Ours is independent of it, but it means MCP would be the first paid-tier request limit to reject, which is worth naming rather than discovering. **Tracking.** The dry-run window and the enforcement step each need a production change request. Enablement is tracked in its own issue rather than here. <details><summary>Detail</summary> ### Why the middleware rather than `check_rate_limit!` `Gitlab::ApplicationRateLimiter` would run inside the Grape endpoint, after the body is parsed, so it could count only `tools/call` and distinguish read from write tools. It was not chosen: it emits no `RateLimit-*` headers, has no rule-level observe mode, produces no metrics, and sits outside where the tier-aware rate limiting work is being built. The middleware supplies all of those, and the granularity it gives up is granularity this round is not delivering. The MCP specification also requires the limit to exist: its Security Considerations say servers **MUST** "rate limit tool invocations". ### Its own limiter, not `GENERAL` An MCP path is also an API path, so this throttle always co-fires with the general authenticated API one. Registry rules declare a terminating claim, so in a shared limiter the first of the two to match would count the request and the other would stop counting entirely. Protected paths are the shipped precedent: they overlap the general throttles, live in their own limiter, and both counters increment. Plan rules are spliced ahead of registry rules, so they are not affected by a registry claim either way. ### How a Labkit rule gets its numbers `Limiters#build_rules` builds each rule's `limit` and `period` as procs over the throttle definition, resolved per check. That is why the settings have to be a standard throttle definition rather than a bespoke key: an admin change then takes effect at runtime with no deploy, and the settings API and admin page come with the pattern. ### Tier resolution `TierResolver.tier_for(requester_type, requester_id)` resolves a plan from the requester id alone, with no namespace required — it reads the highest plan across the user's memberships and falls back to Free, through a short-lived cache. That matters because `/api/v4/mcp` carries no project or group in its path, so the namespace-grain resolution used elsewhere returns nothing for MCP. It resolves a plan only for a user requester. Deploy tokens cannot authenticate to the MCP endpoint at all, so that is not a gap. ### Verification Set a low value, drive `POST /api/v4/mcp` past it, and confirm a `429` carrying `Retry-After` and the `RateLimit-*` headers, the same headers present on preceding successful responses, `initialize` and `tools/list` counting toward the same bucket, one user exhausting the limit leaving another unaffected, and both the MCP counter and the general throttle's counter incrementing in Redis. Step-by-step validation with observed output is in !257035. </details>