Gemini CLI MCP 서버: Sume 호스팅 MCP 추가하기

Gemini CLI에 Sume 호스팅 MCP 서버를 추가하려면 ~/.gemini/settings.json의 mcpServers 아래에 "httpUrl": "https://mcp.sume.com/mcp"와, 값이 "Authorization": "Bearer $SUME_API_KEY"인 headers를 담은 sume 항목을 넣으세요. Gemini CLI는 파일을 불러올 때 설정 문자열 안의 $VAR_NAME 참조를 해석하므로, 키 자체는 환경 변수에 그대로 남습니다.

Gemini CLI 동작은 MCP 서버 가이드와 설정 레퍼런스에서, Sume 쪽 내용은 MCP 빠른 시작, OAuth와 API 키, MCP 도구와 게이트에서 가져왔으며, 모두 2026-09-27에 확인했습니다. Sume는 Gemini CLI 확장 프로그램을 배포하지 않습니다. Gemini CLI가 Sume 원격 MCP 서버에 직접 연결합니다. Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명합니다. Claude Code, Cursor, Codex는 Claude Code·Cursor·Codex를 Sume에 연결하기에서 다룹니다.

settings.json 항목에는 무엇을 넣나요?

Gemini CLI는 URL 필드로 트랜스포트를 고릅니다. httpUrl은 Sume 빠른 시작 문서가 요구하는 streamable HTTP를, url은 SSE를 뜻합니다. 둘 다 설정하면 httpUrl이 우선합니다. headers는 그 URL로 보내는 요청에 붙는 HTTP 헤더 맵이며, Sume는 키를 Authorization: Bearer나 x-api-key로 받습니다.

Sume 문서는 인터랙티브 클라이언트에는 OAuth를 권장하고, API 키 원격 MCP는 기존 사용자와 자동화를 위해 유지합니다. 이 글은 양쪽 문서가 모두 설명하는 키 헤더 방식을 씁니다. Gemini CLI 자체의 OAuth 플로는 로컬 브라우저를 여는데, Gemini CLI 문서에 따르면 헤드리스 환경, X11 포워딩이 없는 원격 SSH 세션, 브라우저를 지원하지 않는 컨테이너에서는 동작하지 않습니다.

모든 Gemini CLI 세션에 적용되는 사용자 파일 ~/.gemini/settings.json을 쓰세요. 프로젝트의 .gemini/settings.json은 그 프로젝트에서만 적용됩니다. $SUME_API_KEY 참조를 쓰면 키 자체가 파일에 들어가지 않는데, API 키 세션에는 Sume 쓰기·유료 도구가 보이므로 이 점이 중요합니다.

{
  "mcpServers": {
    "sume": {
      "httpUrl": "https://mcp.sume.com/mcp",
      "headers": { "Authorization": "Bearer $SUME_API_KEY" },
      "includeTools": [
        "mcp_health",
        "tools_list",
        "tools_schema",
        "generation_admission_preview",
        "generate_image",
        "jobs_wait",
        "jobs_result"
      ]
    }
  }
}

대신 gemini mcp add로 추가할 수도 있나요?

네. gemini mcp add가 settings.json에 서버를 대신 설정해 주지만, -s, --scope 플래그의 기본값이 project이므로 -s user를 넘기세요. --transport http는 streamable HTTP 트랜스포트이고, -H, --header는 헤더를 설정하며, --include-tools는 쉼표로 구분한 목록을 받습니다. 헤더는 작은따옴표로 감싸세요. 그래야 셸이 키를 명령어 안에 펼쳐 넣지 않고 $SUME_API_KEY 문자열을 그대로 Gemini CLI에 넘깁니다.

gemini mcp add -s user --transport http \
  --header 'Authorization: Bearer $SUME_API_KEY' \
  --include-tools mcp_health,tools_list,tools_schema,jobs_wait,jobs_result \
  sume https://mcp.sume.com/mcp

Gemini CLI는 Sume 도구 이름을 어떻게 짓고, 호출을 어떻게 확인하나요?

발견된 모든 도구는 mcp_{serverName}_{toolName} 형식의 정규화된 전체 이름을 받으므로, Sume의 generate_image는 mcp_sume_generate_image가 됩니다. Gemini CLI는 서버 이름에 밑줄을 쓰지 말라고 경고합니다. 정책 파서가 mcp_ 뒤의 첫 번째 밑줄에서 이름을 나누기 때문입니다.

서버를 신뢰하도록 설정하지 않았다면 도구를 호출할 때마다 확인을 요청하며, 프롬프트에는 Proceed once, Always allow this tool, Always allow this server, Cancel이 선택지로 나옵니다. Sume에는 trust를 꺼 두세요. API 키 세션은 유료 도구까지 호출할 수 있고, 유료 도구마다 idempotency_key가 필요합니다.

유료 호출 전에 에이전트는 무엇을 해야 하나요?

Sume 게이트는 Gemini CLI 확인 프롬프트 아래 단계에서 적용됩니다. 유료 호출마다 idempotency_key가 필요하고, generation_admission_preview나 dry_run=true를 붙인 유료 도구로 접수 여부와 비용을 먼저 미리 볼 수 있으며, max_spend_usd는 값을 넘긴 경우에만 호출의 상한이 됩니다. Gemini CLI는 로컬 머신에서 실행되지만 호스팅 MCP는 노트북의 파일을 읽을 수 없습니다. 업로드는 업로드 URL, 클라이언트 PUT, assets_complete 순서로 진행됩니다. 프리뷰는 Sume Job 실행 전에 AI 영상 생성 비용 추정하기에서 다루고, Sume MCP 도구 목록은 도구를 읽기, 쓰기, 유료로 나눠 정리합니다.

연결은 어떻게 확인하나요?

세션에서 /mcp를 실행하면 서버마다 연결 상태(CONNECTED, CONNECTING, DISCONNECTED)와 도구가 보이며, 셸에서는 gemini mcp list로 연결 상태를 볼 수 있습니다. 그다음 Gemini에게 엔드포인트, 인증 출처, 안전 설정을 확인해 주는 mcp_health와, 세션에 보이는 모든 도구를 나열하는 tools_list를 호출해 달라고 하세요.