@zereight/mcp-gitlab 2.1.6 → 2.1.8

package/README.ko.md

@@ -155,6 +155,21 @@ docker run -i --rm \
 
 MCP OAuth 사양을 지원하는 원격 MCP 클라이언트(예: Claude.ai)용입니다. 서버는 완전한 OAuth 2.0 인증 서버로 동작합니다. 인증되지 않은 요청은 `401 + WWW-Authenticate` 응답을 받고, 클라이언트 측 OAuth 브라우저 플로우가 자동으로 시작됩니다.
 
+OpenCode, MCPJam, Claude.ai 같은 원격 MCP 클라이언트는 인증 중에 자체 callback URL을 보낼 수 있습니다. 모든 클라이언트 callback URL을 GitLab에 등록할 수 없다면 `GITLAB_OAUTH_CALLBACK_PROXY=true`를 켜세요. 콜백 프록시 모드에서는 GitLab에 `{MCP_SERVER_URL}/callback` 하나만 Redirect URI로 등록하면 됩니다.
+
+`GITLAB_OAUTH_REDIRECT_URI`는 로컬 OAuth(`GITLAB_USE_OAUTH`) 전용입니다. 원격 MCP OAuth 클라이언트 callback URL을 덮어쓰지 않으며, 원격 `Unregistered redirect_uri` 오류 해결용으로 사용하면 안 됩니다.
+
+이 변수가 존재하는 이유는 로컬 OAuth 플로우가 MCP 서버와 같은 머신에서 브라우저를 열고, `http://127.0.0.1:8888/callback` 같은 로컬 HTTP 서버로 callback을 받기 때문입니다.
+
+원격 MCP OAuth는 다릅니다. `GITLAB_MCP_OAUTH=true` 모드에서는 MCP 클라이언트가 `/authorize` 요청 중에 자체 callback URL을 제공합니다. `GITLAB_OAUTH_REDIRECT_URI`는 그 클라이언트 제공 URL을 대체하지 않습니다.
+
+| 모드 | 활성화 변수 | Callback 변수 | GitLab Redirect URI |
+| --- | --- | --- | --- |
+| 로컬 OAuth | `GITLAB_USE_OAUTH=true` | `GITLAB_OAUTH_REDIRECT_URI` | `http://127.0.0.1:8888/callback` 또는 로컬 callback |
+| 원격 MCP OAuth | `GITLAB_MCP_OAUTH=true` | `GITLAB_OAUTH_CALLBACK_PROXY=true` | `{MCP_SERVER_URL}/callback` |
+
+MCP 서버가 직접 로컬 브라우저 callback을 받을 때만 `GITLAB_OAUTH_REDIRECT_URI`를 사용하세요. 원격 MCP 클라이언트가 callback URL을 소유하는 경우에는 `GITLAB_OAUTH_CALLBACK_PROXY=true`를 사용하세요.
+
 **동작 방식**: 공개 HTTPS URL을 가진 위치에 이 MCP 서버를 배포합니다. MCP 클라이언트는 `{MCP_SERVER_URL}/mcp`로 연결합니다. 서버는 OAuth 2.0 플로우를 처리하고 GitLab과 자격 증명을 교환합니다.
 
 **사전 준비:**
@@ -173,6 +188,16 @@ MCP OAuth 사양을 지원하는 원격 MCP 클라이언트(예: Claude.ai)용
 | `GITLAB_OAUTH_CALLBACK_PROXY` | 선택 | MCP 서버의 고정 `/callback` URL을 사용하려면 `true` |
 | `GITLAB_OAUTH_SCOPES` | 선택 | 쉼표로 구분된 scope 목록(기본값: `api,read_api,read_user`) |
 
