---
title: MCP OAuth와 API 키
description: 호스팅 MCP 인증 매트릭스와 mcp:read / mcp:write 스코프를 살펴보세요.
---

호스팅 Sume MCP는 OAuth 액세스 토큰과 Sume API 키를 모두 받습니다. 두 자격
증명은 서로 바꿔 쓸 수 없습니다.

## 인증 매트릭스

| 모드 | 연결 방법 | 오늘 호스팅에서 가능한 것 |
|---|---|---|
| OAuth | 클라이언트가 MCP OAuth / protected-resource 메타데이터와 **MCP 호스트**의 1차 동의를 따릅니다 | 필수 `mcp:read`는 읽기 전용입니다. 동의 화면에서 Write를 켜면 `mcp:write`도 부여됩니다. **`mcp:paid` 스코프는 없습니다.** |
| API 키 | 클라이언트가 `Authorization: Bearer <SUME_API_KEY>` 또는 `x-api-key`를 보냅니다 | 전체 호스팅 도구 세트입니다. 지출은 지갑/접수이고, 쓰기·유료에는 `idempotency_key`가 필요합니다. |
| 로컬 `sume mcp` | `sume login` 또는 로컬 키 이후의 향후 CLI MCP | 아직 **출시되지 않았습니다**(`sume mcp doctor` → `coming_soon`). 호스팅 OAuth와는 별개입니다. |

## OAuth 플로 (호스팅)

1. MCP 클라이언트가 `https://mcp.sume.com/mcp`에 연결합니다.
2. Sume가 OAuth 챌린지와 protected-resource 메타데이터를 반환합니다
   (`authorization_servers`는 MCP origin이며 `www` / `app.sume.com`이 아닙니다).
3. 클라이언트가 사용자를 `https://mcp.sume.com/oauth/authorize`로 보내고, 이
   주소는 MCP 호스트의 1차 동의 페이지 `GET /oauth/consent`로 리다이렉트합니다
   (그 origin의 Clerk 브라우저 JS).
4. 로그인 후 동의 화면의 **Permissions**에서 Read는 고정 켜짐, Write 토글은
   기본 꺼짐입니다. Continue는 `POST /oauth/consent/decision`으로 전송됩니다.
5. 클라이언트가 인가 코드를 액세스 토큰으로 교환합니다(PKCE).
6. 클라이언트가 그 bearer 토큰으로 `https://mcp.sume.com/mcp`를 호출합니다.

`www.sume.com`은 보조·deprecated 인가 서버 표면으로 남고, protected-resource
메타데이터는 더 이상 이를 광고하지 않습니다. 인터랙티브 클라이언트를 MCP
OAuth 때문에 `app.sume.com`으로 보내지 마세요.

유용한 공개 메타데이터 엔드포인트입니다.

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

OAuth 리소스 audience는 다음과 같습니다.

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

개발 환경은 `https://mcp.dev.sume.com`에서 같은 형태입니다.

## 스코프

이미 적용된 플랫폼 동작입니다(`packages/mcp-oauth` +
`packages/mcp-server/src/mcp-oauth-as.ts`).

- 지원 스코프: `mcp:read`(필수)와 `mcp:write`(옵트인). Write를 부여하면 Read도
  포함됩니다.
- **`mcp:paid` OAuth 스코프는 없습니다.** 유료 제출은 지갑/접수입니다.
- `mcp:read` 세션에는 **읽기 전용** 도구만 보입니다. 변경 도구에 Write가
  없으면 `insufficient_scope`를 반환합니다.
- `mcp:write` 세션에는 변경·유료 도구가 보입니다.
- 유료·쓰기 제출에는 `idempotency_key`가 필요합니다(전송/중복 제거).
  선택 `dry_run`은 비용 프리플라이트입니다. 선택 `max_spend_usd`는 넘긴
  경우에만 강제됩니다.
- 레거시 `allow_write` / `allow_paid`는 하위 호환으로 받으며 **필수가
  아닙니다**. 빠진 `mcp:write` 스코프를 우회하지 못합니다.

OAuth를 쓰지 않는 자동화에는 API 키 원격 MCP가 다른 경로입니다.

## API 키 원격 MCP

기존 사용자와 자동화를 위해 API 키 호환성은 그대로 유지됩니다.

다음 중 하나를 보내세요.

```bash
# Bearer
Authorization: Bearer $SUME_API_KEY

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

API 키 세션에서는 쓰기·유료 도구가 보입니다. 실행에는 변경·유료 호출에
`idempotency_key`가 필요합니다. 첫 유료 제출 전에는 `dry_run=true` 또는
`generation_admission_preview`를 권장합니다. `max_spend_usd`는 넘긴 경우에만
상한으로 동작합니다.

키는 대시보드에서 만드세요. [API 키](/dashboard/api-keys)에서 살펴보세요.

## 자격 증명 안전 수칙

- MCP OAuth 토큰은 Sume API 키가 **아닙니다**.
- OAuth 토큰을 CLI 설정에 저장하거나, 프롬프트에 붙여 넣거나, 서드파티
  프로바이더로 전달하지 마세요.
- 우회 목적으로 호스팅 OAuth 클라이언트용 API 키를 발급하지 마세요.
- `sume login`은 호스팅 MCP OAuth 토큰을 중개하지 **않습니다**.
- API 키가 로그나 채팅 기록에 노출되면 즉시 교체하세요.

## 호스팅 MCP vs 로컬 MCP vs Studio Agent

| 질문 | 답 |
|---|---|
| Cursor/Claude에 가장 좋은 인터랙티브 커넥터는? | `https://mcp.sume.com/mcp`의 호스팅 MCP + OAuth입니다. |
| 이미 CLI를 쓰는 로컬 셸 에이전트에는? | `sume login` 이후 [CLI](/cli) 명령어를 직접 쓰세요(로컬 `sume mcp`는 아직 미출시). |
| 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)