InfoGrab DocsInfoGrab Docs

GitLab MCP 서버

요약

이 기능에 대한 피드백을 남기려면 이슈 630189에 댓글을 남깁니다. GitLab Model Context Protocol(MCP) 서버를 사용하면 AI 도구와 애플리케이션을 GitLab 인스턴스에 안전하게 연결할 수 있습니다.

히스토리
Warning

이 기능에 대한 피드백을 남기려면 이슈 630189에 댓글을 남깁니다.

GitLab Model Context Protocol(MCP) 서버를 사용하면 AI 도구와 애플리케이션을 GitLab 인스턴스에 안전하게 연결할 수 있습니다. 그러면 Claude Desktop, Claude Code, Cursor 등 MCP 호환 도구의 AI 어시스턴트가 GitLab 데이터에 액세스하고 사용자를 대신하여 작업을 수행할 수 있습니다.

GitLab MCP 서버는 AI 도구가 다음 작업을 수행할 수 있는 표준화된 방법을 제공합니다:

  • GitLab 프로젝트 정보에 액세스합니다.
  • 이슈와 머지 리퀘스트 데이터를 가져옵니다.
  • GitLab API와 안전하게 상호 작용합니다.
  • AI 어시스턴트를 통해 GitLab 고유 작업을 수행합니다.

GitLab MCP 서버는 OAuth 2.0 동적 클라이언트 등록을 지원하며, 이를 통해 AI 도구가 GitLab 인스턴스에 자신을 등록할 수 있습니다. AI 도구가 GitLab MCP 서버에 처음 연결할 때는 다음 과정을 거칩니다:

  1. OAuth 애플리케이션으로 자신을 등록합니다.
  2. GitLab 데이터에 액세스할 인가를 요청합니다.
  3. 안전한 API 액세스를 위한 액세스 토큰을 받습니다.

클릭 데모는 GitLab Duo Agent Platform - GitLab MCP server를 참고합니다.

사전 요구 사항#

인증#

GitLab MCP 서버는 다음 토큰을 허용합니다:

다음 토큰에는 mcp 스코프를 둘 수 없으므로, api 같은 스코프가 있더라도 GitLab MCP 서버가 거부합니다:

  • 레거시 개인 액세스 토큰
  • 프로젝트 액세스 토큰
  • 그룹 액세스 토큰

이 토큰 중 하나를 사용하면 GitLab MCP 서버가 insufficient_scope 오류와 함께 403 Forbidden을 반환합니다. 응답에는 mcp 스코프가 명시되지만, 이 토큰에는 해당 스코프를 추가할 수 없습니다. 이러한 인증 방식에 대한 지원은 이슈 586184에서 제안되었습니다.

GitLab MCP 서버에 클라이언트 연결#

GitLab MCP 서버는 두 가지 전송 유형을 지원합니다:

  • HTTP 전송(권장): 추가 의존성 없이 직접 연결합니다.
  • mcp-remote를 사용한 stdio 전송: 프록시를 통해 연결합니다(Node.js 필요).

주요 AI 도구는 mcpServers 키에 대한 JSON 구성 형식을 지원하며, GitLab MCP 서버 설정을 구성하는 여러 방법을 제공합니다.

서버가 반환하는 도구를 제한하려면 도구 그룹(툴셋) 선택을 참고합니다.

HTTP 전송(권장)#

히스토리

HTTP 전송으로 GitLab MCP 서버를 구성하려면 다음 형식을 사용합니다:

  • <gitlab.example.com>을 다음으로 바꿉니다:
    • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
    • GitLab.com에서는 gitlab.com.
{
  "mcpServers": {
    "GitLab": {
      "type": "http",
      "url": "https://<gitlab.example.com>/api/v4/mcp"
    }
  }
}

X-Gitlab-Mcp-Server-Tool-Name-Prefix HTTP 헤더를 구성하여 도구 이름에 프리픽스를 추가할 수 있습니다. 프리픽스는 다른 MCP 서버나 구성에 있는 여러 GitLab 인스턴스와 도구 이름이 충돌하는 것을 피하는 데 도움이 됩니다.

프리픽스가 32자를 초과하면 처음 32자로 잘립니다.

{
  "mcpServers": {
    "GitLab": {
      "type": "http",
      "url": "https://<gitlab.example.com>/api/v4/mcp",
      "headers": {
        "X-Gitlab-Mcp-Server-Tool-Name-Prefix": "gitlab_"
      }
    }
  }
}

도구 그룹(툴셋) 선택#

GitLab MCP 서버가 반환하는 도구를 특정 그룹으로 제한하려면, X-Gitlab-Enabled-Mcp-Server-Toolsets HTTP 헤더에 쉼표로 구분한 툴셋 이름 목록을 구성합니다. 전체 도구 목록은 도구 참조를 참고합니다.

사용 가능한 툴셋:

툴셋 기본 포함 여부
meta 항상
core 예
merge_requests 예
work_items 예
repository 예
ci 예
duo_agent_platform 예, GitLab Duo Agent Platform을 사용할 수 있는 경우
wikis 아니요(옵트인)
code_security 아니요(옵트인)
orbit 아니요(옵트인)

duo_agent_platform 도구는 사용자가 GitLab Duo Agent Platform을 사용할 수 있을 때만 나열됩니다. 헤더에서 해당 툴셋을 요청하거나 헤더를 all로 설정한 경우에도 마찬가지입니다.

GitLab.com에서는 다음 두 조건을 모두 충족해야 합니다:

  • GitLab Duo Agent Platform을 켠 Premium 또는 Ultimate 요금제의 최상위 그룹에 속해 있거나, GitLab 크레딧을 통해 GitLab Duo Agent Platform을 사용할 수 있습니다.
  • GitLab Duo Agent Platform을 사용할 수 있는 권한이 있습니다(예: 필요한 시트가 있습니다).

GitLab Self-Managed와 GitLab Dedicated에서는 다음 조건을 모두 충족해야 합니다:

  • 인스턴스에서 GitLab Duo가 Always off로 설정되어 있지 않습니다. Off by default이면 GitLab Duo를 켠 그룹이 사용할 수 있도록 도구가 나열됩니다.
  • 인스턴스에 GitLab Duo Agent Platform이 포함된 라이선스가 있거나 GitLab 크레딧이 있습니다.
  • 조직에 GitLab Duo Agent Platform이 켜져 있습니다.
  • GitLab Duo Agent Platform을 사용할 수 있는 권한이 있습니다(예: 필요한 시트가 있습니다).

자세한 내용은 GitLab Duo Agent Platform 사전 요구 사항과 GitLab Duo Agent Platform 켜기 또는 끄기를 참고합니다.

GitLab Duo Agent Platform에 액세스할 수 있으면, GitLab MCP 서버는 클라이언트가 연결할 때 서버 지침도 전송합니다. 이 지침은 AI 도구에 일치하는 GitLab Duo 플로를 제안하고, 플로를 시작하기 전에 사용자에게 확인하도록 안내합니다. 헤더에서 duo_agent_platform 툴셋을 제외한 경우에도 서버는 이 지침을 전송합니다.

code_security 도구는 각 도구의 기반이 되는 기능을 사용자가 사용할 수 있을 때만 나열됩니다. 헤더에서 해당 툴셋을 요청하거나 헤더를 all로 설정한 경우에도 마찬가지입니다.

  • list_vulnerabilities, get_vulnerability, save_vulnerability에는 보안 대시보드가 필요합니다.
  • attach_scan_profile에는 보안 스캔 프로필이 필요합니다.

두 기능 모두 Ultimate 기능입니다. GitLab.com에서는 Ultimate 체험판을 포함해 Ultimate 요금제의 최상위 그룹에 하나 이상 속해 있으면 도구가 나열됩니다. 해당 그룹의 프로젝트에 액세스하는 경우도 포함됩니다. GitLab Self-Managed와 GitLab Dedicated에서는 인스턴스 라이선스에 해당 기능이 포함되어 있으면 도구가 나열됩니다.

orbit 툴셋에는 query_graph처럼 Orbit 명령마다 도구가 하나씩 있습니다. 자세한 내용은 Orbit 도구를 참고합니다. 도구 이름, 설명, 입력 스키마는 Orbit 서버가 설정합니다. Orbit 요구 사항을 충족할 때만 도구가 나열되고 실행됩니다.

Orbit 도구는 orbit 툴셋을 요청하거나 헤더를 all로 설정한 경우에만 나열됩니다. X-Gitlab-Enabled-Mcp-Server-Tools에 Orbit 도구 이름을 지정해도 도구가 나열되지 않습니다.

