로그인(OAuth)과 API 키

호스팅 MCP와 sume CLI가 하나의 Sume OAuth로 로그인하는 방식, 그리고 API 키를 쓰는 곳을 살펴보세요.

이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.

사람은 MCP 클라이언트에서든 sume CLI에서든 Sume에 한 번, OAuth로 로그인합니다. 스크립트는 Sume API 키를 씁니다. 둘은 서로를 대신하지 않습니다.

인증 매트릭스

누가	연결 방법	할 수 있는 일
MCP 클라이언트(Claude, ChatGPT, Cursor, Codex)	`https://mcp.sume.com/mcp`의 OAuth: 클라이언트가 브라우저를 열면 로그인하고 Allow를 누릅니다	항상 `mcp:read`. 동의 화면의 Create and spend credits를 켜면 `mcp:write`가 더해집니다.
`sume` CLI	`sume login`: 브라우저에서 같은 로그인, 또는 `sume login --device`로 코드 승인	같은 스코프. CLI 토큰은 HTTP API(`https://api.sume.com/v1`)에서 씁니다.
스크립트·서버	HTTP API나 `https://api.sume.com/mcp`에 Sume API 키	전체 도구 세트. `mcp.sume.com`은 API 키를 받지 않습니다.

mcp:paid 스코프는 없습니다. 유료 호출은 워크스페이스 잔액으로 확인하고, idempotency_key가 필요하며, dry_run으로 먼저 가격을 볼 수 있습니다.

MCP 로그인

MCP 클라이언트가 https://mcp.sume.com/mcp에 연결합니다.
Sume이 OAuth 챌린지와 보호 리소스 메타데이터를 돌려줍니다. authorization_servers는 https://mcp.sume.com입니다.
클라이언트가 등록하고(Dynamic Client Registration, 또는 https:// 클라이언트 ID 메타데이터 문서) https://mcp.sume.com/oauth/authorize로 보냅니다.
로그인하면 동의 화면이 앱 이름과 돌아갈 호스트를 보여 줍니다.
- Read는 항상 켜져 있고, Create and spend credits가 mcp:write입니다.
- Workspace로 연결이 시작할 곳을 고릅니다. 개인 워크스페이스나 속한 팀입니다.
- Allow는 앱에 코드를, Deny는 error=access_denied를 돌려줍니다. 둘 다 iss=https://mcp.sume.com이 붙습니다.
앱이 코드(PKCE)를 1시간짜리 액세스 토큰과 리프레시 토큰으로 바꿉니다.
앱이 그 액세스 토큰으로 https://mcp.sume.com/mcp를 호출합니다.

앱은 알아서 토큰을 갱신합니다. 리프레시 토큰은 한 번만 쓰이고, 다시 쓰이면 연결이 끝나며, 30일 동안 쓰지 않으면 만료됩니다. 연결을 끝내려면 리프레시 토큰을 /oauth/revoke로 보내세요. 그 액세스 토큰은 다음 요청부터 실패합니다.

다른 워크스페이스에서 일하려면 에이전트에게 말하세요. list_workspaces가 워크스페이스를 보여 주고 select_workspace가 이 연결을 옮깁니다. 다시 연결할 필요는 없습니다.

공개 메타데이터:

MCP 클라이언트의 토큰 대상(audience):

개발 환경은 https://mcp.dev.sume.com에서 같은 구조를 씁니다.

CLI 로그인

sume login은 MCP와 같은 동의 화면을 씁니다. resource=https://api.sume.com을 요청하므로 토큰은 HTTP API에서 쓰이고 mcp.sume.com/mcp에서는 쓰이지 않습니다. CLI는 세션을 ~/.sume-com/config.json(본인만 읽을 수 있음)에 두고 직접 갱신합니다.

스코프

mcp:read(필수)와 mcp:write(선택). write를 허용하면 항상 read도 포함됩니다.
mcp:read 연결은 읽기 전용 도구만 봅니다. 데이터를 바꾸는 도구는 insufficient_scope를 돌려줍니다. HTTP API에서도 읽기 전용 로그인은 읽기만 할 수 있습니다.
mcp:write 연결은 데이터를 바꾸는 도구와 유료 도구를 봅니다.
유료·쓰기 호출에는 idempotency_key가 필요합니다. dry_run은 아무것도 실행하지 않고 가격을 보여 주고, max_spend_usd를 보내면 호출 상한이 됩니다.

스크립트용 API 키

https://api.sume.com/v1/…이나 https://api.sume.com/mcp에 둘 중 하나를 보내세요.

https://mcp.sume.com/mcp는 사람용이라 API 키에 401 api_key_not_accepted로 답합니다. 키는 대시보드에서 만드세요: API keys. sume login --api-key는 로그인 대신 CLI에 키를 저장합니다.

자격 증명 안전

로그인 토큰은 API 키가 아닙니다. 둘 다 프롬프트에 붙여 넣거나 외부 프로바이더에 보내지 마세요.
sume auth token은 내 스크립트용 토큰을 출력하며, 1시간 동안 유효합니다.
키나 토큰이 로그나 채팅 기록에 남았다면 취소하세요. 키는 교체하고, 로그인은 sume logout으로 끝내세요.

호스팅 MCP vs CLI vs Studio Agent

질문	답
Cursor/Claude에 가장 좋은 연결은?	OAuth로 로그인한 `https://mcp.sume.com/mcp` 호스팅 MCP입니다.
로컬 셸 에이전트에는?	`sume login` 후 CLI입니다.
Image 1.0 / Video 1.0(`images_create` / `videos_create`)이 필요하면?	호스팅 MCP에는 없습니다. Developer API를 쓰세요. 라우터 스틸·클립은 `generate_image` / `generate_video`입니다.
Studio Agent는 호스팅 MCP와 같은가요?	아닙니다. Studio Agent는 별도 제품 화면입니다.