GitLab MCP 서버 문제 해결
GitLab v19.6Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
요약
GitLab MCP 서버를 사용할 때 다음과 같은 문제가 발생할 수 있습니다. GitLab MCP 서버를 시작할 때 이 오류가 발생할 수 있습니다. GitLab 19.4 및 이전 버전에서는 같은 문제가 404 Not Found를 대신 반환합니다.
GitLab MCP 서버를 사용할 때 다음과 같은 문제가 발생할 수 있습니다.
오류: 403 Forbidden#
GitLab MCP 서버를 시작할 때 이 오류가 발생할 수 있습니다. OAuth 플로가 완료된 뒤
POST /api/v4/mcp 또는 GET /api/v4/mcp가 403 Forbidden을 반환할 때도
이 오류가 발생할 수 있습니다.
GitLab 19.4 및 이전 버전에서는 같은 문제가 404 Not Found를 대신 반환합니다. 두 상태 코드의
원인은 같습니다.
이 문제를 해결하려면 GitLab MCP 서버 사전 요구 사항을 충족하는지 확인합니다.
원인을 찾으려면 응답 본문의 메시지를 확인합니다. 관리자는 mcp.log 파일에서
denial_reason 필드도 확인할 수 있습니다.
MCP server disabled for this instance(denial_reason:instance_setting_disabled): GitLab Self-Managed에서 관리자가 해당 인스턴스의 MCP 서버를 껐습니다.MCP server not enabled for any of your groups(denial_reason:no_enabled_namespace): GitLab.com에서 사용자가 속한 최상위 그룹 중 MCP 서버가 켜진 그룹이 없습니다. 새로 만든 그룹의 경우 오류:MCP server not enabled for any of your groups를 참고합니다.
404 Project Not Found와 같이 REST 기반 도구 호출에서 반환되는 404 오류는
JSON-RPC 응답 본문에 isError: true와 함께 표시되며, mcp.log에는
tool_status가 not_found로 설정되어 기록됩니다. 그 밖의 도구 호출 실패도 응답
본문에 isError: true와 함께 표시되며, mcp.log에는 발생한 일을 설명하는
tool_status와 함께 기록됩니다.
오류: Server's protocol version is not supported: 2025-06-18#
GitLab 18.6 및 이전 버전에서는 MCP 클라이언트 라이브러리가 GitLab MCP 서버 프로토콜 사양을 지원하지 않을 때 이 오류가 발생할 수 있습니다.
이 문제를 해결하려면 AI 도구 공급자에게 클라이언트 구현을 업데이트하도록 요청합니다.
오류: 429 Too Many Requests#
MCP 클라이언트가 동작을 멈추고 일반적인 HTTP 또는 연결 오류를 보고할 수 있으며, 속도 제한 기간이 초기화될
때까지 모든 요청이 실패합니다. 이는 속도 제한을 초과했을 때 발생합니다. MCP 서버 속도 제한 또는 인증된 API 속도 제한이
해당하며, MCP 서버 요청은 두 제한 모두에 계산되기 때문입니다. GitLab은 요청이 MCP 서버에 도달하기 전에 거부하므로
어떤 도구도 실행되지 않습니다. rate_limited 도구 결과와 달리
오류 결과를 담은 200 OK가 아닙니다.
응답은 콘텐츠 유형이 text/plain인 HTTP 429이며, 기본적으로 본문은 Retry later입니다.
JSON-RPC 메시지가 아니므로 MCP 클라이언트가 MCP 응답으로 읽을 수 없습니다.
원인을 확인하려면 응답 헤더를 확인합니다.
RateLimit-Name은 도달한 제한을 식별합니다. GitLab Self-Managed에서 MCP 서버 제한은throttle_authenticated_mcp입니다. 다른 값은 일반 인증된 API 제한과 같은 다른 제한을 뜻합니다.Retry-After는 다시 시도하기 전에 기다릴 시간(초)입니다. 전체 기간이 아니라 현재 기간에 남은 시간입니다. 클라이언트는 즉시 다시 시도하지 말고 이 값을 따라야 합니다.
응답에는 다른 속도 제한 헤더도 포함됩니다.
제한에 도달하기 전에도 성공한 200 OK 응답에 이미 RateLimit-Remaining이 포함되므로,
헤더를 읽는 클라이언트나 프록시는 제한에 다가가고 있음을 확인할 수 있습니다.
관리자는 로그도 확인할 수 있습니다.
- 거부된 요청은 Workhorse 로그에
status가429이고uri가/api/v4/mcp인 항목으로 나타납니다. 이 항목에는 사용자와 제한 이름이 없습니다. - 거부된 요청은 API에 도달하지 않으므로
api_json.log나mcp.log에 나타나지 않습니다. 일부 다른 GitLab 속도 제한과 달리auth.log에도 나타나지 않습니다. - 계산되었지만 허용된 요청은
rack_request_mcp:authenticated_mcp:allow를 담은rate_limit_state필드와 함께api_json.log에 나타납니다. 이를 사용해 제한을 소비하는 사용자를 파악합니다.
이 문제를 해결하려면 Retry-After에 표시된 초만큼 기다린 다음 다시 시도합니다.
- GitLab.com에서는 요금제별 제한이 MCP 요청에 적용됩니다. 공개된 값은 속도 제한을 참고합니다.
- GitLab Self-Managed에서는 이 제한이 기본적으로 비활성화되어 있습니다. 활성화되어 있다면 관리자가 제한을 높이거나 비활성화할 수 있습니다.
오류: rate_limited 도구 결과#
대신 HTTP 429 Too Many Requests 응답을 받았다면 429 Too Many Requests를 참고합니다.
MCP 서버 자체는 200 OK를 반환했는데도 isError: true가 포함된 도구 결과를 받을 수 있습니다.
이는 도구 호출이 호출하는 기반 GitLab API 엔드포인트의 속도 제한에 걸렸을 때 발생합니다.
예를 들어 검색 도구가 실행될 때 검색 속도 제한에 걸리는 경우입니다.
이 경우 MCP 서버는 429 Too Many Requests를 반환하지 않습니다. 대신 Model Context Protocol 사양을 따릅니다.
이 사양은 API 실패를 결과에 보고되는 도구 실행 오류로 분류하므로 클라이언트나 언어 모델이 이를 읽고
스스로 수정할 수 있습니다.
content 필드에는 사람이 읽을 수 있는 메시지가 들어 있습니다. 예를 들면 다음과 같습니다.
Rate limited by search_rate_limit. Retry after 60 seconds.
structuredContent 필드에는 기계가 읽을 수 있는 재시도 세부 정보가 들어 있습니다.
{
"error": {
"type": "rate_limited",
"retry_after_seconds": 60,
"limit": "search_rate_limit",
"message": "This endpoint has been requested too many times. Try again later."
}
}
이 문제를 해결하려면 기다린 다음 도구 호출을 다시 시도합니다. MCP 클라이언트를 만들 때는
문구가 바뀔 수 있으므로 메시지 텍스트와 비교하지 말고 error.type == "rate_limited"를 확인합니다.
하나의 도구 호출이 둘 이상의 제한을 소비할 수 있으므로 limit을 사용해 어떤 속도 제한에 걸렸는지 식별합니다.
retry_after_seconds는 현재 기간에 남은 시간이 아니라 전체 속도 제한 기간이므로,
정확한 대기 시간이 아니라 안전한 상한으로 취급합니다.
retry_after_seconds와 limit은 GitLab이 호출한 엔드포인트가 제공한 경우에만 존재합니다.
이 필드가 없는 응답도 항상 처리해야 합니다. 관리자가 개별 엔드포인트의 속도 제한을 변경할 수 있으므로
실제 값은 인스턴스마다 다릅니다.
오류: start_duo_session의 403 Forbidden 도구 결과#
start_duo_session 도구를 호출할 때 403 Forbidden이라고 표시되는 오류가 발생할 수 있습니다.
MCP 서버는 200 OK를 반환하며, 도구 결과에는 isError: true가 있고 content 필드에 다음
메시지가 들어 있습니다.
403 Forbidden
이 문제는 프로젝트에서 플로를 실행할 수 없을 때 발생합니다. start_duo_session은 항상
CI job에서 실행되는 세션으로 플로를 시작하며, 프로젝트에서 해당 플로를 실행할 권한이 있어야 합니다.
이 문제를 해결하려면 다음 중 하나를 수행합니다.
- GitLab Duo Agent Platform에 액세스할 수 없다면 GitLab Duo Agent Platform 사전 요구 사항을 충족합니다.
- 프로젝트에서 Reporter 이하 권한이 있다면 프로젝트 Owner 또는 Maintainer에게 최소 Developer 권한을 요청합니다.
- 기본 제공 플로가 꺼져 있다면 프로젝트 Maintainer 또는 Owner, 또는 최상위 그룹 Owner에게 기본 제공 플로를 켜도록 요청합니다.
- 플로가 베타라면 최상위 그룹 Owner에게 베타 및 실험 기능을 켜도록 요청합니다.
GitLab Duo Agent Platform을 사용하지 않는다면 MCP 클라이언트에서 해당 도구를 숨길 수 있습니다.
클라이언트가 사용자 지정 헤더를 지원한다면 duo_agent_platform이 포함되지 않은 목록과 함께
X-Gitlab-Enabled-Mcp-Server-Toolsets 헤더를 보냅니다. 자세한 내용은
도구 그룹(툴셋) 선택을 참고합니다.
Cursor에서 GitLab MCP 서버 문제 해결#
- Cursor에서 Output 뷰를 열려면 다음 중 하나를 수행합니다.
- View > Output으로 이동합니다.
- macOS에서는 Command+Shift+U를 누릅니다.
- Windows 또는 Linux에서는 Control+Shift+U를 누릅니다.
- Output 뷰에서 MCP:SERVERNAME을 선택합니다. 이름은 MCP 구성 값에 따라 달라집니다.
GitLab로 지정한 예에서는MCP: user-GitLab이 됩니다. - 버그를 보고할 때는 출력을 이슈 템플릿의 로그 섹션에 복사합니다.
mcp-remote와 함께 CLI에서 GitLab MCP 서버 문제 해결#
-
Node.js 20 이상 버전을 설치합니다.
-
IDE 및 데스크톱 클라이언트와 완전히 동일한 명령을 테스트하려면 다음을 수행합니다.
- MCP 구성을 추출합니다.
npx명령 문자열을 한 줄로 조합합니다.- 명령 문자열을 실행합니다.
rm -rf ~/.mcp-auth/mcp-remote* npx -y mcp-remote@latest https://gitlab.example.com/api/v4/mcp --static-oauth-client-metadata '{"scope": "mcp"}' -
더 상세한 출력을 기록하려면
--debug파라미터를 추가합니다.rm -rf ~/.mcp-auth/mcp-remote* npx -y mcp-remote@latest https://gitlab.example.com/api/v4/mcp --static-oauth-client-metadata '{"scope": "mcp"}' --debug -
선택 사항.
mcp-remote-client실행 파일을 직접 실행합니다.rm -rf ~/.mcp-auth/mcp-remote* npx -p mcp-remote@latest mcp-remote-client https://gitlab.example.com/api/v4/mcp --static-oauth-client-metadata '{"scope": "mcp"}' -
선택 사항. 특정 버전에서만 발생하는 버그를 만나면
mcp-remote모듈의 버전을 특정 버전으로 고정합니다. 예를 들어mcp-remote@0.1.26을 사용하면 버전이0.1.26으로 고정됩니다.[!note] 보안상의 이유로 가능하면 버전을 고정하지 않는 편이 좋습니다.
Claude Desktop에서 GitLab MCP 서버 문제 해결#
설치된 Node.js 버전을 확인합니다. Claude Desktop은 Node.js 20 이상 버전이 필요합니다.
for n in $(which -a node); do echo "$n" && $n -v; done
MCP 인증 캐시 삭제#
MCP 인증은 로컬에 상당량이 캐시됩니다. 문제를 해결하는 동안 오탐이 발생할 수 있습니다. 이를 방지하려면 문제 해결 중에 캐시 디렉터리를 삭제합니다.
rm -rf ~/.mcp-auth/mcp-remote*
디버깅 및 개발 도구#
MCP Inspector는 MCP 서버를 테스트하고 디버깅하는 대화형 개발자 도구입니다. 이 도구를 실행하려면 명령줄을 사용한 뒤 웹 인터페이스에 접속해 GitLab MCP 서버를 검사합니다.
npx -y @modelcontextprotocol/inspector npx