도구가 나열된다고 해서 액세스 권한이 부여되는 것은 아닙니다. 각 도구는 호출될 때 프로젝트와 네임스페이스 권한을 확인합니다.

옵트인 툴셋을 포함하려면 헤더 값에 명시적으로 추가합니다. 모든 옵트인 툴셋을 포함해 모든 툴셋을 요청하려면 헤더를 all로 설정합니다.

두 헤더를 모두 생략하면 서버는 기본 툴셋을 반환합니다. 툴셋 헤더는 생략하고 X-Gitlab-Enabled-Mcp-Server-Tools만 설정하면, 서버는 기본 툴셋이나 meta 도구 없이 사용자가 지정한 도구만 반환합니다.

X-Gitlab-Enabled-Mcp-Server-Toolsets 헤더의 툴셋 이름은 대소문자를 구분하지 않고 일치시키므로 ci, CI, Ci가 모두 허용됩니다.

헤더에 인식할 수 없는 툴셋 이름이 있으면 400 오류가 반환됩니다.

X-Gitlab-Enabled-Mcp-Server-Tools도 함께 설정하면 서버는 두 목록의 교집합이 아니라 합집합을 반환합니다. 두 헤더를 모두 설정해도 어느 한 헤더만 설정했을 때보다 도구가 줄어드는 일은 없습니다.

{
  "mcpServers": {
    "GitLab": {
      "type": "http",
      "url": "https://<gitlab.example.com>/api/v4/mcp",
      "headers": {
        "X-Gitlab-Enabled-Mcp-Server-Toolsets": "core,work_items"
      }
    }
  }
}

이 헤더를 설정하는 방법은 클라이언트 구성 방식에 따라 다릅니다. 이 페이지에서 사용 중인 클라이언트의 섹션에서 구성 형식을 확인합니다.

  • headers 키를 허용하는 JSON 객체로 구성하는 클라이언트(Cursor와 Kiro 포함): 앞의 예시를 사용합니다.

  • opencode는 최상위 mcp 키와 "type": "remote"를 사용하므로, OpenCode를 GitLab MCP 서버에 연결의 서버 정의에 headers 키를 추가합니다.

  • 명령줄에서 구성하는 Claude Code: --header를 전달합니다.

    claude mcp add -s user --transport http GitLab https://<gitlab.example.com>/api/v4/mcp \
      --header "X-Gitlab-Enabled-Mcp-Server-Toolsets: core,work_items"
    
  • mcp-remote를 통해 연결하는 클라이언트(Claude Desktop과 Zed 포함): --header를 인수로 전달합니다.

    {
      "mcpServers": {
        "GitLab": {
          "command": "npx",
          "args": [
            "-y", "mcp-remote", "https://<gitlab.example.com>/api/v4/mcp",
            "--header", "X-Gitlab-Enabled-Mcp-Server-Toolsets: core,work_items"
          ]
        }
      }
    }
    

    Windows에서는 npx를 호출할 때 args 안의 공백이 이스케이프되지 않아 헤더 값이 손상됩니다. 값을 환경 변수에 넣고 콜론 뒤의 공백을 생략합니다:

    {
      "mcpServers": {
        "GitLab": {
          "command": "npx",
          "args": [
            "-y", "mcp-remote", "https://<gitlab.example.com>/api/v4/mcp",
            "--header", "X-Gitlab-Enabled-Mcp-Server-Toolsets:${GITLAB_TOOLSETS}"
          ],
          "env": {
            "GITLAB_TOOLSETS": "core,work_items"
          }
        }
      }
    }
    

Gemini Code Assist와 Gemini CLI, VS Code의 GitHub Copilot, OpenAI Codex를 포함한 다른 클라이언트는 자체 구성 형식을 사용합니다. 사용자 지정 HTTP 헤더를 보내는 방법은 해당 클라이언트의 문서를 확인합니다.

mcp-remote를 사용한 stdio 전송#

사전 요구 사항:

  • Node.js 20 버전 이상을 설치합니다.

stdio 전송으로 GitLab MCP 서버를 구성하려면 다음 형식을 사용합니다:

  • "command": 매개변수의 경우, npx가 전역이 아니라 로컬에 설치되어 있으면 npx의 전체 경로를 지정합니다.
  • <gitlab.example.com>을 다음으로 바꿉니다:
    • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
    • GitLab.com에서는 gitlab.com.
{
  "mcpServers": {
    "GitLab": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<gitlab.example.com>/api/v4/mcp"
      ]
    }
  }
}

Cursor를 GitLab MCP 서버에 연결#

Cursor는 추가 의존성 없이 직접 연결하기 위해 HTTP 전송을 사용합니다. Cursor에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. Cursor에서 Settings > Cursor Settings > Tools & MCP로 이동합니다.

  2. Installed MCP Servers에서 New MCP Server를 선택합니다.

  3. 열린 mcp.json 파일의 mcpServers 키에 다음 정의를 추가합니다:

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    {
      "mcpServers": {
        "GitLab": {
           "type": "http",
           "url": "https://<gitlab.example.com>/api/v4/mcp"
        }
      }
    }
    
  4. 파일을 저장하고 브라우저가 OAuth 인가 페이지를 열 때까지 기다립니다.

    페이지가 열리지 않으면 Cursor를 닫고 다시 시작합니다.

  5. 브라우저에서 인가 요청을 검토하고 승인합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

Amazon Q Developer를 GitLab MCP 서버에 연결#

Amazon Q Developer는 mcp-remote 프록시를 통한 stdio 전송을 사용합니다. JSON 파일이 아니라 양식에서 서버를 구성합니다.

사전 요구 사항:

  • Node.js 20 버전 이상을 설치합니다.

Amazon Q Developer에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. Amazon Q 패널에서 MCP 서버 설정으로 이동해 서버를 추가합니다.
  2. 양식을 작성합니다:
    • Scope에서는 서버를 어디서나 사용하려면 Global을, 하나의 워크스페이스로 제한하려면 This workspace를 선택합니다.
    • Name에는 gitlab을 입력합니다.
    • Transport에서는 stdio를 선택합니다.
    • Command에는 npx를 입력합니다. npx가 전역이 아니라 로컬에 설치되어 있다면 npx의 전체 경로를 입력합니다.
    • Arguments에는 -y, mcp-remote, https://<gitlab.example.com>/api/v4/mcp의 세 인수를 각각 추가합니다. <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    • Timeout에는 60을 입력합니다.
  3. 구성을 저장합니다.
  4. 브라우저에서 인가 요청을 검토하고 승인합니다.

mcp-remote를 특정 버전에 고정하지 않습니다. 버전 고정은 OAuth 스코프를 요청하는 방식 때문에 쓰던 우회 방법이었고, 이제 서버가 동적 클라이언트 등록 중에 해당 스코프를 기본으로 지정합니다. 버전을 고정한 프록시는 업스트림 수정 사항도 받지 못합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

Claude Code를 GitLab MCP 서버에 연결#

Claude Code는 추가 의존성 없이 직접 연결하기 위해 HTTP 전송을 사용합니다. Claude Code에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. 터미널에서 CLI로 GitLab MCP 서버를 추가합니다:

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    claude mcp add -s user --transport http GitLab https://<gitlab.example.com>/api/v4/mcp
    

    -s user 스코프를 사용하면 모든 프로젝트에서 서버를 사용할 수 있습니다. 이 스코프를 지정하지 않으면 서버가 local 스코프로 추가되어 명령을 실행한 디렉터리에서만 사용할 수 있습니다.

    이미 GitLab MCP 서버를 구성했다면 claude mcp add는 기존 항목을 덮어쓰지 않습니다. 기존 서버를 나열하고 GitLab 항목이 어떤 스코프를 사용하는지 확인합니다:

    claude mcp list
    

    해당 스코프의 기존 항목을 제거한 다음 다시 추가합니다. 이전 버전의 이 안내를 따라 추가한 항목은 -s 플래그를 지정하지 않았으므로 local 스코프이며, local 항목은 이름이 같은 user 항목보다 우선합니다.

    claude mcp remove GitLab -s local
    
  2. Claude Code를 시작합니다:

    claude
    
  3. GitLab MCP 서버에 인증합니다:

    • 채팅에서 /mcp를 입력합니다.
    • 목록에서 GitLab 서버를 선택합니다.
    • 브라우저에서 인가 요청을 검토하고 승인합니다.
  4. 선택 사항. 연결을 확인하려면 /mcp를 다시 입력합니다. GitLab 서버가 연결된 상태로 표시되어야 합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

Claude Desktop을 GitLab MCP 서버에 연결#

