히스토리

• GitLab 18.3에서 mcp_server와 oauth_dynamic_client_registration이라는 기능 플래그와 함께 실험으로 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 18.6에서 실험에서 베타로 변경되었습니다. 기능 플래그 mcp_server와 oauth_dynamic_client_registration이 제거되었습니다.
• GitLab 18.7에서 2025-03-26과 2025-06-18 MCP 프로토콜 사양 지원이 추가되었습니다.
• GitLab 18.7에서 2025-11-25 MCP 프로토콜 사양 지원이 추가되었습니다.
• GitLab 19.2에서 별도 설정으로 변경되고, GitLab Premium에서 GitLab Free로 이동되었습니다.

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를 참고합니다.

사전 요구 사항#

• MCP 서버 액세스를 허용합니다:
  • GitLab.com에서는 최상위 그룹에 대해 허용합니다.
  • GitLab Self-Managed와 GitLab Dedicated에서는 인스턴스에 대해 허용합니다.

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

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

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

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

HTTP 전송(권장)#

히스토리

• GitLab 18.6에서 도입되었습니다.
• GitLab 18.11에서 도구 이름 프리픽스가 추가되었습니다.

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_"
      }
    }
  }
}

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. 브라우저에서 인가 요청을 검토하고 승인합니다.

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

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 --transport http GitLab https://<gitlab.example.com>/api/v4/mcp
   

2. Claude Code를 시작합니다:

   claude
   

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

   • 채팅에서 /mcp를 입력합니다.
   • 목록에서 GitLab 서버를 선택합니다.
   • 브라우저에서 인가 요청을 검토하고 승인합니다.

4. 선택 사항. 연결을 확인하려면 /mcp를 다시 입력합니다. GitLab 서버가 연결된 상태로 표시되어야 합니다.

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

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 서버를 점검합니다.

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

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. 브라우저에서 인가 요청을 검토하고 승인합니다.

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

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. 브라우저에서 인가 요청을 검토하고 승인합니다.

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

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. 브라우저에서 인가 요청을 검토하고 승인합니다.

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

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. 브라우저에서 인가 요청을 검토하고 승인합니다.

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

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. 브라우저에서 인가 요청을 검토하고 승인합니다.

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

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

히스토리

• GitLab 19.3에서 관리자 UI를 통한 OAuth 애플리케이션 생성이 도입되었습니다.
• GitLab 19.3에서 그룹 및 사용자 UI를 통한 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를 사용해야 합니다.

보안 고려 사항#

클라이언트 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 매개변수를 허용하지만, 필수로 요구하지는 않습니다.

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

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

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

관련 주제#

• AI 카탈로그의 MCP 서버