스킬

기술 빠른 시작

@showly/mcp-server를 설치하고 터미널에서 인증하면 실제 미리보기 URL을 빠르게 확인할 수 있습니다.

Showly의 헤드라인 약속은 "에이전트에서 사이트 배포"입니다. 이 페이지는 끝까지 레시피. 설치 및 첫 번째 미리보기에는 약 90초가 소요됩니다. 신선한 노트북; 프로덕션 게시 경로에는 수동 브라우저 내 승인 단계가 추가됩니다. (섹션 5에서 다룹니다).

1. 에이전트에 설치

정식 설치 경로는 @showly/mcp-server 패키지(bin showly-mcp). Claude Code의 경우:

npx @showly/mcp-server install --to claude-code

Codex의 경우:

npx @showly/mcp-server install --to codex

이는 단일 MCP-서버 항목(전송 + URL)을 ~/.claude.json 또는 ~/.codex/config.toml. 토큰이 기록되지 않습니다. 에이전트는 엔드포인트 자체에서 Showly의 OAuth 인증 서버를 검색합니다. 처음 사용할 때 브라우저 로그인을 실행합니다. 패키지는 또한 입력된 내용을 배송합니다. manifest.json 모든 Showly 도구, 필요한 범위 및 여부를 나열합니다. MCP-원본 통화가 허용됩니다.

브라우저 로그인과 헤드리스 로그인은 스킬 설치를 참조하세요.

설치 프로그램에서 에이전트를 지원하지 않는 경우 다음을 실행하세요. npx @showly/mcp-server install --to stdout 스니펫을 수동으로 붙여넣습니다.

2. 실제 대화를 통해 인증하기

Claude Code(또는 Codex에 상응하는 것)을 열고 Showly 도구. 예를 들어:

"내 Showly 사이트를 나열합니다."

에이전트가 list_sites를 호출합니다. 이 컴퓨터에는 아직 Showly 토큰이 없으므로 호스트가 브라우저 로그인을 열고 사람이 Allow를 클릭합니다.

컴퓨터에 브라우저가 없거나(서버, 컨테이너, CI, 원격 셸) 당신이 그 앞에 없다면 헤드리스 로그인을 대신 사용하세요.

npx @showly/mcp-server login --to claude-code

다음 내용을 그대로 출력한 뒤 기다립니다.

Showly needs one approval from you. If you do not have a Showly
account yet, you will be asked to create one first.

  1. Open this page:   https://showly.ai/oauth/device
  2. Enter this code:  K7QM-3XPD

Same machine as your browser? Use the direct link instead:
  https://showly.ai/oauth/device?user_code=K7QM-3XPD

The page will show the code K7QM-3XPD before you approve.
Approve ONLY if it matches the code above. If it shows a
different code, someone else is trying to get in - refuse it.

Waiting for approval until 14:58 local. Once you approve, this
command picks it up on its own - no need to come back and tell it.

아무 기기에서나(휴대폰도 됩니다) 그 페이지를 열고 가입할 때 쓴 이메일로 로그인하세요. 동의 화면에는 코드, 요청된 범위, 허용 / 거부 버튼이 표시됩니다.

페이지의 코드와 터미널의 코드를 대조하고, 일치한다는 확인란을 선택한 다음 허용을 클릭하세요. 이 대조가 핵심입니다. 동의 화면에 나오는 클라이언트 이름은 클라이언트가 스스로 정한 것이므로 검증할 수 있는 부분은 코드뿐입니다. 터미널로 돌아오면 명령이 몇 초 안에 끝나고 읽기 도구를 바로 쓸 수 있습니다.

3. 한 줄만 변경하고 미리보기

상담원에게 물어보세요:

"northstar 사이트에서 H1을 'Hello from W7'로 변경하고 미리보기를 해주세요."

에이전트는 네 가지 도구 호출을 연결합니다.

  1. create_change_plan — 문장을 구조화된 계획으로 바꿉니다.
  2. apply_site_patch — 편집을 _changeset_(범위 site:write)으로 준비합니다.
  3. create_preview — 변경 세트를 빌드하고 보호된 미리보기 URL을 반환합니다.

(범위 preview:create).

  1. run_checks — 해당 배포에서 Lint/typecheck/빌드 상태를 읽습니다.

(범위 checks:run).

작은 편집은 약 5초, 실제 Next.js 앱은 약 30초가 걸립니다. 에이전트가 보호된 미리보기 URL을 표시합니다. 현재 라이브 사이트에 영향을 주지 않고 변경 사항을 검토할 수 있습니다.

4. 제작 시작

Showly 에이전트가 직접 프로덕션에 게시하는 것을 허용하지 않습니다. 상담원이 전화함 request_publish(범위 publish:request), 보류 중인 승인을 생성하고 배송하는 대신 webApprovalUrl 딥 링크를 반환합니다.

{
  "ok": true,
  "data": {
    "approvalId": "appr_xxx",
    "deploymentId": "dep_xxx",
    "state": "pending",
    "expiresAt": "2026-05-31T10:00:00.000Z",
    "reused": false,
    "webApprovalUrl": "https://showly.ai/app/deployments/dep_xxx/publish"
  }
}

상담원이 webApprovalUrl를 건네줍니다. 열어서 정확한 미리보기를 검토하고 계획에 필요한 팀원 승인을 완료합니다. OTP/MFA 등록은 되지 않습니다. 필수. 게시가 시작되면 에이전트는 다음과 같이 get_preview_status를 호출합니다. waitForChange: true 그리고 긴 폴링(기본값 30초, 최대 60초) 천장). 프로덕션 배포가 ready로 바뀌면 응답 에이전트가 최종 라이브 URL로 반환하는 productionUrl가 포함됩니다.

기기에서 전송되는 내용

  • 에이전트는 로컬에서 실행됩니다(Claude Code, Codex, ...).
  • 사이트 컨텍스트를 읽을 때는 MCP 토큰 범위에서 허용된 데이터만 반환됩니다.
  • apply_site_patch 또는 다른 업로드 도구를 호출하면 변경 파일이 Showly로 전송됩니다.
  • Showly는 해당 파일로 비공개 미리보기를 만들고 관련 작업을 작업공간 감사 기록에 남깁니다.

전체 배포 흐름은 아키텍처을 참조하세요.

일반적인 오류

  • missing_bearer_token — 에이전트가

Authorization: Bearer mcp_…를 보내지 않았습니다. npx @showly/mcp-server install을 다시 실행하고 에이전트를 재시작하세요.

  • invalid_token — 토큰이 만료 또는 취소되었거나 MCP 토큰이 아닙니다.

Showly 도구를 다시 호출하여 새로운 브라우저 로그인을 실행하세요. 대리인 자동으로 새 토큰을 얻습니다. (강제하려면 아래의 이전 행을 취소하십시오. 관리자 → 상담원 먼저.)

  • insufficient_scope — 요청한 도구에는 귀하가 부여하지 않은 범위가 필요합니다

동의 흐름 중에. 취소 + 재승인, 이번에는 승인 범위.

  • 프로덕션 게시 — publish_site는 단기 2단계를 사용합니다.

사용자가 '예'라고 답한 후 확인합니다. 작업공간이 있는 경우 2차 검토자 승인 정책이 활성화된 경우 request_publish 및 해당 항목을 사용하세요. webApprovalUrl 대신. 두 흐름 모두 OTP/MFA 등록이 필요하지 않습니다.

다음 단계