사전 요구 사항:

  • Node.js 20 버전 이상을 설치합니다.
  • PATH 환경 변수에서 Node.js를 전역으로 사용할 수 있게 합니다(which -a node).

Claude Desktop에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. Claude Desktop을 엽니다.

  2. 구성 파일을 편집합니다. 다음 중 하나를 수행할 수 있습니다:

    • Claude Desktop에서 Settings > Developer > Edit Config로 이동합니다.
    • macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json 파일을 엽니다.
  3. GitLab MCP 서버에 대한 다음 항목을 추가하고 필요에 맞게 편집합니다:

    • "command": 매개변수의 경우, npx가 전역이 아니라 로컬에 설치되어 있으면 npx의 전체 경로를 지정합니다.
    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 GitLab.com.
    {
      "mcpServers": {
        "GitLab": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://<gitlab.example.com>/api/v4/mcp"
          ]
        }
      }
    }
    
  4. 구성을 저장하고 Claude Desktop을 다시 시작합니다.

  5. 처음 연결할 때 Claude Desktop이 OAuth용 브라우저 창을 엽니다. 요청을 검토하고 승인합니다.

  6. Settings > Developer로 이동하여 새 GitLab MCP 구성을 확인합니다.

  7. Settings > Connectors로 이동하여 연결된 GitLab MCP 서버를 점검합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

Gemini Code Assist와 Gemini CLI를 GitLab MCP 서버에 연결#

Gemini Code Assist와 Gemini CLI는 추가 의존성 없이 직접 연결하기 위해 HTTP 전송을 사용합니다. Gemini Code Assist 또는 Gemini CLI에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. ~/.gemini/settings.json을 편집하여 GitLab MCP 서버를 추가합니다.

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    {
      "mcpServers": {
        "GitLab": {
          "httpUrl": "https://<gitlab.example.com>/api/v4/mcp"
        }
      }
    }
    
  2. Gemini Code Assist 또는 Gemini CLI에서 /mcp auth GitLab 명령을 실행합니다.

    OAuth 인가 페이지가 나타나야 합니다. 나타나지 않으면 Gemini Code Assist 또는 Gemini CLI를 다시 시작합니다.

  3. 브라우저에서 인가 요청을 검토하고 승인합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

VS Code의 GitHub Copilot을 GitLab MCP 서버에 연결#

GitHub Copilot은 추가 의존성 없이 직접 연결하기 위해 HTTP 전송을 사용합니다. VS Code의 GitHub Copilot에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. VS Code에서 Command Palette를 엽니다:

    • macOS에서는 Command+Shift+P를 누릅니다.
    • Windows 또는 Linux에서는 Control+Shift+P를 누릅니다.
  2. MCP: Add Server를 입력하고 Enter를 누릅니다.

  3. 서버 유형으로 HTTP를 선택합니다.

  4. 서버 URL로 https://<gitlab.example.com>/api/v4/mcp를 입력합니다.

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
  5. 서버 ID로 GitLab을 입력합니다.

  6. 구성을 전역으로 저장하거나 vscode/mcp.json 워크스페이스에 저장합니다.

    OAuth 인가 페이지가 나타나야 합니다. 나타나지 않으면 Command Palette를 열고 MCP: List Servers를 검색하여 상태를 확인하거나 서버를 다시 시작합니다.

  7. 브라우저에서 인가 요청을 검토하고 승인합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

Kiro IDE와 CLI를 GitLab MCP 서버에 연결#

Kiro IDE와 CLI는 추가 의존성 없이 직접 연결하기 위해 HTTP 전송을 사용합니다. Kiro IDE 또는 CLI에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. ~/.kiro/settings/mcp.json을 편집하여 GitLab MCP 서버를 추가합니다.

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    {
      "mcpServers": {
        "GitLab": {
          "type": "http",
          "url": "https://<gitlab.example.com>/api/v4/mcp"
        }
      }
    }
    
  2. 구성을 저장합니다.

    OAuth 인가 페이지가 나타나야 합니다. 나타나지 않으면 Kiro CLI를 열고 /mcp 명령을 실행합니다.

  3. 브라우저에서 인가 요청을 검토하고 승인합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

OpenCode를 GitLab MCP 서버에 연결#

OpenCode는 추가 의존성 없이 직접 연결하기 위해 HTTP 전송을 사용합니다. OpenCode에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. ~/.config/opencode/opencode.json 파일의 mcp 키에 다음 정의를 추가합니다:

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    {
      "mcp": {
        "gitlab-mcp": {
          "type": "remote",
          "url": "https://<gitlab.example.com>/api/v4/mcp",
          "enabled": true
        }
      }
    }
    
  2. 파일을 저장합니다.

  3. GitLab MCP 서버에 인증합니다:

    opencode mcp auth gitlab-mcp
    
  4. 브라우저에서 인가 요청을 검토하고 승인합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

OpenAI Codex를 GitLab MCP 서버에 연결#

OpenAI Codex는 추가 의존성 없이 직접 연결하기 위해 HTTP 전송을 사용합니다. OpenAI Codex에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. 터미널에서 CLI로 GitLab MCP 서버를 추가합니다:

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    codex mcp add GitLab --url "https://<gitlab.example.com>/api/v4/mcp"
    
  2. ~/.codex/config.toml을 편집하여 [features] 섹션에서 rmcp_client 기능 플래그를 활성화합니다.

    [features]
    "rmcp_client" = true
    
    [mcp_servers.GitLab]
    url = "https://<gitlab.example.com>/api/v4/mcp"
    
  3. 로그인 플로를 실행하여 GitLab 인스턴스에 인증합니다.

    codex mcp login GitLab
    
  4. 브라우저에서 인가 요청을 검토하고 승인합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

Zed를 GitLab MCP 서버에 연결#

사전 요구 사항:

  • Node.js 20 버전 이상을 설치합니다.
  • PATH 환경 변수에서 Node.js를 전역으로 사용할 수 있게 합니다(which -a node).

Zed에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. Zed에서 Command Palette를 엽니다:

    • macOS에서는 Command+Shift+P를 누릅니다.
    • Windows 또는 Linux에서는 Control+Shift+P를 누릅니다.
  2. agent: open settings를 입력하고 Enter를 누릅니다.

  3. Model Context Protocol (MCP) Servers 섹션에서 Add Server를 선택합니다.

  4. args의 서버 URL로 https://<gitlab.example.com>/api/v4/mcp를 사용합니다.

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    {
      /// The name of your MCP server
      "GitLab": {
        /// The command which runs the MCP server
        "command": "npx",
        /// The arguments to pass to the MCP server
        "args": ["-y","mcp-remote@latest","https://<gitlab.example.com>/api/v4/mcp"],
        /// The environment variables to set
        "env": {}
      }
    }
    
  5. 구성을 저장합니다.

    OAuth 인가 페이지가 나타나야 합니다. 나타나지 않으면 GitLab 토글을 껐다가 다시 켭니다.

  6. 브라우저에서 인가 요청을 검토하고 승인합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

단일 OAuth 애플리케이션 재사용#

히스토리

MCP 클라이언트가 GitLab MCP 서버에 연결하면 OAuth 2.0 동적 클라이언트 등록(Dynamic Client Registration, DCR)을 사용하여 GitLab 인스턴스에 새 OAuth 애플리케이션을 생성합니다.

미리 등록한 단일 OAuth 애플리케이션을 반드시 재사용해야 하는지는 인스턴스에 따라 다릅니다:

  • 관리자가 DCR을 끈 인스턴스에서는 MCP 클라이언트가 애플리케이션을 자동으로 등록할 수 없으므로, 미리 등록한 OAuth 애플리케이션을 재사용해야 합니다. 자세한 내용은 OAuth 동적 클라이언트 등록 끄기를 참고합니다.
  • 그 밖의 모든 인스턴스에서는 미리 등록한 OAuth 애플리케이션 재사용이 선택 사항입니다. DCR의 다음 문제를 피하려면 하나를 재사용합니다:
    • GitLab Self-Managed와 GitLab Dedicated에서는 사용자가 많거나 반복해서 연결하는 클라이언트가 있으면, 인스턴스에 매우 많은 OAuth 애플리케이션이 생성될 수 있습니다.
    • IP 주소별로 DCR 요청에 시간당 10회 등록이라는 속도 제한이 적용됩니다. 회사 네트워크나 VPN처럼 이그레스 IP 주소를 공유하는 사용자는 이 제한을 초과하여 MCP 서버 인증에 실패할 수 있습니다.

