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

사람은 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 로그인

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

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

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

공개 메타데이터:

```text
https://mcp.sume.com/.well-known/oauth-protected-resource/mcp
https://mcp.sume.com/.well-known/oauth-authorization-server
```

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

```text
https://mcp.sume.com/mcp
```

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

## CLI 로그인

```bash
sume login            # 브라우저를 엽니다. 리디렉션은 127.0.0.1로 돌아옵니다
sume login --device   # 코드를 출력합니다. mcp.sume.com/oauth/device에서 승인하세요
sume auth status      # 이 머신이 로그인한 방식
sume auth token       # 스크립트용 현재 액세스 토큰
sume logout           # 로그인을 취소하고 지웁니다
```

`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`에 둘 중 하나를
보내세요.

```bash
# Bearer
Authorization: Bearer $SUME_API_KEY

# 또는 헤더
x-api-key: $SUME_API_KEY
```

`https://mcp.sume.com/mcp`는 사람용이라 API 키에 `401 api_key_not_accepted`로
답합니다. 키는 대시보드에서 만드세요: [API keys](/dashboard/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](/cli)입니다. |
| Image 1.0 / Video 1.0(`images_create` / `videos_create`)이 필요하면? | 호스팅 MCP에는 없습니다. Developer API를 쓰세요. 라우터 스틸·클립은 `generate_image` / `generate_video`입니다. |
| Studio Agent는 호스팅 MCP와 같은가요? | 아닙니다. Studio Agent는 별도 제품 화면입니다. |

## 관련 문서

- [MCP 개요](/mcp)
- [MCP 빠른 시작](/mcp/quickstart)
- [도구와 게이트](/mcp/tools-and-gates)
- [CLI 개요](/cli)
- [인증](/authentication)