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 joint.write\"}"
         ]
       }
     }
   }

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

   

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

   

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

권한 승인 과정

동의 화면에 연결 주체 Gemini CLI와 요청 권한(워크스페이스 조회·메시지 보내기·챙기기 관리)이 표시됩니다. 허용하면 토큰이 CLI에 저장됩니다. 쓰기 도구를 실행하기 전에 Gemini 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 제품의 기능 변경은 이 문서의 갱신으로 반영합니다.