그래도 모든 사용자는 OAuth로 각자 인가를 받고 각자의 액세스 토큰을 받습니다. 공유 애플리케이션은 OAuth 클라이언트 신원이며, 공유 자격 증명이 아닙니다.

재사용하는 주체에 따라 다음 범위 중 하나로 OAuth 애플리케이션을 생성합니다:

  • 인스턴스: 인스턴스의 모든 사용자가 공유합니다.
  • 그룹: 그룹의 멤버가 공유합니다.
  • 사용자: 사용자 자신의 계정에 사용합니다.

사전 요구 사항:

  • 다음을 지원하는 MCP 클라이언트:
    • 미리 구성된 OAuth 자격 증명
    • 구성의 clientId 필드
  • 인스턴스용으로 애플리케이션을 생성하는 경우 관리자 액세스 권한이 있어야 합니다.
  • 그룹용으로 애플리케이션을 생성하는 경우 해당 그룹에 Owner 권한이 있어야 합니다.

OAuth 애플리케이션을 생성하려면 다음을 수행합니다:

  1. 다음 중 하나에 대해 OAuth 애플리케이션을 생성합니다: 인스턴스, 그룹 또는 사용자.
  2. 범위로 mcp를 선택하고 Confidential 체크박스를 선택 해제합니다.
  3. 애플리케이션을 저장합니다.
  4. 애플리케이션 ID로 MCP 클라이언트를 구성하거나, 애플리케이션을 재사용하는 사용자에게 애플리케이션 ID를 전달합니다. 애플리케이션 ID가 clientId 입니다. 구성 키는 클라이언트마다 다르지만, 보통 GitLab MCP 서버의 OAuth 구성에서 clientId 또는 client_id라는 이름을 쓰며, 대개 mcp.json 파일에 있습니다.

인스턴스 애플리케이션과 사용자 애플리케이션은 REST API로도 생성할 수 있습니다. 그룹 소유 애플리케이션용 REST API는 없으므로 그룹 UI를 사용해야 합니다.

Note

OAuth 애플리케이션에 등록한 리디렉션 URI는 MCP 클라이언트가 OAuth 플로 중에 보내는 리디렉션 URI와 정확히 일치해야 합니다. 클라이언트가 사용하는 리디렉션 URI는 해당 클라이언트 문서에서 확인합니다. 단일 공유 OAuth 애플리케이션은 서로 다른 리디렉션 URI를 사용하는 MCP 클라이언트를 함께 지원할 수 없습니다. 사용자가 리디렉션 URI가 서로 다른 MCP 클라이언트를 사용한다면, 클라이언트 유형마다 별도의 공유 OAuth 애플리케이션을 생성합니다.

보안 고려 사항#

클라이언트 ID로 인증하는 사용자도 자신의 GitLab 자격 증명으로 OAuth 인가를 완료해야 합니다. 허용된 데이터에만 액세스할 수 있습니다.

GitLab은 어떤 MCP 클라이언트 애플리케이션이 clientId를 제시하는지 검증하지 않습니다. 특정 MCP 클라이언트용으로 OAuth 애플리케이션을 생성하더라도, 사전 등록을 지원하는 다른 MCP 클라이언트가 같은 clientId로 인증할 수 있습니다. clientId는 어떤 OAuth 애플리케이션을 사용하는지를 제어하며, 어떤 클라이언트 소프트웨어가 허용되는지는 제어하지 않습니다.

REST API로 생성한 사전 등록 애플리케이션은 Proof Key for Code Exchange(PKCE)를 강제하지 않습니다. PKCE는 퍼블릭 클라이언트를 대상으로 한 인가 코드 가로채기를 방어합니다.

PKCE를 강제하려면 MCP 클라이언트가 OAuth 플로 중에 code_challenge와 code_challenge_method 매개변수를 보내는지 확인합니다. GitLab은 사전 등록 애플리케이션에 대해 PKCE 매개변수를 허용하지만, 필수로 요구하지는 않습니다.

속도 제한#

히스토리
  • GitLab 19.5에서 rate_limiter_mcp_limits_free_info, rate_limiter_mcp_limits_free_enforce, rate_limiter_mcp_limits_premium_info, rate_limiter_mcp_limits_premium_enforce, rate_limiter_mcp_limits_ultimate_info, rate_limiter_mcp_limits_ultimate_enforce라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 19.6에서 rate_limiter_mcp_sustained_limits_free_info, rate_limiter_mcp_sustained_limits_free_enforce, rate_limiter_mcp_sustained_limits_premium_info, rate_limiter_mcp_sustained_limits_premium_enforce, rate_limiter_mcp_sustained_limits_ultimate_info, rate_limiter_mcp_sustained_limits_ultimate_enforce라는 기능 플래그와 함께 시간당 제한이 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 19.6에서 분당 제한이 일반 공급되었습니다. 기능 플래그 rate_limiter_mcp_limits_free_info, rate_limiter_mcp_limits_free_enforce, rate_limiter_mcp_limits_premium_info, rate_limiter_mcp_limits_premium_enforce, rate_limiter_mcp_limits_ultimate_info, rate_limiter_mcp_limits_ultimate_enforce가 제거되었습니다.
Feature flag

시간당 제한의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 기록을 참고합니다.

MCP 서버 엔드포인트인 POST /api/v4/mcp에 대한 요청은 사용자의 네임스페이스 요금제에 따라 사용자별로 제한됩니다:

요금제 분당 제한 시간당 제한
Free 60 3,600
Premium 600 5,000
Ultimate 600 5,000

이 제한은 클라이언트나 토큰별이 아니라 사용자별로 적용됩니다. 사용자가 여러 MCP 클라이언트를 연결하면 모든 클라이언트가 허용량 하나를 공유합니다.

MCP 서버 요청은 모든 트래픽에 적용되는 GitLab.com 속도 제한에도 포함되므로, 요청은 두 제한 중 어느 쪽에든 도달할 수 있습니다. 모든 요금제에서 MCP 서버 제한이 둘 중 더 낮습니다.

제한을 초과하면 GitLab은 Retry-After와 RateLimit-Reset을 포함한 표준 속도 제한 헤더와 함께 429 Too Many Requests를 반환합니다. RateLimit-Name은 도달한 제한을 식별합니다.

분당 제한 때문에 거부된 요청도 시간당 제한에 포함됩니다. 클라이언트가 429 응답 후 기다리지 않고 재시도하면 시간당 제한에 도달할 수 있으며, 그 제한이 초기화될 때까지 GitLab이 해당 클라이언트의 요청을 거부합니다.

도구의 기반이 되는 GitLab API 엔드포인트의 속도 제한은 다르게 보고됩니다. 이 경우는 rate_limited 도구 결과를 참고합니다.

GitLab Self-Managed와 GitLab Dedicated에서는 관리자가 인스턴스에 단일 MCP 서버 제한을 설정합니다. 자세한 내용은 인증된 MCP 서버 요청 속도 제한을 참고합니다.

지원되는 MCP 프로토콜 버전#

GitLab MCP 서버는 initialize 요청에서 프로토콜 버전을 협상합니다. 클라이언트가 서버에서 지원하지 않는 버전을 요청하면, 서버는 지원되는 버전을 나열한 JSON-RPC 오류를 반환합니다.

프로토콜 버전 지원
2025-11-25 지원됩니다. 클라이언트가 더 새로운 버전을 요청하는 경우에도 서버는 이 버전으로 응답합니다.
2025-06-18 지원됩니다.
2025-03-26 지원됩니다.
2026-07-28 initialize 요청에서만 허용됩니다. 서버는 이 버전의 무상태 기능을 아직 구현하지 않았으므로 2025-11-25로 응답합니다. 진행 상황은 이슈 627825를 참고합니다.

MCP 사양이 프로토콜 버전을 지원 중단해도 GitLab은 그 버전을 계속 지원합니다. 프로토콜 버전 제거는 브레이킹 체인지입니다. GitLab은 버전이 제거되기 전에 지원 중단 및 제거 페이지에서 제거를 안내합니다.

감사 이벤트#

GitLab은 클라이언트가 GitLab MCP 서버에 수행하는 도구 호출마다 AI 감사 이벤트를 기록할 수 있습니다. 자세한 내용은 GitLab MCP 서버의 감사 이벤트를 참고합니다.

관련 주제#

GitLab MCP 서버

GitLab v19.6
Tier: Free, Premium, Ultimate
Offering: GitLab.com
원문 보기

요약

이 기능에 대한 피드백을 남기려면 이슈 630189에 댓글을 남깁니다. GitLab Model Context Protocol(MCP) 서버를 사용하면 AI 도구와 애플리케이션을 GitLab 인스턴스에 안전하게 연결할 수 있습니다.

