docs: document OAUTH_REGISTER_RATE_LIMIT_PER_HOUR across README and skill

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: zereight

CHANGELOG.md

@@ -16,6 +16,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
 ##### Added
 
+- `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR` — tune per-IP `POST /register` rate limit when `GITLAB_MCP_OAUTH=true` (default `20`/hour) ([#630](https://github.com/zereight/gitlab-mcp/pull/630))
 - `health_check` reports GitLab instance version from `/api/v4/version` when authenticated ([#617](https://github.com/zereight/gitlab-mcp/issues/617))
 - `GITLAB_PERMISSION_MODE` with `readonly`, `modify`, and `full` permission tiers
 - Startup new-version notice (disable with `GITLAB_DISABLE_VERSION_CHECK=true`) ([#573](https://github.com/zereight/gitlab-mcp/pull/573))

README.ko.md

@@ -317,6 +317,7 @@ Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx
 - `MCP_ALLOWED_ORIGINS`
 - `GITLAB_MCP_OAUTH`
 - `GITLAB_OAUTH_CALLBACK_PROXY`
+- `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`
 - `OAUTH_STATELESS_MODE`
 - `OAUTH_STATELESS_SECRET`
 
@@ -465,13 +466,15 @@ node build/index.js
 | `GITLAB_API_URL`                            | 예     | GitLab 인스턴스 API URL(예: `https://gitlab.com/api/v4`)                                                                                                                   |
 | `STREAMABLE_HTTP`                           | 예     | 반드시 `true`(SSE 미지원)                                                                                                                                                  |
 | `GITLAB_OAUTH_SCOPES`                       | 아니오 | 요청할 GitLab scope 목록(쉼표 구분). 기본값은 `api` 또는 `GITLAB_READ_ONLY_MODE=true`일 때 `read_api`입니다. 사전 등록 애플리케이션에 해당 scope가 설정되어 있어야 합니다. |
+| `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`        | 아니오 | Dynamic Client Registration(`POST /register`)의 클라이언트 IP당 rolling 한도. 기본 `20`/시간, 범위 `1`–`1000`. IDE 창 여러 개 등으로 등록이 막히면 올리세요. GitLab API 한도와 무관합니다. |
 | `MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL` | 아니오 | 로컬 HTTP 개발에서만 `true`                                                                                                                                                |
 
 **중요 사항:**
 
 - MCP OAuth는 **Streamable HTTP 전송에서만** 동작합니다(`SSE=true`와 호환되지 않음).
 - 각 사용자 세션은 자체 OAuth 토큰을 저장하며 완전히 격리됩니다.
 - 세션 타임아웃, rate limiting, capacity limit은 `REMOTE_AUTHORIZATION` 모드와 동일하게 적용됩니다(`SESSION_TIMEOUT_SECONDS`, `MAX_REQUESTS_PER_MINUTE`, `MAX_SESSIONS`).
+- **DCR rate limiting:** `POST /register`는 클라이언트 IP당 `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`로 제한됩니다(기본 20/시간). `/mcp` 한도 및 GitLab API quota와 별개입니다. [environment-variables.md](docs/configuration/environment-variables.md#oauth_register_rate_limit_per_hour) 참고.
 - **헤더 인증 fallback:** `Private-Token` 또는 `JOB-TOKEN` 요청 헤더가 있으면 OAuth 검증을 건너뛰고 raw token을 해당 세션에 직접 사용합니다. 같은 서버 인스턴스에서 OAuth 플로우와 함께 PAT 및 CI job token을 사용할 수 있습니다. `Authorization: Bearer`는 항상 OAuth token으로 처리됩니다. PAT 기반 헤더 인증에는 `Private-Token`을 사용하세요.
 
 ## Agent Skill Files

README.md

@@ -351,6 +351,7 @@ Commonly referenced variables:
 - `MCP_ALLOWED_ORIGINS`
 - `GITLAB_MCP_OAUTH`
 - `GITLAB_OAUTH_CALLBACK_PROXY`
+- `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`
 - `OAUTH_STATELESS_MODE`
 - `OAUTH_STATELESS_SECRET`
 
@@ -505,6 +506,7 @@ No `headers` field is needed — Claude.ai obtains the token via OAuth automatic
 | `GITLAB_API_URL`                            | Yes      | Your GitLab instance API URL (e.g. `https://gitlab.com/api/v4`)                                                                                                                                                     |
 | `STREAMABLE_HTTP`                           | Yes      | Must be `true` (SSE is not supported)                                                                                                                                                                               |
 | `GITLAB_OAUTH_SCOPES`                       | No       | Comma-separated GitLab scopes to request (e.g. `api,read_user`). Defaults to `api` (or `read_api` when `GITLAB_READ_ONLY_MODE=true`). The pre-registered application must be configured with at least these scopes. |
+| `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`        | No       | Per-IP rolling limit for Dynamic Client Registration (`POST /register`). Default `20`/hour; range `1`–`1000`. Raise when clients (e.g. multiple IDE windows) hit registration throttling. Not a GitLab API limit. |
 | `MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL` | No       | Set `true` for local HTTP dev only                                                                                                                                                                                  |
 
 **Important Notes:**
@@ -514,6 +516,9 @@ No `headers` field is needed — Claude.ai obtains the token via OAuth automatic
 - Session timeout, rate limiting, and capacity limits apply identically to the
   `REMOTE_AUTHORIZATION` mode (`SESSION_TIMEOUT_SECONDS`, `MAX_REQUESTS_PER_MINUTE`,
   `MAX_SESSIONS`)
+- **DCR rate limiting:** `POST /register` is limited to `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`
+  per client IP (default 20/hour). Separate from `/mcp` limits and GitLab API quotas.
+  See [environment-variables.md](docs/configuration/environment-variables.md#oauth_register_rate_limit_per_hour).
 - **Header auth fallback:** when `Private-Token` or `JOB-TOKEN` request headers are
   present, OAuth validation is skipped and the raw token is used directly for that
   session. This allows PATs and CI job tokens to be used alongside the OAuth flow on

README.zh-CN.md

@@ -317,6 +317,7 @@ Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx
 - `MCP_ALLOWED_ORIGINS`
 - `GITLAB_MCP_OAUTH`
 - `GITLAB_OAUTH_CALLBACK_PROXY`
+- `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`
 - `OAUTH_STATELESS_MODE`
 - `OAUTH_STATELESS_SECRET`
 
@@ -465,13 +466,15 @@ node build/index.js
 | `GITLAB_API_URL`                            | 是   | GitLab 实例 API URL（例如 `https://gitlab.com/api/v4`）                                                                                  |
 | `STREAMABLE_HTTP`                           | 是   | 必须为 `true`（不支持 SSE）                                                                                                              |
 | `GITLAB_OAUTH_SCOPES`                       | 否   | 要请求的 GitLab scopes，以逗号分隔。默认值为 `api`，当 `GITLAB_READ_ONLY_MODE=true` 时为 `read_api`。预注册应用必须配置至少这些 scopes。 |
+| `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`        | 否   | Dynamic Client Registration（`POST /register`）的每客户端 IP rolling 限制。默认 `20`/小时，范围 `1`–`1000`。多个 IDE 窗口等导致注册被限流时可调高。与 GitLab API 限额无关。 |
 | `MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL` | 否   | 仅用于本地 HTTP 开发                                                                                                                     |
 
 **重要说明：**
 
 - MCP OAuth **仅适用于 Streamable HTTP 传输**（与 `SSE=true` 不兼容）。
 - 每个用户会话保存自己的 OAuth token，会话完全隔离。
 - 会话超时、rate limiting 和 capacity limit 与 `REMOTE_AUTHORIZATION` 模式相同（`SESSION_TIMEOUT_SECONDS`, `MAX_REQUESTS_PER_MINUTE`, `MAX_SESSIONS`）。
+- **DCR rate limiting：** `POST /register` 按客户端 IP 受 `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR` 限制（默认 20/小时）。与 `/mcp` 限制及 GitLab API 配额无关。详见 [environment-variables.md](docs/configuration/environment-variables.md#oauth_register_rate_limit_per_hour)。
 - **请求头认证 fallback：** 当请求头中存在 `Private-Token` 或 `JOB-TOKEN` 时，会跳过 OAuth 验证，并直接将原始 token 用于该会话。这样可以在同一服务器实例中同时使用 OAuth 流程、PAT 和 CI job token。`Authorization: Bearer` 始终被视为 OAuth token。PAT 请求头认证请使用 `Private-Token`。
 
 ## Agent Skill Files

docs/auth/oauth-callback-proxy.md

@@ -132,6 +132,7 @@ sequenceDiagram
 | State is not replayable | Deleted from pending store after `/callback` consumes it |
 | Error responses are sanitized | Generic messages to clients, details in server logs only |
 | Bounded memory | In-memory LRU cache, max 1000 entries |
+| DCR rate limit | `POST /register` limited per client IP (`OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`, default 20/hour) |
 
 ## Configuration
 
@@ -141,6 +142,8 @@ GITLAB_MCP_OAUTH=true
 GITLAB_OAUTH_CALLBACK_PROXY=true
 MCP_SERVER_URL=https://mcp-server.example.com
 GITLAB_OAUTH_APP_ID=<app-id>
+# Optional: raise when many MCP clients register at once (e.g. multiple IDE windows)
+# OAUTH_REGISTER_RATE_LIMIT_PER_HOUR=50
 ```
 
 In GitLab Admin → Applications:

docs/configuration/environment-variables.md

@@ -122,6 +122,9 @@ Default:
 
 Enables the server-side MCP OAuth proxy mode for remote MCP clients.
 
+Dynamic Client Registration (`POST /register`) is rate-limited per client IP;
+tune with `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR` (default `20`/hour).
+
 ### `GITLAB_OAUTH_CALLBACK_PROXY`
 
 Set to `true` to make the MCP server handle GitLab's OAuth callback at
@@ -579,8 +582,8 @@ Monitor rejections via `/metrics` → `rejectedByRateLimit` or
 
 ### `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`
 
-Maximum client registration (`POST /register`) requests allowed per IP per
-rolling 1-hour window. Applies when `GITLAB_MCP_OAUTH=true`.
+Maximum client registration (`POST /register`) requests allowed per client IP
+per rolling 1-hour window. Applies when `GITLAB_MCP_OAUTH=true`.
 
 Valid range: `1`-`1000`.
 
@@ -589,7 +592,15 @@ Default:
 - `20`
 
 Raise this if legitimate MCP clients are being throttled during dynamic client
-registration, or lower it to harden against registration abuse.
+registration (for example multiple IDE windows each calling `POST /register`), or
+lower it to harden against registration abuse.
+
+Counts apply **per server process** (in-memory `express-rate-limit` store). In
+multi-instance deployments each replica maintains its own counter; use
+ingress-level limits when you need a strict global cap.
+
+Separate from `MAX_REQUESTS_PER_MINUTE` (`/mcp` and other OAuth routes) and
+from GitLab upstream API rate limits.
 
 ### `MAX_SESSIONS`
 
@@ -649,6 +660,7 @@ Maximum GitLab client pool size.
 - `REMOTE_AUTHORIZATION=true` or `GITLAB_MCP_OAUTH=true`
 - `MCP_TRUST_PROXY=true` (when behind a reverse proxy)
 - `MAX_REQUESTS_PER_MINUTE=300` (tune from metrics)
+- `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR` (when `GITLAB_MCP_OAUTH=true`; raise if DCR `/register` returns 429)
 - `MCP_SERVER_URL` or `MCP_ALLOWED_HOSTS` (non-loopback public host)
 - `HOST`
 - `PORT`

skills/gitlab-mcp/SKILL.md

@@ -123,5 +123,6 @@ Enable with `GITLAB_TOOLSETS=vulnerabilities` (requires GitLab Ultimate).
 - **Dynamic discovery**: `discover_tools` lists and activates opt-in toolsets at runtime
 - **GraphQL**: `execute_graphql` for queries not covered by REST tools
 - **Tool docs**: `docs/tools/` is generated from `tools/registry.ts`; prefer it for exact schemas
+- **Remote MCP OAuth**: when `GITLAB_MCP_OAUTH=true`, `POST /register` (DCR) is rate-limited per client IP (default 20/hour via MCP SDK; tune with `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`). Separate from `MAX_REQUESTS_PER_MINUTE` and GitLab API quotas — see [environment-variables.md](../../docs/configuration/environment-variables.md#oauth_register_rate_limit_per_hour)
 - **Zoekt search**: `search_code`, `search_project_code`, `search_group_code` (requires advanced search enabled)
 - **Work Items**: GraphQL-based alternative to issues (Premium/Ultimate features)