## Summary ### Rate limits for GA | Limit | Free (individual developer) | Paid (team / organizational) | |---|---|---| | Tool operations per minute (sustained) | 60 | 600 | <details> <summary> Originally Proposed but cut for now </summary> | Limit | Free (individual developer) | Paid (team / organizational) | | Burst capacity (short periods) | up to 120/min | up to 1,200/min | | Concurrent operations per user | 2 | 10 | | Write operations per minute | 10 | 120 | | GraphQL query complexity (max) | 150 | 250 ~~| </details> > **Note:** These limits are tighter than GitLab's general authenticated API throttle (`2,000` requests/min per user on GitLab.com), but looser than several endpoint limits MCP tool calls already hit: `search_rate_limit` caps authenticated search at `30/min`, and semantic code search at `10/min`. There is a possibility that users hit those underlying API limits before the general MCP one in case usage exists solels of tools calling those endpoints. ### Throttling Every throttled response is an HTTP `429` Too Many Requests carrying the header set GitLab's `Rack::Attack` throttles already use, so existing GitLab API clients need no MCP-specific handling. The MCP endpoint emits these headers itself; they are not inherited from the application rate limiter: | Header | Meaning | |---|---| | `RateLimit-Limit` | Ceiling for the current window (tool ops/min for your tier) | | `RateLimit-Remaining` | Operations left in the current window | | `RateLimit-Reset` | Unix epoch when the window resets | | `RateLimit-ResetTime` | RFC 1123 timestamp of the same reset | | `Retry-After` | Seconds to wait before retrying | A `429` is never returned without `Retry-After` and a reset time. Clients that honor `Retry-After` will never be hard-blocked. | Tier | Behavior when approaching the limit | Behavior at the limit | |---|---|---| | Free | `RateLimit-Remaining` counts down; no artificial delay added | Requests over the limit are rejected with `429` + `Retry-After` | | Paid | Bursts are smoothed to protect long-running, multi-step workflows; short spikes are absorbed up to the burst ceiling | Only sustained traffic past the burst ceiling is rejected with `429` + `Retry-After` | > **Internal note:** Enforcement lives in the before block of the MCP endpoint (`POST /api/v4/mcp)`. > * Inheriting the underlying API limit only holds for `REST`-backed tools, which re-dispatch through the existing Grape endpoint in-process. > * GraphQL-backed tools (the majority) run via `GitlabSchema.execute` and get no per-tool limit, only GraphQL complexity/depth budgets. > * Every request still counts once against the general authenticated throttle (`2,000` req/min on GitLab.com), and limit values vary by deployment type. > * The header names above are borrowed from `Rack::Attack` for client compatibility, but that's names only: the underlying limiter emits no `RateLimit-*` headers, just a bare `Retry-After`, so the MCP endpoint has to construct and emit the full set itself. ### Outstanding questions 1. When an MCP tool calls an endpoint with its own lower limit, which limit takes precedence? These per-endpoint limits also vary by deployment type, with self-managed defaults differing from GitLab.com's configured values. 1. **Answer:** The lower limit takes precedence (needs to be documented), as those can be meant to protect critical systems. 2. ~~How can per-user concurrency limiting be implemented? No request-level per-user concurrency limiter exists anywhere in Rails. Every user-facing limit is a counter-over-a-window. Sidekiq's is per-worker-class, Topology Service's is global. Building one means new Redis machinery plus in-flight tracking with leak recovery. May be reclassified as a post-GA spike.~~ _Not relevant for now_ 3. How will tier resolution work when not all MCP server requests are tied to a specific namespace or project? 1. **Answer**: See https://gitlab.com/groups/gitlab-org/-/work_items/22800#note_3853563340