Gemini CLI

Gemini CLI

사전 준비

• Gemini CLI 최신 버전 설치
• 브라우저를 열 수 있는 환경(로그인·동의 화면용). 로그인 완료 시 CLI가 로컬 콜백(예: http://localhost:<포트>/oauth/callback)으로 결과를 받습니다.

단계별 연결 방법

1. ~/.gemini/settings.json을 열어 mcpServers에 조인트 서버를 추가합니다(파일이 없으면 새로 만듭니다).

   {
     "mcpServers": {
       "joint": {
         "command": "npx",
         "args": [
           "-y", "mcp-remote",
           "https://mcp.joint.now",
           "--static-oauth-client-info", "{\"client_id\":\"gemini-cli\"}",
           "--static-oauth-client-metadata", "{\"scope\":\"joint.read\"}"
         ]
       }
     }
   }

   Gemini CLI는 mcp-remote라는 연결 도우미를 거쳐 접속합니다(npx는 Gemini CLI 설치 시 함께 설치됩니다). 이미 mcpServers 항목이 있다면 그 안에 "joint" 블록만 추가하세요. 핵심은 ① 서버 URL을 경로·끝 슬래시 없이 https://mcp.joint.now로, ② OAuth 클라이언트 ID를 gemini-cli로 지정하는 것입니다.

   

2. Gemini CLI를 실행하고 /mcp 명령으로 서버 상태를 확인한 뒤, joint 서버의 인증을 진행합니다(예: /mcp auth joint).

   

3. 브라우저에서 조인트 로그인 → 동의 화면에서 허용합니다. 완료되면 CLI로 돌아옵니다.

권한 승인 과정

동의 화면에 연결 주체 Gemini CLI와 요청 권한(조회 전용)이 표시됩니다. 허용하면 토큰이 CLI에 저장됩니다.

연결 확인 방법

• /mcp 목록에서 joint 서버가 연결 상태로 표시되고 조인트 tool 목록이 나열됩니다.
• "조인트에서 내 워크스페이스 정보 조회해 줘"가 동작합니다

알려진 제한 사항

• Gemini CLI는 접속 URL과 서버 리소스 식별자의 글자 단위 일치를 요구합니다. URL에 경로나 끝 슬래시를 붙이면 "Protected resource ... does not match expected ..." 오류로 연결이 실패합니다.
• 자동 클라이언트 등록(DCR)에 의존하는 자동 설정 흐름은 사용할 수 없습니다. 반드시 clientId: gemini-cli를 명시하세요.
• 조인트 측 조회 빈도 제한(사용자당 1분 60회)을 넘으면 잠시 후 다시 시도해야 합니다.

연결해제

• settings.json에서 joint 항목을 제거하면 더 이상 연결되지 않습니다.

자주 발생하는 오류

Gemini 웹 및 앱의 미지원 범위

Gemini 웹(gemini.google.com)과 모바일·데스크톱 앱은 사용자가 임의의 MCP 서버를 연결하는 기능을 제공하지 않으므로, 조인트 MCP를 사용할 수 없습니다. 조인트가 별도의 우회 방법을 제공하지도 않습니다. Gemini 제품군에서 조인트 MCP를 사용하려면 Gemini CLI를 이용하세요. 향후 Gemini 제품의 기능 변경은 이 문서의 갱신으로 반영합니다.