히스토리
Warning

이 기능에 대한 피드백을 남기려면 이슈 630189에 댓글을 남깁니다.

GitLab Model Context Protocol(MCP) 서버를 사용하면 AI 도구와 애플리케이션을 GitLab 인스턴스에 안전하게 연결할 수 있습니다. 그러면 Claude Desktop, Claude Code, Cursor 등 MCP 호환 도구의 AI 어시스턴트가 GitLab 데이터에 액세스하고 사용자를 대신하여 작업을 수행할 수 있습니다.

GitLab MCP 서버는 AI 도구가 다음 작업을 수행할 수 있는 표준화된 방법을 제공합니다:

  • GitLab 프로젝트 정보에 액세스합니다.
  • 이슈와 머지 리퀘스트 데이터를 가져옵니다.
  • GitLab API와 안전하게 상호 작용합니다.
  • AI 어시스턴트를 통해 GitLab 고유 작업을 수행합니다.

GitLab MCP 서버는 OAuth 2.0 동적 클라이언트 등록을 지원하며, 이를 통해 AI 도구가 GitLab 인스턴스에 자신을 등록할 수 있습니다. AI 도구가 GitLab MCP 서버에 처음 연결할 때는 다음 과정을 거칩니다:

  1. OAuth 애플리케이션으로 자신을 등록합니다.
  2. GitLab 데이터에 액세스할 인가를 요청합니다.
  3. 안전한 API 액세스를 위한 액세스 토큰을 받습니다.

클릭 데모는 GitLab Duo Agent Platform - GitLab MCP server를 참고합니다.

사전 요구 사항#

인증#

GitLab MCP 서버는 다음 토큰을 허용합니다:

다음 토큰에는 mcp 스코프를 둘 수 없으므로, api 같은 스코프가 있더라도 GitLab MCP 서버가 거부합니다:

  • 레거시 개인 액세스 토큰
  • 프로젝트 액세스 토큰
  • 그룹 액세스 토큰

이 토큰 중 하나를 사용하면 GitLab MCP 서버가 insufficient_scope 오류와 함께 403 Forbidden을 반환합니다. 응답에는 mcp 스코프가 명시되지만, 이 토큰에는 해당 스코프를 추가할 수 없습니다. 이러한 인증 방식에 대한 지원은 이슈 586184에서 제안되었습니다.

GitLab MCP 서버에 클라이언트 연결#

GitLab MCP 서버는 두 가지 전송 유형을 지원합니다:

  • HTTP 전송(권장): 추가 의존성 없이 직접 연결합니다.
  • mcp-remote를 사용한 stdio 전송: 프록시를 통해 연결합니다(Node.js 필요).

주요 AI 도구는 mcpServers 키에 대한 JSON 구성 형식을 지원하며, GitLab MCP 서버 설정을 구성하는 여러 방법을 제공합니다.

서버가 반환하는 도구를 제한하려면 도구 그룹(툴셋) 선택을 참고합니다.

HTTP 전송(권장)#

히스토리

HTTP 전송으로 GitLab MCP 서버를 구성하려면 다음 형식을 사용합니다:

  • <gitlab.example.com>을 다음으로 바꿉니다:
    • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
    • GitLab.com에서는 gitlab.com.
{
  "mcpServers": {
    "GitLab": {
      "type": "http",
      "url": "https://<gitlab.example.com>/api/v4/mcp"
    }
  }
}

X-Gitlab-Mcp-Server-Tool-Name-Prefix HTTP 헤더를 구성하여 도구 이름에 프리픽스를 추가할 수 있습니다. 프리픽스는 다른 MCP 서버나 구성에 있는 여러 GitLab 인스턴스와 도구 이름이 충돌하는 것을 피하는 데 도움이 됩니다.

프리픽스가 32자를 초과하면 처음 32자로 잘립니다.

{
  "mcpServers": {
    "GitLab": {
      "type": "http",
      "url": "https://<gitlab.example.com>/api/v4/mcp",
      "headers": {
        "X-Gitlab-Mcp-Server-Tool-Name-Prefix": "gitlab_"
      }
    }
  }
}

도구 그룹(툴셋) 선택#

GitLab MCP 서버가 반환하는 도구를 특정 그룹으로 제한하려면, X-Gitlab-Enabled-Mcp-Server-Toolsets HTTP 헤더에 쉼표로 구분한 툴셋 이름 목록을 구성합니다. 전체 도구 목록은 도구 참조를 참고합니다.

사용 가능한 툴셋:

툴셋 기본 포함 여부
meta 항상
core 예
merge_requests 예
work_items 예
repository 예
ci 예
duo_agent_platform 예, GitLab Duo Agent Platform을 사용할 수 있는 경우
wikis 아니요(옵트인)
code_security 아니요(옵트인)
orbit 아니요(옵트인)

duo_agent_platform 도구는 사용자가 GitLab Duo Agent Platform을 사용할 수 있을 때만 나열됩니다. 헤더에서 해당 툴셋을 요청하거나 헤더를 all로 설정한 경우에도 마찬가지입니다.

GitLab.com에서는 다음 두 조건을 모두 충족해야 합니다:

  • GitLab Duo Agent Platform을 켠 Premium 또는 Ultimate 요금제의 최상위 그룹에 속해 있거나, GitLab 크레딧을 통해 GitLab Duo Agent Platform을 사용할 수 있습니다.
  • GitLab Duo Agent Platform을 사용할 수 있는 권한이 있습니다(예: 필요한 시트가 있습니다).

GitLab Self-Managed와 GitLab Dedicated에서는 다음 조건을 모두 충족해야 합니다:

  • 인스턴스에서 GitLab Duo가 Always off로 설정되어 있지 않습니다. Off by default이면 GitLab Duo를 켠 그룹이 사용할 수 있도록 도구가 나열됩니다.
  • 인스턴스에 GitLab Duo Agent Platform이 포함된 라이선스가 있거나 GitLab 크레딧이 있습니다.
  • 조직에 GitLab Duo Agent Platform이 켜져 있습니다.
  • GitLab Duo Agent Platform을 사용할 수 있는 권한이 있습니다(예: 필요한 시트가 있습니다).

자세한 내용은 GitLab Duo Agent Platform 사전 요구 사항과 GitLab Duo Agent Platform 켜기 또는 끄기를 참고합니다.

GitLab Duo Agent Platform에 액세스할 수 있으면, GitLab MCP 서버는 클라이언트가 연결할 때 서버 지침도 전송합니다. 이 지침은 AI 도구에 일치하는 GitLab Duo 플로를 제안하고, 플로를 시작하기 전에 사용자에게 확인하도록 안내합니다. 헤더에서 duo_agent_platform 툴셋을 제외한 경우에도 서버는 이 지침을 전송합니다.

code_security 도구는 각 도구의 기반이 되는 기능을 사용자가 사용할 수 있을 때만 나열됩니다. 헤더에서 해당 툴셋을 요청하거나 헤더를 all로 설정한 경우에도 마찬가지입니다.

  • list_vulnerabilities, get_vulnerability, save_vulnerability에는 보안 대시보드가 필요합니다.
  • attach_scan_profile에는 보안 스캔 프로필이 필요합니다.

두 기능 모두 Ultimate 기능입니다. GitLab.com에서는 Ultimate 체험판을 포함해 Ultimate 요금제의 최상위 그룹에 하나 이상 속해 있으면 도구가 나열됩니다. 해당 그룹의 프로젝트에 액세스하는 경우도 포함됩니다. GitLab Self-Managed와 GitLab Dedicated에서는 인스턴스 라이선스에 해당 기능이 포함되어 있으면 도구가 나열됩니다.

orbit 툴셋에는 query_graph처럼 Orbit 명령마다 도구가 하나씩 있습니다. 자세한 내용은 Orbit 도구를 참고합니다. 도구 이름, 설명, 입력 스키마는 Orbit 서버가 설정합니다. Orbit 요구 사항을 충족할 때만 도구가 나열되고 실행됩니다.

Orbit 도구는 orbit 툴셋을 요청하거나 헤더를 all로 설정한 경우에만 나열됩니다. X-Gitlab-Enabled-Mcp-Server-Tools에 Orbit 도구 이름을 지정해도 도구가 나열되지 않습니다.

도구가 나열된다고 해서 액세스 권한이 부여되는 것은 아닙니다. 각 도구는 호출될 때 프로젝트와 네임스페이스 권한을 확인합니다.

옵트인 툴셋을 포함하려면 헤더 값에 명시적으로 추가합니다. 모든 옵트인 툴셋을 포함해 모든 툴셋을 요청하려면 헤더를 all로 설정합니다.