+> **`Unregistered redirect_uri` 문제 해결**
+>
+> 브라우저 URL의 `redirect_uri`를 확인하세요. 값이 `http://127.0.0.1:xxxxx/.../callback` 같은 클라이언트 callback을 가리키면 다음 설정을 켜세요.
+>
+> ```env
+> GITLAB_OAUTH_CALLBACK_PROXY=true
+> ```
+>
+> 원격 MCP OAuth 문제를 `GITLAB_OAUTH_REDIRECT_URI` 변경으로 해결하려고 하지 마세요. 이 변수는 로컬 OAuth(`GITLAB_USE_OAUTH`) 전용입니다.
+
 ```shell
 docker run -i --rm \
   -e HOST=0.0.0.0 \

package/README.md

@@ -8,13 +8,13 @@
 
 ## @zereight/mcp-gitlab
 
-A comprehensive GitLab MCP server for AI clients. Manage projects, merge requests, issues, pipelines, wiki, releases, milestones, and more through stdio, SSE, and Streamable HTTP.
+A comprehensive GitLab MCP server for AI clients. Manage projects, merge requests, issues, pipelines, wiki, releases, tags, milestones, and more through stdio, SSE, and Streamable HTTP.
 
 Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization for VS Code, Claude, Cursor, Copilot, and other MCP clients.
 
 ### Why use this GitLab MCP?
 
-- Broad GitLab coverage — projects, repository browsing, merge requests, issues, pipelines, wiki, releases, labels, milestones, and more
+- Broad GitLab coverage — projects, repository browsing, merge requests, issues, pipelines, wiki, releases, tags, labels, milestones, and more
 - Flexible auth — Personal Access Token, local OAuth2 browser flow, MCP OAuth proxy, and per-request remote authorization
 - Multiple transports — stdio for local clients, SSE for legacy clients, and Streamable HTTP for modern remote deployments
 - Client-friendly setup — examples for Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, and Amp Code
@@ -33,6 +33,7 @@ Quick start: choose either Personal Access Token or OAuth2 setup below and use `
 - [OAuth2 Authentication Setup Guide](./docs/oauth-setup.md)
 - [Environment Variables Reference](./docs/environment-variables.md)
 - [Stateless Mode — Multi-Pod HPA](./docs/stateless-mode.md)
+- [Custom Agents and Multiple PAT Setup](./docs/custom-agent-multiple-pat.md)
 
 ## Usage
 
@@ -159,6 +160,32 @@ The server acts as a full OAuth 2.0 authorization server — unauthenticated req
 receive a `401 + WWW-Authenticate` response, which triggers the OAuth browser flow
 automatically on the client side.
 
+Remote MCP clients such as OpenCode, MCPJam, and Claude.ai can send their own
+callback URL during authorization. If you cannot register every client callback
+URL in GitLab, enable `GITLAB_OAUTH_CALLBACK_PROXY=true`. With callback proxy
+mode, GitLab only needs one registered redirect URI: `{MCP_SERVER_URL}/callback`.
+
+`GITLAB_OAUTH_REDIRECT_URI` is for local OAuth (`GITLAB_USE_OAUTH`) only. It does
+not override remote MCP OAuth client callback URLs and should not be used to fix
+remote `Unregistered redirect_uri` errors.
+
+This variable exists because the local OAuth flow starts a browser on the same
+machine as the MCP server and listens for the callback on a local HTTP server,
+for example `http://127.0.0.1:8888/callback`.
+
+Remote MCP OAuth is different. In `GITLAB_MCP_OAUTH=true` mode, the MCP client
+provides its own callback URL during `/authorize`. `GITLAB_OAUTH_REDIRECT_URI`
+does not replace that client-provided URL.
+
+| Mode | Enable with | Callback variable | GitLab redirect URI |
+| --- | --- | --- | --- |
+| Local OAuth | `GITLAB_USE_OAUTH=true` | `GITLAB_OAUTH_REDIRECT_URI` | `http://127.0.0.1:8888/callback` or your local callback |
+| Remote MCP OAuth | `GITLAB_MCP_OAUTH=true` | `GITLAB_OAUTH_CALLBACK_PROXY=true` | `{MCP_SERVER_URL}/callback` |
+
+Use `GITLAB_OAUTH_REDIRECT_URI` only when the MCP server itself owns the local
+browser callback. Use `GITLAB_OAUTH_CALLBACK_PROXY=true` when a remote MCP client
+owns the callback URL.
+
 **How it works**: You deploy this MCP server somewhere with a public HTTPS URL. MCP
 clients connect to `{MCP_SERVER_URL}/mcp`. The server handles the OAuth 2.0 flow,
 exchanging credentials with GitLab on behalf of the client.
