복붙도 끝: Claude Code·Codex가 HTML을 바로 링크로 발행하게 만드는 법

Claude Code나 Codex가 만든 HTML을 매번 복사해 업로드하지 않아도 됩니다. HTML2WEB의 공개 Remote MCP 주소를 한 번 등록하면, “이 파일을 1시간 링크로 발행해줘”라는 요청으로 에이전트가 게시 도구를 호출하고 URL을 돌려줄 수 있습니다. 공개 Free 엔드포인트에는 API 키나 bearer token이 필요하지 않습니다.

MCP를 한 문장으로 이해하기

MCP(Model Context Protocol)는 AI 클라이언트가 외부 서비스의 도구를 발견하고 호출하는 규격입니다. 공식 MCP Tools 명세는 서버가 도구 이름, 설명, 입력 스키마를 제공하고 클라이언트가 tools/call 요청으로 실행하는 방식을 정의합니다.

HTML2WEB은 이 규격으로 발행·수정·삭제 도구를 제공합니다. 연결했다고 파일이 자동으로 게시되는 것은 아닙니다. 사용자가 발행을 요청하고 클라이언트의 승인 정책이 허용할 때 도구가 실행됩니다.

Claude Code에 HTML2WEB 연결하기

터미널에서 다음 명령을 실행합니다.

claude mcp add --transport http --scope user html2web https://html2web.iill.dev/mcp

--transport http는 Remote MCP가 Streamable HTTP 방식이라는 뜻입니다. --scope user는 모든 프로젝트에서 이 연결을 사용합니다. 한 프로젝트에만 필요하다면 --scope local을 사용하거나 기본값을 유지합니다.

연결 상태를 확인합니다.

claude mcp list

Claude Code 세션에서는 /mcp 메뉴에서도 연결을 확인할 수 있습니다. 현재 옵션은 Claude Code MCP 공식 문서를 기준으로 확인하세요.

Claude Code에서 실제로 요청하기

report.html을 HTML2WEB으로 발행해줘.

- 만료: 24시간
- 비밀번호: 사용하지 않음
- 발행 전에 API 키, 토큰, 접속 문자열, 개인정보, 고객 데이터,
  내부 호스트명과 로컬 자산 경로를 검사할 것.
- 하나라도 발견하면 발행하지 말고 파일 위치와 이유만 보고할 것.
- 성공하면 공유 URL과 만료 시각만 공개 답변에 표시할 것.
- 관리 토큰은 공개 답변이나 채팅 채널에 출력하지 말 것.

Codex에 HTML2WEB 연결하기

현재 Codex CLI에서는 다음 명령을 사용합니다.

codex mcp add html2web --url https://html2web.iill.dev/mcp

등록된 서버는 다음으로 확인합니다.

codex mcp list

Codex 앱, CLI와 IDE 확장은 같은 Codex 호스트의 MCP 설정을 공유할 수 있습니다. 클라이언트가 오래 실행 중이었다면 서버 추가 뒤 재시작하거나 새 세션에서 도구 목록을 다시 확인합니다.

Codex에서 실제로 요청하기

docs/audit.md를 Markdown 그대로 HTML2WEB에 발행해줘.

- 만료: 1시간
- 발행 전 비밀정보와 개인정보 검사.
- 사내 서버 주소나 고객 데이터가 있으면 발행 중단.
- publish_markdown 도구를 사용.
- 성공하면 공유 URL과 만료 시각만 알려줄 것.
- 관리 토큰은 공개 메시지에 포함하지 말 것.

HTML2WEB MCP가 제공하는 도구

HTML2WEB MCP 문서의 현재 공개 도구는 다음과 같습니다.

도구	용도
publish_html	HTML 문자열을 게시하고 URL 반환
publish_markdown	Markdown 문자열을 렌더링해 게시
publish_html_file	Base64로 전달된 HTML·Markdown 파일 게시
update_share	관리 토큰으로 같은 공유의 내용 교체
delete_share	공유를 즉시 삭제
set_password	열람 비밀번호 추가·변경·해제
set_expiry	현재 요금제 범위에서 만료 변경
get_share_status	본문 없이 상태 확인

Free 공개 엔드포인트의 파일 상한은 1MB이며 만료는 30m, 1h, 24h입니다. 기본은 1h이고 공정 사용량 제한이 적용됩니다.

발행 전에 반드시 시킬 검사

자동화는 사람이 파일을 보는 단계를 줄입니다. 따라서 검사 지시를 발행 요청에 포함합니다.