두 헤더를 모두 생략하면 서버는 기본 툴셋을 반환합니다. 툴셋 헤더는 생략하고 X-Gitlab-Enabled-Mcp-Server-Tools만 설정하면, 서버는 기본 툴셋이나 meta 도구 없이 사용자가 지정한 도구만 반환합니다.

X-Gitlab-Enabled-Mcp-Server-Toolsets 헤더의 툴셋 이름은 대소문자를 구분하지 않고 일치시키므로 ci, CI, Ci가 모두 허용됩니다.

헤더에 인식할 수 없는 툴셋 이름이 있으면 400 오류가 반환됩니다.

X-Gitlab-Enabled-Mcp-Server-Tools도 함께 설정하면 서버는 두 목록의 교집합이 아니라 합집합을 반환합니다. 두 헤더를 모두 설정해도 어느 한 헤더만 설정했을 때보다 도구가 줄어드는 일은 없습니다.

{
  "mcpServers": {
    "GitLab": {
      "type": "http",
      "url": "https://<gitlab.example.com>/api/v4/mcp",
      "headers": {
        "X-Gitlab-Enabled-Mcp-Server-Toolsets": "core,work_items"
      }
    }
  }
}

이 헤더를 설정하는 방법은 클라이언트 구성 방식에 따라 다릅니다. 이 페이지에서 사용 중인 클라이언트의 섹션에서 구성 형식을 확인합니다.

  • headers 키를 허용하는 JSON 객체로 구성하는 클라이언트(Cursor와 Kiro 포함): 앞의 예시를 사용합니다.

  • opencode는 최상위 mcp 키와 "type": "remote"를 사용하므로, OpenCode를 GitLab MCP 서버에 연결의 서버 정의에 headers 키를 추가합니다.

  • 명령줄에서 구성하는 Claude Code: --header를 전달합니다.

    claude mcp add -s user --transport http GitLab https://<gitlab.example.com>/api/v4/mcp \
      --header "X-Gitlab-Enabled-Mcp-Server-Toolsets: core,work_items"
    
  • mcp-remote를 통해 연결하는 클라이언트(Claude Desktop과 Zed 포함): --header를 인수로 전달합니다.

    {
      "mcpServers": {
        "GitLab": {
          "command": "npx",
          "args": [
            "-y", "mcp-remote", "https://<gitlab.example.com>/api/v4/mcp",
            "--header", "X-Gitlab-Enabled-Mcp-Server-Toolsets: core,work_items"
          ]
        }
      }
    }
    

    Windows에서는 npx를 호출할 때 args 안의 공백이 이스케이프되지 않아 헤더 값이 손상됩니다. 값을 환경 변수에 넣고 콜론 뒤의 공백을 생략합니다:

    {
      "mcpServers": {
        "GitLab": {
          "command": "npx",
          "args": [
            "-y", "mcp-remote", "https://<gitlab.example.com>/api/v4/mcp",
            "--header", "X-Gitlab-Enabled-Mcp-Server-Toolsets:${GITLAB_TOOLSETS}"
          ],
          "env": {
            "GITLAB_TOOLSETS": "core,work_items"
          }
        }
      }
    }
    

Gemini Code Assist와 Gemini CLI, VS Code의 GitHub Copilot, OpenAI Codex를 포함한 다른 클라이언트는 자체 구성 형식을 사용합니다. 사용자 지정 HTTP 헤더를 보내는 방법은 해당 클라이언트의 문서를 확인합니다.

mcp-remote를 사용한 stdio 전송#

사전 요구 사항:

  • Node.js 20 버전 이상을 설치합니다.

stdio 전송으로 GitLab MCP 서버를 구성하려면 다음 형식을 사용합니다:

  • "command": 매개변수의 경우, npx가 전역이 아니라 로컬에 설치되어 있으면 npx의 전체 경로를 지정합니다.
  • <gitlab.example.com>을 다음으로 바꿉니다:
    • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
    • GitLab.com에서는 gitlab.com.
{
  "mcpServers": {
    "GitLab": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<gitlab.example.com>/api/v4/mcp"
      ]
    }
  }
}

Cursor를 GitLab MCP 서버에 연결#

Cursor는 추가 의존성 없이 직접 연결하기 위해 HTTP 전송을 사용합니다. Cursor에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. Cursor에서 Settings > Cursor Settings > Tools & MCP로 이동합니다.

  2. Installed MCP Servers에서 New MCP Server를 선택합니다.

  3. 열린 mcp.json 파일의 mcpServers 키에 다음 정의를 추가합니다:

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    {
      "mcpServers": {
        "GitLab": {
           "type": "http",
           "url": "https://<gitlab.example.com>/api/v4/mcp"
        }
      }
    }
    
  4. 파일을 저장하고 브라우저가 OAuth 인가 페이지를 열 때까지 기다립니다.

    페이지가 열리지 않으면 Cursor를 닫고 다시 시작합니다.

  5. 브라우저에서 인가 요청을 검토하고 승인합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

Amazon Q Developer를 GitLab MCP 서버에 연결#

Amazon Q Developer는 mcp-remote 프록시를 통한 stdio 전송을 사용합니다. JSON 파일이 아니라 양식에서 서버를 구성합니다.

사전 요구 사항:

  • Node.js 20 버전 이상을 설치합니다.

Amazon Q Developer에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. Amazon Q 패널에서 MCP 서버 설정으로 이동해 서버를 추가합니다.
  2. 양식을 작성합니다:
    • Scope에서는 서버를 어디서나 사용하려면 Global을, 하나의 워크스페이스로 제한하려면 This workspace를 선택합니다.
    • Name에는 gitlab을 입력합니다.
    • Transport에서는 stdio를 선택합니다.
    • Command에는 npx를 입력합니다. npx가 전역이 아니라 로컬에 설치되어 있다면 npx의 전체 경로를 입력합니다.
    • Arguments에는 -y, mcp-remote, https://<gitlab.example.com>/api/v4/mcp의 세 인수를 각각 추가합니다. <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    • Timeout에는 60을 입력합니다.
  3. 구성을 저장합니다.
  4. 브라우저에서 인가 요청을 검토하고 승인합니다.

mcp-remote를 특정 버전에 고정하지 않습니다. 버전 고정은 OAuth 스코프를 요청하는 방식 때문에 쓰던 우회 방법이었고, 이제 서버가 동적 클라이언트 등록 중에 해당 스코프를 기본으로 지정합니다. 버전을 고정한 프록시는 업스트림 수정 사항도 받지 못합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

Claude Code를 GitLab MCP 서버에 연결#

Claude Code는 추가 의존성 없이 직접 연결하기 위해 HTTP 전송을 사용합니다. Claude Code에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. 터미널에서 CLI로 GitLab MCP 서버를 추가합니다:

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    claude mcp add -s user --transport http GitLab https://<gitlab.example.com>/api/v4/mcp
    

    -s user 스코프를 사용하면 모든 프로젝트에서 서버를 사용할 수 있습니다. 이 스코프를 지정하지 않으면 서버가 local 스코프로 추가되어 명령을 실행한 디렉터리에서만 사용할 수 있습니다.

    이미 GitLab MCP 서버를 구성했다면 claude mcp add는 기존 항목을 덮어쓰지 않습니다. 기존 서버를 나열하고 GitLab 항목이 어떤 스코프를 사용하는지 확인합니다:

    claude mcp list
    

    해당 스코프의 기존 항목을 제거한 다음 다시 추가합니다. 이전 버전의 이 안내를 따라 추가한 항목은 -s 플래그를 지정하지 않았으므로 local 스코프이며, local 항목은 이름이 같은 user 항목보다 우선합니다.

    claude mcp remove GitLab -s local
    
  2. Claude Code를 시작합니다:

    claude
    
  3. GitLab MCP 서버에 인증합니다:

    • 채팅에서 /mcp를 입력합니다.
    • 목록에서 GitLab 서버를 선택합니다.
    • 브라우저에서 인가 요청을 검토하고 승인합니다.
  4. 선택 사항. 연결을 확인하려면 /mcp를 다시 입력합니다. GitLab 서버가 연결된 상태로 표시되어야 합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

Claude Desktop을 GitLab MCP 서버에 연결#

사전 요구 사항:

  • Node.js 20 버전 이상을 설치합니다.
  • PATH 환경 변수에서 Node.js를 전역으로 사용할 수 있게 합니다(which -a node).

