개발자

Sume MCP insufficient_scope·누락 도구·타임아웃 해결

Sume MCP의 insufficient_scope 오류는 OAuth 세션에 mcp:write가 없다는 뜻입니다. mcp_health부터 호출한 뒤 스코프, 누락된 도구, 타임아웃을 해결하세요.

읽는 시간 5분Sume
전체 글

Sume 호스팅 MCP 서버에서 insufficient_scope는 mcp:read만 있는 OAuth 세션이 쓰기나 지출을 하는 도구를 호출했다는 뜻입니다. 클라이언트의 OAuth 로그인을 다시 실행하고 동의 화면에서 Write를 켜서 mcp:write를 부여하거나, API 키 세션으로 바꾸세요. 먼저 mcp_health를 호출하세요. 세션에 실제로 어떤 자격 증명과 스코프가 있는지 보여 줍니다.

해결 방법은 MCP 빠른 시작, MCP OAuth와 API 키, MCP 도구와 게이트, Job과 결과 (영문)를 바탕으로 하며, 2026-09-26에 확인했습니다. 현재 동작으로 설명한 필드는 호스팅 서버의 코드에서 가져왔습니다. 기초 페이지는 CLI와 https://mcp.sume.com/mcp의 호스팅 MCP가 여전히 동작하지만 현재 주 연동 경로는 아니라고 설명합니다. 처음 설정하는 방법은 Claude Code·Cursor·Codex를 호스팅 MCP로 Sume에 연결에 있습니다.

무엇부터 확인해야 하나요?

mcp_health를 호출하세요. 엔드포인트 준비 상태, 인증 출처, 안전 설정을 알려 주므로 자격 증명 문제와 도구 문제를 구분할 수 있습니다. OAuth에서는 authenticated.auth_source가 mcp_oauth입니다. 현재 응답에는 다음도 담깁니다.

  • authenticated.credential: 자격 증명의 type(oauth_access_token 또는 api_key)과 scopes.
  • tools: 이 세션이 노출하는 도구 이름.
  • safety: paid_tools_require_idempotency_key: true, signed_urls_returned: false 같은 안전 설정.
  • 이 도구의 설명에는 호출 한 번의 실패는 연결 문제가 아니라는 안내도 있습니다. 연결을 디버깅하기 전에 그 호출을 다시 시도하세요.

insufficient_scope는 왜 발생하나요?

동의 페이지의 Write 토글은 기본적으로 꺼져 있으므로, 기본 OAuth 세션에는 mcp:read만 있고 모든 쓰기·유료 도구가 insufficient_scope로 응답합니다. 세션마다 호출할 수 있는 도구는 Claude Code·Cursor·Codex를 호스팅 MCP로 Sume에 연결에 정리돼 있습니다. 현재 도구 오류 메시지는 Sume MCP OAuth token is missing mcp:write scope.이며, required_scope는 mcp:write로 설정됩니다.

빠른 시작 문서는 세 가지 해결 방법을 제시합니다.

  • 동의 화면에서 mcp:write를 부여하세요. 클라이언트의 OAuth 로그인을 다시 실행하고 Write를 켜면 됩니다. 현재 부여되는 스코프는 클라이언트가 요청한 값이 아니라 그 토글에서 정해집니다.
  • 전체 호스팅 도구 세트가 보이는 API 키 세션을 쓰세요. Authorization: Bearer $SUME_API_KEY나 x-api-key 중 하나만 보내고, 둘 다 보내지는 마세요.
  • 그 쓰기는 Developer API나 CLI로 하세요.
  • 통하지 않는 방법도 있습니다. 존재하지 않는 mcp:paid 스코프를 요청하는 것(authorize 요청이 invalid_scope로 실패), 그리고 빠진 mcp:write 스코프를 우회하지 못하는 레거시 allow_write·allow_paid 플래그를 보내는 것입니다.