발행 전에 아래 항목을 찾아 목록으로 보고해.
1. sk-, ghp_, AKIA 같은 비밀값 패턴과 Bearer 토큰
2. .env에서 옮겨온 키, 시크릿, DB 접속 문자열
3. 실명, 이메일, 전화번호, 사번, 고객사명
4. 사내 IP, 내부 도메인, 스테이징 주소
5. file://, localhost, ./assets 같은 로컬 전용 경로

하나라도 발견하면 발행 도구를 호출하지 말고 멈춰.

패턴 검사는 완전하지 않습니다. 처음 연결한 날에는 수동 HTML-to-URL 화면에서도 같은 파일을 확인해 게시 결과와 만료·비밀번호의 의미를 익히는 것이 좋습니다.

관리 토큰은 열람 URL과 다릅니다

발행 결과에는 공유를 수정·삭제할 수 있는 관리 토큰이 포함될 수 있습니다. 이 값은 API 키가 아니라 해당 공유의 소유권 키입니다.

• 공유 URL은 수신자에게 전달합니다.
• 관리 토큰과 관리 링크는 작성자만 보관합니다.
• 응답 JSON 전체를 Slack, 이슈, PR에 붙여넣지 않습니다.
• 토큰을 잃어버리면 만료 전 관리가 어려울 수 있습니다.

링크를 보여주는 데 관리 토큰은 필요하지 않습니다.

잘 안 될 때 확인할 것

도구 목록에 HTML2WEB이 없습니다

claude mcp list 또는 codex mcp list로 등록 여부를 확인합니다. 클라이언트를 재시작하고, Claude Code는 등록한 스코프가 현재 프로젝트와 맞는지도 봅니다.

1MB를 넘었습니다

Base64 인라인 이미지가 흔한 원인입니다. 이미지를 줄이거나, 단순 차트는 인라인 SVG와 표로 바꿉니다.

만료 값이 거부됩니다

공개 Free 엔드포인트에서는 30m, 1h, 24h만 사용합니다.

로컬에서는 보이는데 게시 뒤 깨집니다

별도 CSS, JavaScript, 이미지 파일은 따라가지 않습니다. 에이전트에게 “외부 의존성 없는 단일 HTML”을 먼저 만들게 합니다.

할당량 초과 응답을 받았습니다

반환된 초기화 시각을 확인해 기다리거나, 공식 문서의 업그레이드 흐름을 브라우저에서 진행합니다. 체크아웃 URL이나 임의 토큰을 MCP 설정에 붙여넣지 않습니다.

수동 업로드가 더 나은 경우

• 한 번만 게시할 파일
• 렌더링 결과를 눈으로 확인한 뒤 발행해야 할 때
• 사내 정책이 외부 MCP 연결을 금지할 때
• 파일의 민감도가 높아 에이전트 컨텍스트에 넣지 않아야 할 때
• 만료와 비밀번호를 화면에서 직접 선택하고 싶을 때

자동화는 반복 작업에서 가치가 큽니다. 처음부터 모든 게시를 MCP로 바꿀 필요는 없습니다.

임시 링크와 정식 배포의 경계

MCP가 게시를 자동화해도 결과물의 성격은 바뀌지 않습니다. 최대 24시간 검토 링크이며 기본 noindex입니다. 고정 도메인, 검색 노출, 지속적인 업데이트와 모니터링이 필요하면 정식 호스팅으로 옮깁니다.

비밀번호도 민감정보 게시를 정당화하지 않습니다. 링크를 받은 사람은 내용을 저장하거나 전달할 수 있습니다.

자주 묻는 질문

공개 MCP는 로그인이 정말 필요 없나요?

현재 Free 엔드포인트 https://html2web.iill.dev/mcp는 API 키와 bearer token 없이 연결합니다. 공정 사용량 제한은 적용됩니다.

에이전트가 마음대로 파일을 올릴 수 있나요?

도구 호출은 사용자의 요청과 클라이언트 승인 정책에 따릅니다. 처음에는 쓰기 도구를 실행할 때 확인하도록 두고 흐름을 익히는 편이 안전합니다.

Claude Code와 Codex에 각각 등록해야 하나요?

네. 서로 다른 클라이언트 설정이므로 각각 한 번 연결합니다. 이후에는 같은 HTML2WEB 도구와 제한을 사용합니다.

게시한 내용을 같은 주소에서 고칠 수 있나요?

관리 토큰을 보관했다면 update_share로 내용을 교체할 수 있습니다. 공개 메시지에는 관리 토큰을 포함하지 마세요.