Claude Desktop에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. Claude Desktop을 엽니다.

  2. 구성 파일을 편집합니다. 다음 중 하나를 수행할 수 있습니다:

    • Claude Desktop에서 Settings > Developer > Edit Config로 이동합니다.
    • macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json 파일을 엽니다.
  3. GitLab MCP 서버에 대한 다음 항목을 추가하고 필요에 맞게 편집합니다:

    • "command": 매개변수의 경우, npx가 전역이 아니라 로컬에 설치되어 있으면 npx의 전체 경로를 지정합니다.
    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 GitLab.com.
    {
      "mcpServers": {
        "GitLab": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://<gitlab.example.com>/api/v4/mcp"
          ]
        }
      }
    }
    
  4. 구성을 저장하고 Claude Desktop을 다시 시작합니다.

  5. 처음 연결할 때 Claude Desktop이 OAuth용 브라우저 창을 엽니다. 요청을 검토하고 승인합니다.

  6. Settings > Developer로 이동하여 새 GitLab MCP 구성을 확인합니다.

  7. Settings > Connectors로 이동하여 연결된 GitLab MCP 서버를 점검합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

Gemini Code Assist와 Gemini CLI를 GitLab MCP 서버에 연결#

Gemini Code Assist와 Gemini CLI는 추가 의존성 없이 직접 연결하기 위해 HTTP 전송을 사용합니다. Gemini Code Assist 또는 Gemini CLI에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. ~/.gemini/settings.json을 편집하여 GitLab MCP 서버를 추가합니다.

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    {
      "mcpServers": {
        "GitLab": {
          "httpUrl": "https://<gitlab.example.com>/api/v4/mcp"
        }
      }
    }
    
  2. Gemini Code Assist 또는 Gemini CLI에서 /mcp auth GitLab 명령을 실행합니다.

    OAuth 인가 페이지가 나타나야 합니다. 나타나지 않으면 Gemini Code Assist 또는 Gemini CLI를 다시 시작합니다.

  3. 브라우저에서 인가 요청을 검토하고 승인합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

VS Code의 GitHub Copilot을 GitLab MCP 서버에 연결#

GitHub Copilot은 추가 의존성 없이 직접 연결하기 위해 HTTP 전송을 사용합니다. VS Code의 GitHub Copilot에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. VS Code에서 Command Palette를 엽니다:

    • macOS에서는 Command+Shift+P를 누릅니다.
    • Windows 또는 Linux에서는 Control+Shift+P를 누릅니다.
  2. MCP: Add Server를 입력하고 Enter를 누릅니다.

  3. 서버 유형으로 HTTP를 선택합니다.

  4. 서버 URL로 https://<gitlab.example.com>/api/v4/mcp를 입력합니다.

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
  5. 서버 ID로 GitLab을 입력합니다.

  6. 구성을 전역으로 저장하거나 vscode/mcp.json 워크스페이스에 저장합니다.

    OAuth 인가 페이지가 나타나야 합니다. 나타나지 않으면 Command Palette를 열고 MCP: List Servers를 검색하여 상태를 확인하거나 서버를 다시 시작합니다.

  7. 브라우저에서 인가 요청을 검토하고 승인합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

Kiro IDE와 CLI를 GitLab MCP 서버에 연결#

Kiro IDE와 CLI는 추가 의존성 없이 직접 연결하기 위해 HTTP 전송을 사용합니다. Kiro IDE 또는 CLI에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. ~/.kiro/settings/mcp.json을 편집하여 GitLab MCP 서버를 추가합니다.

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    {
      "mcpServers": {
        "GitLab": {
          "type": "http",
          "url": "https://<gitlab.example.com>/api/v4/mcp"
        }
      }
    }
    
  2. 구성을 저장합니다.

    OAuth 인가 페이지가 나타나야 합니다. 나타나지 않으면 Kiro CLI를 열고 /mcp 명령을 실행합니다.

  3. 브라우저에서 인가 요청을 검토하고 승인합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

OpenCode를 GitLab MCP 서버에 연결#

OpenCode는 추가 의존성 없이 직접 연결하기 위해 HTTP 전송을 사용합니다. OpenCode에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. ~/.config/opencode/opencode.json 파일의 mcp 키에 다음 정의를 추가합니다:

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    {
      "mcp": {
        "gitlab-mcp": {
          "type": "remote",
          "url": "https://<gitlab.example.com>/api/v4/mcp",
          "enabled": true
        }
      }
    }
    
  2. 파일을 저장합니다.

  3. GitLab MCP 서버에 인증합니다:

    opencode mcp auth gitlab-mcp
    
  4. 브라우저에서 인가 요청을 검토하고 승인합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

OpenAI Codex를 GitLab MCP 서버에 연결#

OpenAI Codex는 추가 의존성 없이 직접 연결하기 위해 HTTP 전송을 사용합니다. OpenAI Codex에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. 터미널에서 CLI로 GitLab MCP 서버를 추가합니다:

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    codex mcp add GitLab --url "https://<gitlab.example.com>/api/v4/mcp"
    
  2. ~/.codex/config.toml을 편집하여 [features] 섹션에서 rmcp_client 기능 플래그를 활성화합니다.

    [features]
    "rmcp_client" = true
    
    [mcp_servers.GitLab]
    url = "https://<gitlab.example.com>/api/v4/mcp"
    
  3. 로그인 플로를 실행하여 GitLab 인스턴스에 인증합니다.

    codex mcp login GitLab
    
  4. 브라우저에서 인가 요청을 검토하고 승인합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

Zed를 GitLab MCP 서버에 연결#

사전 요구 사항:

  • Node.js 20 버전 이상을 설치합니다.
  • PATH 환경 변수에서 Node.js를 전역으로 사용할 수 있게 합니다(which -a node).

Zed에서 GitLab MCP 서버를 구성하려면 다음을 수행합니다:

  1. Zed에서 Command Palette를 엽니다:

    • macOS에서는 Command+Shift+P를 누릅니다.
    • Windows 또는 Linux에서는 Control+Shift+P를 누릅니다.
  2. agent: open settings를 입력하고 Enter를 누릅니다.

  3. Model Context Protocol (MCP) Servers 섹션에서 Add Server를 선택합니다.

  4. args의 서버 URL로 https://<gitlab.example.com>/api/v4/mcp를 사용합니다.

    • <gitlab.example.com>을 다음으로 바꿉니다:
      • GitLab Self-Managed에서는 GitLab 인스턴스 URL.
      • GitLab.com에서는 gitlab.com.
    {
      /// The name of your MCP server
      "GitLab": {
        /// The command which runs the MCP server
        "command": "npx",
        /// The arguments to pass to the MCP server
        "args": ["-y","mcp-remote@latest","https://<gitlab.example.com>/api/v4/mcp"],
        /// The environment variables to set
        "env": {}
      }
    }
    
  5. 구성을 저장합니다.

    OAuth 인가 페이지가 나타나야 합니다. 나타나지 않으면 GitLab 토글을 껐다가 다시 켭니다.

  6. 브라우저에서 인가 요청을 검토하고 승인합니다.

이제 새 채팅을 시작해 사용 가능한 도구에 따라 질문할 수 있습니다.

Warning

이 도구를 사용할 때 프롬프트 인젝션을 방어할 책임은 사용자에게 있습니다. 각별히 주의하거나, 신뢰하는 GitLab 객체에만 MCP 도구를 사용합니다.

단일 OAuth 애플리케이션 재사용#

히스토리

MCP 클라이언트가 GitLab MCP 서버에 연결하면 OAuth 2.0 동적 클라이언트 등록(Dynamic Client Registration, DCR)을 사용하여 GitLab 인스턴스에 새 OAuth 애플리케이션을 생성합니다.

미리 등록한 단일 OAuth 애플리케이션을 반드시 재사용해야 하는지는 인스턴스에 따라 다릅니다:

  • 관리자가 DCR을 끈 인스턴스에서는 MCP 클라이언트가 애플리케이션을 자동으로 등록할 수 없으므로, 미리 등록한 OAuth 애플리케이션을 재사용해야 합니다. 자세한 내용은 OAuth 동적 클라이언트 등록 끄기를 참고합니다.
  • 그 밖의 모든 인스턴스에서는 미리 등록한 OAuth 애플리케이션 재사용이 선택 사항입니다. DCR의 다음 문제를 피하려면 하나를 재사용합니다:
    • GitLab Self-Managed와 GitLab Dedicated에서는 사용자가 많거나 반복해서 연결하는 클라이언트가 있으면, 인스턴스에 매우 많은 OAuth 애플리케이션이 생성될 수 있습니다.
    • IP 주소별로 DCR 요청에 시간당 10회 등록이라는 속도 제한이 적용됩니다. 회사 네트워크나 VPN처럼 이그레스 IP 주소를 공유하는 사용자는 이 제한을 초과하여 MCP 서버 인증에 실패할 수 있습니다.

