MCP OAuth와 API 키

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

호스팅 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 플로 (호스팅)

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

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

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

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

개발 환경은 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 키 호환성은 그대로 유지됩니다.

다음 중 하나를 보내세요.

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

키는 대시보드에서 만드세요. API 키에서 살펴보세요.

자격 증명 안전 수칙

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 명령어를 직접 쓰세요(로컬 `sume mcp`는 아직 미출시).
Image 1.0 / Video 1.0(`images_create` / `videos_create`)이 필요하면?	호스팅 MCP에는 없습니다. Developer API를 사용하세요. 라우터 스틸/클립은 `generate_image` / `generate_video`입니다.
Studio Agent가 호스팅 MCP와 같은 것인가요?	아닙니다. Studio Agent는 별개의 제품 표면입니다.