MCP 범위 및 토큰
범위가 지정된 MCP 토큰을 발행하고 안전하게 취소합니다.
Showly MCP 토큰은 에이전트가 인증하는 방법입니다. 이 페이지에서는 발행 방법, 범위를 엄격하게 지정하는 방법, 문제가 있을 때 회전하거나 취소하는 방법을 다룹니다.
토큰 발행
작업공간 설정 → MCP 클라이언트 → 새 클라이언트.
5개의 필드를 설정합니다.
- 클라이언트 이름 — 감사 로그에 표시됩니다. 설명적으로 작성하세요.
Claude Code (alice@acme)가token-3보다 읽기가 더 좋습니다. - 프로젝트 범위 — 선택 사항입니다. 설정된 경우 토큰은 해당 프로젝트의 사이트/배포만 보고 변경할 수 있습니다.
- 범위 — 필요한 최소값을 선택합니다. 기본값은
project:read,site:read,preview:read입니다. - TTL — 토큰이 유효한 기간입니다. 기본값은 90일, 최대 365일입니다.
- 참고 — Free-텍스트. 토큰의 용도를 기록하는 데 사용합니다.
토큰은 생성 시 한 번 표시됩니다. 복사하세요. 우리는 일반 텍스트를 저장하지 않습니다.
범위 참조
범위는 중첩된 계층이 아닌 플랫 문자열입니다. 토큰은 명시적인 목록을 전달하며 API는 아래의 정확한 이름만 허용합니다.
| 범위 | 계층 | 허용 |
|---|---|---|
project:read | 읽기 | list_projects — 이 토큰이 액세스할 수 있는 프로젝트 목록 및 검사 |
site:read | 읽기 | list_sites, get_site_context, create_change_plan, list_site_versions, get_site_files — 사이트 상태 읽기 |
site:write | 쓰다 | apply_site_patch, create_site_from_template — 단계 편집(직접 배포하지 않음) |
site:delete | 쓰다 | delete_site — 사이트의 2단계 연속 일시 삭제(관리 계층) |
preview:read | 읽기 | get_preview_status — 배포 상태 읽기 |
preview:create | 쓰다 | create_preview, create_github_preview, delete_preview — 비공개 미리보기 구체화/일시 삭제 |
checks:run | 쓰다 | run_checks — Lint/typecheck/build/audit 상태 읽기 |
publish:request | 쓰다 | request_publish — 프로덕션 게시를 위한 승인 행 열기 |
publish:confirm | 쓰다 | publish_site — 2단계 확인 및 프로덕션 게시(대화 중 사람 확인, 단독/비승인 계획) |
rollback:confirm | 쓰다 | rollback_to_version — 이전 버전으로 다시 돌아가는 2단계 롤 프로덕션(관리 계층, 프로덕션 직접) |
logs:read | 읽기 | get_deployment_logs — 테일 캡처 빌드 로그; diagnose_deployment 제한된 클라이언트/에이전트 진단도 노출 |
template:read | 읽기 | list_templates — 사용 가능한 사이트 템플릿 목록 |
template:create | 쓰다 | create_site_from_template — 템플릿에서 새 사이트 구체화 |
함축 사다리가 없습니다. publish:request 부여는 preview:create 부여가 아닙니다. 클라이언트가 필요로 하는 범위를 정확하게 선택하세요. 웹 UI의 "MCP 토큰" 패널은 이 목록을 확인란으로 표시합니다. 동일한 상수가 사용자 지정 RBAC 역할에 대한 역할 빌더를 지원합니다.
레거시rollback_deployment동사는 범위에 관계없이 노출되지 않습니다 MCP;publish_site는 MCPpublish:confirm및 2단계 대화 중 확인을 통해서만 호출 가능합니다. 근거는 도구 참조를 참조하세요.
범위가 좁은 토큰의 모습
인프라에 절대로 접근해서는 안 되는 _콘텐츠 전용_ 에이전트의 경우:
- 허용 목록:
marketing-site사이트만 해당됩니다. - 범위:
site:read,site:write. 에이전트는 패치를 준비할 수 있지만 미리 보기를 생성하거나 게시할 수는 없습니다. - TTL: 30일.
CI의 _배포봇_의 경우:
- 허용 목록: 배포 중인 프로덕션 사이트만 해당됩니다.
- 범위:
preview:read,preview:create,checks:run,publish:request. 아니요site:write— 패치는 봇이 아닌 CI의 체크인 워크플로에서 제공됩니다. - TTL: 14일, CI에 따라 순환됩니다.
_템플릿 기반 온보딩 봇의 경우_:
- 허용 목록: 봇이 초대된 모든 프로젝트입니다.
- 범위:
project:read,template:read,template:create,site:write,preview:read,preview:create. 봇이 템플릿을 선택하고, 사이트를 만들고, 첫 번째 미리보기 빌드를 볼 수 있습니다. - TTL: 7일.
회전
두 가지 경로:
- 수동 — 클라이언트에서 회전을 클릭합니다. 이전 토큰은 즉시 취소됩니다. 새 것을 복사하고 쉘 구성을 업데이트하십시오.
- 예약됨 — 작업 공간 설정 → 토큰 정책에서 교체 주기를 설정합니다. Showly 만료되기 전에 고객 소유자에게 이메일을 보냅니다.
철회
토큰을 즉시 삭제하려면 취소를 클릭하세요. 취소된 토큰을 사용하는 모든 진행 중인 도구 호출은 401을 받습니다. 클라이언트 이름은 감사 로그(revoked 플래그 포함)에 남아 있으므로 기록 항목이 계속 확인됩니다.
토큰이 손상되었다고 생각되면 먼저 취소하고 두 번째로 조사하세요. publish:request 범위의 손상된 토큰은 게시 승인을 열 수 있지만 여전히 인간 승인자 또는 배포 바인딩 게시 확인을 우회할 수는 없습니다.
감사 가시성
모든 도구 호출은 클라이언트 ID(토큰 아님)가 포함된 감사 행을 작성합니다. 다음을 수행할 수 있습니다.
- 클라이언트의 모든 통화 쿼리:
client_id eq <id>. - 동사를 쓰는 모든 통화를 쿼리합니다:
action eq mcp.request_publish. - 활성화된 감사 표면을 통해서만 기록을 검토하고 내보낼 수 있습니다.
작업 공간.
토큰으로 할 수 없는 것
- 교차 테넌트가 읽습니다. 토큰은 하나의 작업공간에 바인딩됩니다.
- 승인을 우회합니다.
publish:request범위는 승인을 _열 수 있는_ 권한을 부여합니다. 승인 규칙은 계속 적용됩니다. - 청구서 또는 RBAC에 씁니다. 여기에는 인간 + 관리자 역할 + 브라우저 세션이 필요합니다.
- 레거시
rollback_deployment동사를 호출합니다. 이는 MCP 서버에 전혀 등록되지 않습니다. (publish_site에는publish:confirm범위와 명시적인 2단계 확인이 필요합니다.)
직접 게시는 Free/Pro 게시에도 포함된 publish:confirm를 사용합니다. 권장되는 출판 대행자 승인이 필요하지만 여전히 단기간 두 번째 호출 확인. 파괴적인 삭제 및 롤백 범위 선택 상태를 유지하세요.