스킬

Showly 스킬 설치

Claude Code 또는 Codex에 공식 Showly 스킬을 추가합니다.

Showly 스킬은 인텐트 트리거 프롬프트와 게시 루프 인식 거부 모델로 MCP 서버를 래핑합니다. 이 페이지에서는 Claude Code, Codex 및 기타 MCP 인식 에이전트에 설치하는 방법을 안내합니다.

인증 작동 방식

토큰을 붙여넣지 않습니다. Showly의 MCP 서버는 https://mcp.showly.ai의 원격 HTTP 서버이며 표준 MCP 인증 핸드셰이크(OAuth 2.1 + PKCE)를 사용합니다. 에이전트가 Showly 도구를 처음 호출할 때:

에이전트가 연결하여 401을 받고 Showly의 인증 서버를 자동으로 검색합니다.
로그인하고 요청된 범위를 승인하는 showly.ai에 대한 브라우저 탭이 열립니다.
Showly 짧은 범위의 토큰을 에이전트에 직접 발급합니다. 당신은 그것을 보거나 복사하지 않습니다.

따라서 설치 프로그램의 유일한 작업은 에이전트에 서버 URL을 등록하는 것입니다. 처음 사용할 때 브라우저에서 로그인이 이루어집니다.

전제조건

Showly 작업 공간과 하나 이상의 사이트가 연결되어 있습니다.
대리인 접속을 승인하기 위한 권한입니다. 승인 단계에는 최소 site:write(소유자, 관리자, 개발자 또는 회원) 역할이 필요합니다. 권한이 낮은 계정에서 승인하면 실제로 보유한 범위로 축소된 토큰이 발행됩니다.

Claude Code

정식 설치 프로그램은 @showly/mcp-server 패키지(bin showly-mcp)입니다. claude-code 타겟으로 실행하세요:

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

그러면 Showly MCP 서버 블록이 Claude Code 구성에 기록됩니다. 토큰도 없고 별도의 로그인 명령도 없습니다. 다음에 Showly 도구를 호출하면 에이전트는 위에서 설명한 브라우저 로그인을 실행합니다.

내부에서 연결을 테스트하세요 Claude Code:

Showly, 내 사이트 목록을 표시하세요.

첫 번째 호출에서는 액세스를 승인하기 위해 브라우저 탭이 열립니다. 승인하면 mcp__showly__list_sites에서 가져온 사이트가 나열됩니다.

Codex

codex 대상과 동일한 설치 프로그램을 사용합니다. Showly 서버를 ~/.codex/config.toml에 기록합니다.

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

Codex를 다시 시작하여 새 서버를 선택한 다음 Showly 도구를 호출하여 브라우저 로그인을 실행하세요.

기타 MCP 호스트

설치 프로그램이 적용하지 않고 작성한 구성을 검사하려면 stdout를 대상으로 지정하세요.

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

인쇄된 MCP 서버 블록을 호스트 구성에 복사하세요. 표준 인증 흐름(WWW-Authenticate 검색 → 브라우저 동의)을 지원하는 모든 MCP 클라이언트는 수동 토큰 없이 https://mcp.showly.ai에 연결됩니다. 에이전트를 실행하는 컴퓨터에 브라우저가 없거나 승인할 사람이 그 컴퓨터 앞에 없다면 아래의 헤드리스 로그인을 사용하세요.

헤드리스 로그인(기기 흐름)

에이전트가 실행되는 컴퓨터에 브라우저가 없거나(서버, 컨테이너, CI, 원격 셸) 승인할 사람이 그 컴퓨터가 아니라 휴대폰을 들고 있다면 npx @showly/mcp-server login --to claude-code를 실행하세요. 페이지 주소와 짧은 코드를 출력한 뒤 아무 기기에서 승인할 때까지 기다리고, 승인되면 호스트 구성에 자격 증명을 기록합니다. --to codex는 ~/.codex/config.toml에 기록하지만, 그 설정은 자격 증명을 파일이 아니라 환경 변수 SHOWLY_TOKEN에서 읽습니다. 명령이 이에 맞는 export SHOWLY_TOKEN=… 줄도 출력하며, Codex를 실행하는 환경에서 이를 설정해야 인증됩니다. --to stdout은 아무것도 쓰지 않고 스니펫만 출력하며, --print-token은 토큰만 출력해 CI가 파일에 남기지 않고 받아갈 수 있게 합니다.

페이지의 코드가 터미널의 코드와 같을 때만 승인하세요. 동의 화면은 이를 명시적으로 확인하도록 요구합니다. 클라이언트가 표시하는 이름은 스스로 정한 것이고, 확인할 수 있는 부분은 코드뿐이기 때문입니다. 코드는 15분 동안 유효하며, 페이지를 열면 로그인과 승인을 마칠 시간이 10분 더 주어집니다. 만료되면 명령을 다시 실행하세요.

이는 클라이언트가 스스로 찾아내는 경로가 아닙니다. MCP 클라이언트는 기기 흐름을 시작하지 않으므로 login이 유일한 입구입니다. 기록된 자격 증명은 90일 뒤 만료되고 Showly는 갱신 토큰을 발급하지 않으므로, 그때 login을 다시 실행하세요.

문제 해결

tool not found: mcp__showly__list_sites — 스킬이 설치되었지만 MCP 서버가 아직 연결되지 않았습니다. Claude Code에서 claude mcp list를 실행하고 showly 항목을 확인하세요. Showly 도구를 한 번 호출하여 로그인을 실행하세요.

브라우저 로그인이 표시되지 않음/'승인되지 않음' — 에이전트가 표준 MCP 승인 흐름을 지원하지 않을 수 있습니다. 최신 버전인지 확인한 후 다시 시도하세요. 에이전트는 401 → WWW-Authenticate 검색 내용을 따라 동의 페이지를 열 수 있어야 합니다.

"승인할 권한이 없습니다." — 승인 계정에는 최소 site:write가 필요합니다. 소유자/관리자/개발자/회원 계정으로 로그인하거나 해당 역할을 가진 팀원의 승인을 받으세요.

"사이트를 찾을 수 없음" — 요청한 사이트가 승인된 범위 또는 사이트 허용 목록에 포함되지 않습니다. 로그인을 다시 실행하고 필요한 범위를 승인하거나 내 에이전트 페이지(/app/integrations)에서 액세스 권한을 확대하세요.

도구 호출 중단 — MCP 서버가 Showly의 API에 연결할 수 없습니다. 네트워크를 확인하세요. 엔드포인트를 재정의한 경우 SHOWLY_MCP_URL(MCP 서버 URL) 및 SHOWLY_API_URL(API 기본)가 오래된 위치를 가리키고 있지 않은지 확인하세요.

접근권한 철회

상담원의 액세스 권한을 취소하려면 내 상담원 페이지(/app/integrations)를 열고 상담원을 찾아 연결을 해제하세요. 철회는 즉시 적용됩니다. 상담원은 다음 통화 시 다시 로그인하라는 메시지를 받게 됩니다. 수동으로 회전할 토큰이 없습니다. 에이전트는 브라우저 흐름을 통해 새로운 토큰을 얻습니다. 브라우저가 없으면 npx @showly/mcp-server login으로 받습니다. 헤드리스 로그인으로 받은 자격 증명은 90일 뒤 만료됩니다.