그래도 모든 사용자는 OAuth로 각자 인가를 받고 각자의 액세스 토큰을 받습니다. 공유 애플리케이션은 OAuth 클라이언트 신원이며, 공유 자격 증명이 아닙니다.

재사용하는 주체에 따라 다음 범위 중 하나로 OAuth 애플리케이션을 생성합니다:

  • 인스턴스: 인스턴스의 모든 사용자가 공유합니다.
  • 그룹: 그룹의 멤버가 공유합니다.
  • 사용자: 사용자 자신의 계정에 사용합니다.

사전 요구 사항:

  • 다음을 지원하는 MCP 클라이언트:
    • 미리 구성된 OAuth 자격 증명
    • 구성의 clientId 필드
  • 인스턴스용으로 애플리케이션을 생성하는 경우 관리자 액세스 권한이 있어야 합니다.
  • 그룹용으로 애플리케이션을 생성하는 경우 해당 그룹에 Owner 권한이 있어야 합니다.

OAuth 애플리케이션을 생성하려면 다음을 수행합니다:

  1. 다음 중 하나에 대해 OAuth 애플리케이션을 생성합니다: 인스턴스, 그룹 또는 사용자.
  2. 범위로 mcp를 선택하고 Confidential 체크박스를 선택 해제합니다.
  3. 애플리케이션을 저장합니다.
  4. 애플리케이션 ID로 MCP 클라이언트를 구성하거나, 애플리케이션을 재사용하는 사용자에게 애플리케이션 ID를 전달합니다. 애플리케이션 ID가 clientId 입니다. 구성 키는 클라이언트마다 다르지만, 보통 GitLab MCP 서버의 OAuth 구성에서 clientId 또는 client_id라는 이름을 쓰며, 대개 mcp.json 파일에 있습니다.

인스턴스 애플리케이션과 사용자 애플리케이션은 REST API로도 생성할 수 있습니다. 그룹 소유 애플리케이션용 REST API는 없으므로 그룹 UI를 사용해야 합니다.

Note

OAuth 애플리케이션에 등록한 리디렉션 URI는 MCP 클라이언트가 OAuth 플로 중에 보내는 리디렉션 URI와 정확히 일치해야 합니다. 클라이언트가 사용하는 리디렉션 URI는 해당 클라이언트 문서에서 확인합니다. 단일 공유 OAuth 애플리케이션은 서로 다른 리디렉션 URI를 사용하는 MCP 클라이언트를 함께 지원할 수 없습니다. 사용자가 리디렉션 URI가 서로 다른 MCP 클라이언트를 사용한다면, 클라이언트 유형마다 별도의 공유 OAuth 애플리케이션을 생성합니다.

보안 고려 사항#

클라이언트 ID로 인증하는 사용자도 자신의 GitLab 자격 증명으로 OAuth 인가를 완료해야 합니다. 허용된 데이터에만 액세스할 수 있습니다.

GitLab은 어떤 MCP 클라이언트 애플리케이션이 clientId를 제시하는지 검증하지 않습니다. 특정 MCP 클라이언트용으로 OAuth 애플리케이션을 생성하더라도, 사전 등록을 지원하는 다른 MCP 클라이언트가 같은 clientId로 인증할 수 있습니다. clientId는 어떤 OAuth 애플리케이션을 사용하는지를 제어하며, 어떤 클라이언트 소프트웨어가 허용되는지는 제어하지 않습니다.

REST API로 생성한 사전 등록 애플리케이션은 Proof Key for Code Exchange(PKCE)를 강제하지 않습니다. PKCE는 퍼블릭 클라이언트를 대상으로 한 인가 코드 가로채기를 방어합니다.

PKCE를 강제하려면 MCP 클라이언트가 OAuth 플로 중에 code_challenge와 code_challenge_method 매개변수를 보내는지 확인합니다. GitLab은 사전 등록 애플리케이션에 대해 PKCE 매개변수를 허용하지만, 필수로 요구하지는 않습니다.

속도 제한#

히스토리
  • GitLab 19.5에서 rate_limiter_mcp_limits_free_info, rate_limiter_mcp_limits_free_enforce, rate_limiter_mcp_limits_premium_info, rate_limiter_mcp_limits_premium_enforce, rate_limiter_mcp_limits_ultimate_info, rate_limiter_mcp_limits_ultimate_enforce라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 19.6에서 rate_limiter_mcp_sustained_limits_free_info, rate_limiter_mcp_sustained_limits_free_enforce, rate_limiter_mcp_sustained_limits_premium_info, rate_limiter_mcp_sustained_limits_premium_enforce, rate_limiter_mcp_sustained_limits_ultimate_info, rate_limiter_mcp_sustained_limits_ultimate_enforce라는 기능 플래그와 함께 시간당 제한이 도입되었습니다. 기본적으로 비활성화되어 있습니다.
  • GitLab 19.6에서 분당 제한이 일반 공급되었습니다. 기능 플래그 rate_limiter_mcp_limits_free_info, rate_limiter_mcp_limits_free_enforce, rate_limiter_mcp_limits_premium_info, rate_limiter_mcp_limits_premium_enforce, rate_limiter_mcp_limits_ultimate_info, rate_limiter_mcp_limits_ultimate_enforce가 제거되었습니다.
Feature flag

시간당 제한의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 기록을 참고합니다.

MCP 서버 엔드포인트인 POST /api/v4/mcp에 대한 요청은 사용자의 네임스페이스 요금제에 따라 사용자별로 제한됩니다:

요금제 분당 제한 시간당 제한
Free 60 3,600
Premium 600 5,000
Ultimate 600 5,000

이 제한은 클라이언트나 토큰별이 아니라 사용자별로 적용됩니다. 사용자가 여러 MCP 클라이언트를 연결하면 모든 클라이언트가 허용량 하나를 공유합니다.

MCP 서버 요청은 모든 트래픽에 적용되는 GitLab.com 속도 제한에도 포함되므로, 요청은 두 제한 중 어느 쪽에든 도달할 수 있습니다. 모든 요금제에서 MCP 서버 제한이 둘 중 더 낮습니다.

제한을 초과하면 GitLab은 Retry-After와 RateLimit-Reset을 포함한 표준 속도 제한 헤더와 함께 429 Too Many Requests를 반환합니다. RateLimit-Name은 도달한 제한을 식별합니다.

분당 제한 때문에 거부된 요청도 시간당 제한에 포함됩니다. 클라이언트가 429 응답 후 기다리지 않고 재시도하면 시간당 제한에 도달할 수 있으며, 그 제한이 초기화될 때까지 GitLab이 해당 클라이언트의 요청을 거부합니다.

도구의 기반이 되는 GitLab API 엔드포인트의 속도 제한은 다르게 보고됩니다. 이 경우는 rate_limited 도구 결과를 참고합니다.

GitLab Self-Managed와 GitLab Dedicated에서는 관리자가 인스턴스에 단일 MCP 서버 제한을 설정합니다. 자세한 내용은 인증된 MCP 서버 요청 속도 제한을 참고합니다.

지원되는 MCP 프로토콜 버전#

GitLab MCP 서버는 initialize 요청에서 프로토콜 버전을 협상합니다. 클라이언트가 서버에서 지원하지 않는 버전을 요청하면, 서버는 지원되는 버전을 나열한 JSON-RPC 오류를 반환합니다.

프로토콜 버전 지원
2025-11-25 지원됩니다. 클라이언트가 더 새로운 버전을 요청하는 경우에도 서버는 이 버전으로 응답합니다.
2025-06-18 지원됩니다.
2025-03-26 지원됩니다.
2026-07-28 initialize 요청에서만 허용됩니다. 서버는 이 버전의 무상태 기능을 아직 구현하지 않았으므로 2025-11-25로 응답합니다. 진행 상황은 이슈 627825를 참고합니다.

MCP 사양이 프로토콜 버전을 지원 중단해도 GitLab은 그 버전을 계속 지원합니다. 프로토콜 버전 제거는 브레이킹 체인지입니다. GitLab은 버전이 제거되기 전에 지원 중단 및 제거 페이지에서 제거를 안내합니다.

감사 이벤트#

GitLab은 클라이언트가 GitLab MCP 서버에 수행하는 도구 호출마다 AI 감사 이벤트를 기록할 수 있습니다. 자세한 내용은 GitLab MCP 서버의 감사 이벤트를 참고합니다.

관련 주제#