도구가 없거나 파일을 열지 못하는 이유는 무엇인가요?

증상에 맞는 원인을 찾으세요. 라이브 도구 ID는 tools_list의 밑줄 이름이며, 점 별칭도 여전히 동작합니다.

MCP 도구와 게이트, MCP 빠른 시작, 영상 캡션 기준, 2026-09-26 확인.
증상원인해결
generate_image 같은 쓰기·유료 도구가 없음세션에 mcp:write나 API 키가 생길 때까지 숨겨짐mcp:write를 부여하거나 API 키로 연결
images_create나 videos_create를 찾을 수 없음Image 1.0과 Video 1.0은 REST 전용으로 남으며, 둘 다 곧 은퇴generate_image나 generate_video 호출
image-generations_create나 video-router_create가 목록에 없음폐기된 별칭. 현재는 이 이름으로 호출해도 여전히 새 이름으로 연결됨generate_image나 generate_video 사용
video-captions_create가 목록에 없음레거시 자막 생성 도구는 목록에서 빠짐. 진행 중인 클라이언트를 위해 이름으로 호출은 가능HTTP에서 POST /v1/video-captions로 자막을 만들고, video-captions_get으로 읽기
models_explore나 get_workflow_instructions를 찾을 수 없음Sume 도구가 아님컷아웃은 rmbg_create, 소셜 URL 미러는 media-imports_create
catalog_list에 도구가 없는 기능이 나옴카탈로그에는 호스팅 MCP가 감싸지 않는 HTTP 기능도 나올 수 있음그 기능은 HTTP로 호출
도구가 로컬 파일 경로를 열지 못함호스팅 MCP는 노트북의 파일을 읽을 수 없음URL을 전달. 생성 입력에는 공개 HTTPS, video_trim 같은 미디어 도구에는 이 워크스페이스의 media.sume.com URL

동의 화면이 왜 엉뚱한 사이트에서 열리나요?

동의는 MCP 호스트에서 이뤄집니다. https://mcp.sume.com/oauth/authorize는 app.sume.com이 아니라 https://mcp.sume.com/oauth/consent로 이어집니다. www.sume.com은 지원 중단된(deprecated) 인가 서버 표면이며, 메타데이터는 더 이상 이를 알리지 않습니다. 클라이언트가 https://mcp.sume.com/mcp를 가리키게 하고, 그 엔드포인트에서 protected-resource 메타데이터를 찾게 하세요.

자격 증명 함정이 두 가지 더 있습니다. sume login은 호스팅 MCP OAuth 토큰을 발급하지 않으며, MCP OAuth 토큰은 Sume API 키가 아니므로 CLI 설정에 넣으면 안 됩니다. 현재 액세스 토큰은 한 시간 동안 유효하고 리프레시 토큰은 없으며, 만료된 토큰은 토큰이 없을 때와 같은 401 챌린지를 받습니다. 한 시간 전에 동작하던 세션도 다시 로그인해야 합니다. MCP OAuth 플로의 동작 방식을 참고하세요.

호출이 타임아웃되면 어떻게 해야 하나요?

원격 MCP에서 jobs_wait 호출 한 번은 최대 55초까지 대기하며, 기본값은 50초입니다. 긴 렌더는 여러 번의 대기보다 오래 걸리고, 대기가 끝나도 Job은 끝나지 않고 계속 실행되고 청구됩니다.

  • wait_slice_expired를 받으면 같은 id로 jobs_wait를 다시 호출하세요. 유료 create는 절대 다시 제출하지 마세요.
  • jobs_wait에서 받은 524(또는 522, 523, 525)는 전송 실패이지 Job 결과가 아닙니다. 같은 id로 대기를 다시 호출하거나 jobs_status를 한 번 읽으세요.
  • 배치 대기와 결과는 긴 영상 Job의 MCP 도구 호출 타임아웃에서 다룹니다.

출처

관련 글

작성자 Sume