@@ -179,6 +206,18 @@ exchanging credentials with GitLab on behalf of the client.
 | `GITLAB_OAUTH_CALLBACK_PROXY` | optional | Set to `true` to use the MCP server's fixed `/callback` URL |
 | `GITLAB_OAUTH_SCOPES` | optional | Comma-separated scopes (default: `api,read_api,read_user`) |
 
+> **Troubleshooting `Unregistered redirect_uri`**
+>
+> Check the `redirect_uri` in the browser URL. If it points to a client callback
+> such as `http://127.0.0.1:xxxxx/.../callback`, enable:
+>
+> ```env
+> GITLAB_OAUTH_CALLBACK_PROXY=true
+> ```
+>
+> Do not fix remote MCP OAuth by changing `GITLAB_OAUTH_REDIRECT_URI`. That
+> variable is for local OAuth (`GITLAB_USE_OAUTH`) only.
+
 ```shell
 docker run -i --rm \
   -e HOST=0.0.0.0 \
@@ -497,97 +536,108 @@ Register the skill directory in your AI client to get optimal tool usage guidanc
 48. `get_issue` - Get details of a specific issue in a GitLab project
 49. `update_issue` - Update an issue in a GitLab project
 50. `delete_issue` - Delete an issue from a GitLab project
-51. `list_issue_links` - List all issue links for a specific issue
-52. `list_issue_discussions` - List discussions for an issue in a GitLab project
-53. `get_issue_link` - Get a specific issue link
-54. `create_issue_link` - Create an issue link between two issues
-55. `delete_issue_link` - Delete an issue link
-56. `list_namespaces` - List all namespaces available to the current user
-57. `get_namespace` - Get details of a namespace by ID or path
-58. `verify_namespace` - Verify if a namespace path exists
-59. `get_project` - Get details of a specific project
-60. `list_projects` - List projects accessible by the current user
-61. `list_project_members` - List members of a GitLab project
-62. `list_group_projects` - List projects in a GitLab group with filtering options
-63. `list_group_iterations` - List group iterations with filtering options
-64. `list_labels` - List labels for a project
-65. `get_label` - Get a single label from a project
-66. `create_label` - Create a new label in a project
-67. `update_label` - Update an existing label in a project
-68. `delete_label` - Delete a label from a project
-69. `list_pipelines` - List pipelines in a GitLab project with filtering options
-70. `get_pipeline` - Get details of a specific pipeline in a GitLab project
-71. `list_pipeline_jobs` - List all jobs in a specific pipeline
-72. `list_pipeline_trigger_jobs` - List all trigger jobs (bridges) in a specific pipeline that trigger downstream pipelines
-73. `get_pipeline_job` - Get details of a GitLab pipeline job number
-74. `get_pipeline_job_output` - Get the output/trace of a GitLab pipeline job with optional pagination to limit context window usage
-75. `create_pipeline` - Create a new pipeline for a branch or tag
-76. `retry_pipeline` - Retry a failed or canceled pipeline
-77. `cancel_pipeline` - Cancel a running pipeline
-78. `play_pipeline_job` - Run a manual pipeline job
-79. `retry_pipeline_job` - Retry a failed or canceled pipeline job
-80. `cancel_pipeline_job` - Cancel a running pipeline job
-81. `list_deployments` - List deployments in a GitLab project with filtering options
-82. `get_deployment` - Get details of a specific deployment in a GitLab project
-83. `list_environments` - List environments in a GitLab project
-84. `get_environment` - Get details of a specific environment in a GitLab project
-85. `list_job_artifacts` - List artifact files in a job's artifacts archive. Returns file names, paths, types, and sizes
-86. `download_job_artifacts` - Download the entire artifact archive (zip) for a job to a local path. Returns the saved file path
-87. `get_job_artifact_file` - Get the content of a single file from a job's artifacts by its path within the archive
-88. `list_milestones` - List milestones in a GitLab project with filtering options
-89. `get_milestone` - Get details of a specific milestone
-90. `create_milestone` - Create a new milestone in a GitLab project
-91. `edit_milestone` - Edit an existing milestone in a GitLab project
-92. `delete_milestone` - Delete a milestone from a GitLab project
-93. `get_milestone_issue` - Get issues associated with a specific milestone
-94. `get_milestone_merge_requests` - Get merge requests associated with a specific milestone
-95. `promote_milestone` - Promote a milestone to the next stage
-96. `get_milestone_burndown_events` - Get burndown events for a specific milestone
-97. `list_wiki_pages` - List wiki pages in a GitLab project
-98. `get_wiki_page` - Get details of a specific wiki page
-99. `create_wiki_page` - Create a new wiki page in a GitLab project
-100. `update_wiki_page` - Update an existing wiki page in a GitLab project
-101. `delete_wiki_page` - Delete a wiki page from a GitLab project
-102. `list_group_wiki_pages` - List wiki pages in a GitLab group
-103. `get_group_wiki_page` - Get details of a specific group wiki page
-104. `create_group_wiki_page` - Create a new wiki page in a GitLab group
-105. `update_group_wiki_page` - Update an existing wiki page in a GitLab group
-106. `delete_group_wiki_page` - Delete a wiki page from a GitLab group
-107. `get_repository_tree` - Get the repository tree for a GitLab project (list files and directories)
-108. `list_commits` - List repository commits with filtering options
-109. `get_commit` - Get details of a specific commit
-110. `get_commit_diff` - Get changes/diffs of a specific commit
-111. `list_releases` - List all releases for a project
-112. `get_release` - Get a release by tag name
-113. `create_release` - Create a new release in a GitLab project
-114. `update_release` - Update an existing release in a GitLab project
-115. `delete_release` - Delete a release from a GitLab project (does not delete the associated tag)
-116. `create_release_evidence` - Create release evidence for an existing release (GitLab Premium/Ultimate only)
-117. `download_release_asset` - Download a release asset file by direct asset path
-118. `get_users` - Get GitLab user details by usernames
-119. `list_events` - List all events for the currently authenticated user
-120. `get_project_events` - List all visible events for a specified project
-121. `upload_markdown` - Upload a file to a GitLab project for use in markdown content
-122. `download_attachment` - Download an uploaded file from a GitLab project by secret and filename
-123. `get_work_item` - Get a single work item with full details including status, hierarchy (parent/children), type, labels, assignees, and all widgets
-124. `list_work_items` - List work items in a project with filters (type, state, search, assignees, labels). Returns items with status and hierarchy info
-125. `create_work_item` - Create a new work item (issue, task, incident, test_case, epic, key_result, objective, requirement, ticket). Supports setting title, description, labels, assignees, weight, parent, health status, start/due dates, milestone, and confidentiality
-126. `update_work_item` - Update a work item. Can modify title, description, labels, assignees, weight, state, status, parent hierarchy, children, health status, start/due dates, milestone, confidentiality, linked items, and custom fields
-127. `convert_work_item_type` - Convert a work item to a different type (e.g. issue to task, task to incident)
-128. `list_work_item_statuses` - List available statuses for a work item type in a project. Requires GitLab Premium/Ultimate with configurable statuses
-129. `list_custom_field_definitions` - List available custom field definitions for a work item type in a project. Returns field names, types, and IDs needed for setting custom fields via update_work_item
-130. `move_work_item` - Move a work item (issue, task, etc.) to a different project. Uses GitLab GraphQL issueMove mutation
-131. `list_work_item_notes` - List notes and discussions on a work item. Returns threaded discussions with author, body, timestamps, and system/internal flags
-132. `create_work_item_note` - Add a note/comment to a work item. Supports Markdown, internal notes, and threaded replies
-133. `get_timeline_events` - List timeline events for an incident. Returns chronological events with notes, timestamps, and tags
-134. `create_timeline_event` - Create a timeline event on an incident. Supports tags: 'Start time', 'End time', 'Impact detected', 'Response initiated', 'Impact mitigated', 'Cause identified'
-135. `list_webhooks` - List all configured webhooks for a GitLab project or group. Provide either project_id or group_id
-136. `list_webhook_events` - List recent webhook events (past 7 days) for a project or group webhook. Use summary mode for overview, then get_webhook_event for full details
-137. `get_webhook_event` - Get full details of a specific webhook event by ID, including request/response payloads
-138. `search_code` - Search for code across all projects on the GitLab instance (requires advanced search or exact code search to be enabled)
-139. `search_project_code` - Search for code within a specific GitLab project (requires advanced search or exact code search to be enabled)
-140. `search_group_code` - Search for code within a specific GitLab group (requires advanced search or exact code search to be enabled)
-141. `execute_graphql` - Execute a GitLab GraphQL query
+51. `list_todos` - List GitLab to-do items for the current user
+52. `mark_todo_done` - Mark a GitLab to-do item as done
+53. `mark_all_todos_done` - Mark all pending GitLab to-do items as done for the current user
+54. `list_issue_links` - List all issue links for a specific issue
+55. `list_issue_discussions` - List discussions for an issue in a GitLab project
+56. `get_issue_link` - Get a specific issue link
+57. `create_issue_link` - Create an issue link between two issues
+58. `delete_issue_link` - Delete an issue link
+59. `list_namespaces` - List all namespaces available to the current user
+60. `get_namespace` - Get details of a namespace by ID or path
+61. `verify_namespace` - Verify if a namespace path exists
+62. `get_project` - Get details of a specific project
+63. `list_projects` - List projects accessible by the current user
+64. `list_project_members` - List members of a GitLab project
+65. `list_group_projects` - List projects in a GitLab group with filtering options
+66. `list_group_iterations` - List group iterations with filtering options
+67. `list_labels` - List labels for a project
+68. `get_label` - Get a single label from a project
+69. `create_label` - Create a new label in a project
+70. `update_label` - Update an existing label in a project
+71. `delete_label` - Delete a label from a project
+72. `list_pipelines` - List pipelines in a GitLab project with filtering options
+73. `get_pipeline` - Get details of a specific pipeline in a GitLab project
+74. `list_pipeline_jobs` - List all jobs in a specific pipeline
+75. `list_pipeline_trigger_jobs` - List all trigger jobs (bridges) in a specific pipeline that trigger downstream pipelines
+76. `get_pipeline_job` - Get details of a GitLab pipeline job number
+77. `get_pipeline_job_output` - Get the output/trace of a GitLab pipeline job with optional pagination to limit context window usage
+78. `validate_ci_lint` - Validate provided GitLab CI/CD YAML content for a project
+79. `validate_project_ci_lint` - Validate an existing `.gitlab-ci.yml` configuration for a project
+80. `create_pipeline` - Create a new pipeline for a branch or tag
+81. `retry_pipeline` - Retry a failed or canceled pipeline
+82. `cancel_pipeline` - Cancel a running pipeline
+83. `play_pipeline_job` - Run a manual pipeline job
+84. `retry_pipeline_job` - Retry a failed or canceled pipeline job
+85. `cancel_pipeline_job` - Cancel a running pipeline job
+86. `list_deployments` - List deployments in a GitLab project with filtering options
+87. `get_deployment` - Get details of a specific deployment in a GitLab project
+88. `list_environments` - List environments in a GitLab project
+89. `get_environment` - Get details of a specific environment in a GitLab project
+90. `list_job_artifacts` - List artifact files in a job's artifacts archive. Returns file names, paths, types, and sizes
+91. `download_job_artifacts` - Download the entire artifact archive (zip) for a job to a local path. Returns the saved file path
+92. `get_job_artifact_file` - Get the content of a single file from a job's artifacts by its path within the archive
+93. `list_milestones` - List milestones in a GitLab project with filtering options
+94. `get_milestone` - Get details of a specific milestone
+95. `create_milestone` - Create a new milestone in a GitLab project
+96. `edit_milestone` - Edit an existing milestone in a GitLab project
+97. `delete_milestone` - Delete a milestone from a GitLab project
+98. `get_milestone_issue` - Get issues associated with a specific milestone
+99. `get_milestone_merge_requests` - Get merge requests associated with a specific milestone
+100. `promote_milestone` - Promote a milestone to the next stage
+101. `get_milestone_burndown_events` - Get burndown events for a specific milestone
+102. `list_wiki_pages` - List wiki pages in a GitLab project
+103. `get_wiki_page` - Get details of a specific wiki page
+104. `create_wiki_page` - Create a new wiki page in a GitLab project
+105. `update_wiki_page` - Update an existing wiki page in a GitLab project
+106. `delete_wiki_page` - Delete a wiki page from a GitLab project
+107. `list_group_wiki_pages` - List wiki pages in a GitLab group
+108. `get_group_wiki_page` - Get details of a specific group wiki page
+109. `create_group_wiki_page` - Create a new wiki page in a GitLab group
+110. `update_group_wiki_page` - Update an existing wiki page in a GitLab group
+111. `delete_group_wiki_page` - Delete a wiki page from a GitLab group
+112. `get_repository_tree` - Get the repository tree for a GitLab project (list files and directories)
+113. `list_commits` - List repository commits with filtering options
+114. `get_commit` - Get details of a specific commit
+115. `get_commit_diff` - Get changes/diffs of a specific commit
+116. `list_releases` - List all releases for a project
+117. `get_release` - Get a release by tag name
+118. `create_release` - Create a new release in a GitLab project
+119. `update_release` - Update an existing release in a GitLab project
+120. `delete_release` - Delete a release from a GitLab project (does not delete the associated tag)
+121. `create_release_evidence` - Create release evidence for an existing release (GitLab Premium/Ultimate only)
+122. `download_release_asset` - Download a release asset file by direct asset path
+123. `list_tags` - List repository tags with filtering and pagination support
+124. `get_tag` - Get details of a specific repository tag
+125. `create_tag` - Create a new tag in the repository
+126. `delete_tag` - Delete a tag from the repository
+127. `get_tag_signature` - Get the signature of a signed tag
+128. `get_users` - Get GitLab user details by usernames
+129. `list_events` - List all events for the currently authenticated user
+130. `get_project_events` - List all visible events for a specified project
+131. `upload_markdown` - Upload a file to a GitLab project for use in markdown content
+132. `download_attachment` - Download an uploaded file from a GitLab project by secret and filename
+133. `get_work_item` - Get a single work item with full details including status, hierarchy (parent/children), type, labels, assignees, and all widgets
+134. `list_work_items` - List work items in a project with filters (type, state, search, assignees, labels). Returns items with status and hierarchy info
+135. `create_work_item` - Create a new work item (issue, task, incident, test_case, epic, key_result, objective, requirement, ticket). Supports setting title, description, labels, assignees, weight, parent, health status, start/due dates, milestone, and confidentiality
+136. `update_work_item` - Update a work item. Can modify title, description, labels, assignees, weight, state, status, parent hierarchy, children, health status, start/due dates, milestone, confidentiality, linked items, and custom fields
+137. `convert_work_item_type` - Convert a work item to a different type (e.g. issue to task, task to incident)
+138. `list_work_item_statuses` - List available statuses for a work item type in a project. Requires GitLab Premium/Ultimate with configurable statuses
+139. `list_custom_field_definitions` - List available custom field definitions for a work item type in a project. Returns field names, types, and IDs needed for setting custom fields via update_work_item
+140. `move_work_item` - Move a work item (issue, task, etc.) to a different project. Uses GitLab GraphQL issueMove mutation
+141. `list_work_item_notes` - List notes and discussions on a work item. Returns threaded discussions with author, body, timestamps, and system/internal flags
+142. `create_work_item_note` - Add a note/comment to a work item. Supports Markdown, internal notes, and threaded replies
+143. `get_timeline_events` - List timeline events for an incident. Returns chronological events with notes, timestamps, and tags
+144. `create_timeline_event` - Create a timeline event on an incident. Supports tags: 'Start time', 'End time', 'Impact detected', 'Response initiated', 'Impact mitigated', 'Cause identified'
+145. `list_webhooks` - List all configured webhooks for a GitLab project or group. Provide either project_id or group_id
+146. `list_webhook_events` - List recent webhook events (past 7 days) for a project or group webhook. Use summary mode for overview, then get_webhook_event for full details
+147. `get_webhook_event` - Get full details of a specific webhook event by ID, including request/response payloads
+148. `search_code` - Search for code across all projects on the GitLab instance (requires advanced search or exact code search to be enabled)
+149. `search_project_code` - Search for code within a specific GitLab project (requires advanced search or exact code search to be enabled)
+150. `search_group_code` - Search for code within a specific GitLab group (requires advanced search or exact code search to be enabled)
+151. `execute_graphql` - Execute a GitLab GraphQL query
+
 <!-- TOOLS-END -->
 
 </details>

package/README.zh-CN.md

@@ -155,6 +155,21 @@ docker run -i --rm \
 
 适用于支持 MCP OAuth 规范的远程 MCP 客户端（例如 Claude.ai）。服务器会作为完整 OAuth 2.0 授权服务器运行。未认证请求会收到 `401 + WWW-Authenticate` 响应，从而触发客户端侧 OAuth 浏览器流程。
 
+OpenCode、MCPJam、Claude.ai 等远程 MCP 客户端可能会在授权时发送自己的 callback URL。如果你无法在 GitLab 中注册每个客户端 callback URL，请启用 `GITLAB_OAUTH_CALLBACK_PROXY=true`。启用回调代理模式后，GitLab 只需要注册一个 Redirect URI：`{MCP_SERVER_URL}/callback`。
+
+`GITLAB_OAUTH_REDIRECT_URI` 仅用于本地 OAuth（`GITLAB_USE_OAUTH`）。它不会覆盖远程 MCP OAuth 客户端 callback URL，也不应用来修复远程 `Unregistered redirect_uri` 错误。
+
+这个变量存在是因为本地 OAuth 流程会在与 MCP 服务器相同的机器上打开浏览器，并通过本地 HTTP 服务器接收 callback，例如 `http://127.0.0.1:8888/callback`。
+
+远程 MCP OAuth 不同。在 `GITLAB_MCP_OAUTH=true` 模式下，MCP 客户端会在 `/authorize` 请求中提供自己的 callback URL。`GITLAB_OAUTH_REDIRECT_URI` 不会替换这个客户端提供的 URL。
+
+| 模式 | 启用方式 | Callback 变量 | GitLab Redirect URI |
+| --- | --- | --- | --- |
+| 本地 OAuth | `GITLAB_USE_OAUTH=true` | `GITLAB_OAUTH_REDIRECT_URI` | `http://127.0.0.1:8888/callback` 或你的本地 callback |
+| 远程 MCP OAuth | `GITLAB_MCP_OAUTH=true` | `GITLAB_OAUTH_CALLBACK_PROXY=true` | `{MCP_SERVER_URL}/callback` |
+
+只有当 MCP 服务器自己接收本地浏览器 callback 时，才使用 `GITLAB_OAUTH_REDIRECT_URI`。当远程 MCP 客户端拥有 callback URL 时，请使用 `GITLAB_OAUTH_CALLBACK_PROXY=true`。
+
 **工作方式**：将此 MCP 服务器部署到拥有公开 HTTPS URL 的位置。MCP 客户端连接到 `{MCP_SERVER_URL}/mcp`。服务器处理 OAuth 2.0 流程，并代表客户端与 GitLab 交换凭据。
 
 **前置条件：**
@@ -173,6 +188,16 @@ docker run -i --rm \
 | `GITLAB_OAUTH_CALLBACK_PROXY` | 可选 | 设置为 `true` 时使用 MCP 服务器固定的 `/callback` URL |
 | `GITLAB_OAUTH_SCOPES` | 可选 | 逗号分隔的 scope（默认：`api,read_api,read_user`） |
 
+> **排查 `Unregistered redirect_uri`**
+>
+> 检查浏览器 URL 中的 `redirect_uri`。如果它指向客户端 callback，例如 `http://127.0.0.1:xxxxx/.../callback`，请启用：
+>
+> ```env
+> GITLAB_OAUTH_CALLBACK_PROXY=true
+> ```
+>
+> 不要通过修改 `GITLAB_OAUTH_REDIRECT_URI` 来修复远程 MCP OAuth。该变量仅用于本地 OAuth（`GITLAB_USE_OAUTH`）。
+
 ```shell
 docker run -i --rm \
   -e HOST=0.0.0.0 \