← 블로그

Claude Code로 10분 만에 실시간 WebSocket 추가하기

· Hibira

Claude Code를 Hibira MCP 서버에 연결해 앱 생성, .env 작성, pusher-js 연결, 첫 이벤트 도착 확인까지 맡겨 보세요.

앱에 실시간 기능을 넣는 일은 대부분 배선 작업입니다. 인증 정보를 만들고, 올바른 env 파일에 넣고, 클라이언트 라이브러리를 설정하고, 비공개 채널을 인가한 다음, 이벤트가 정말 도착하는지 확인합니다. 서비스에 접근만 할 수 있다면 AI 코딩 에이전트가 가장 잘하는 종류의 일입니다. Hibira MCP 서버가 그 접근을 열어 줍니다.

이 글은 Claude Code로 설명합니다. Cursor, VS Code, Claude, ChatGPT도 방법은 같고, 각각의 설정은 MCP 서버 페이지에 있습니다.

에이전트가 할 수 있는 일

Hibira는 Model Context Protocol로 아홉 가지 도구를 제공합니다. 에이전트는 플랜과 앱 조회, 앱 생성과 수정, 사용량 확인, 테스트 이벤트 전송, 디버그 콘솔 확인을 할 수 있고, 사용하는 프레임워크의 연동 가이드를 앱 ID와 키가 채워진 상태로 가져올 수 있습니다. 앱을 삭제하거나 시크릿을 교체할 수는 없으며, 기존 앱의 시크릿은 절대 보지 못합니다.

1단계: 서버 추가하기

Hibira 계정이 필요합니다. 무료 플랜이면 충분합니다. 프로젝트 폴더에서 다음을 실행하세요.

claude mcp add --transport http hibira https://hibira.io/mcp

Claude Code가 이 서버를 처음 사용할 때 브라우저에 Hibira 페이지가 열립니다. 로그인한 뒤 읽기 전용 또는 읽기 및 쓰기를 고르고 승인하세요. 자동으로 열리지 않으면 Claude Code에서 /mcp를 실행하고 hibira 서버 인증을 선택합니다. 새 앱을 만들려면 쓰기 권한이 필요합니다.

2단계: 원하는 것을 말하기

기술 스택과 실행 환경을 구체적으로 알려 주세요. Vite 프런트엔드를 쓰는 Laravel 앱이라면 이렇게 요청합니다.

이 Laravel 앱에 Hibira 실시간 기능을 추가해 줘. http://localhost:5173을 허용하는 "shop-dev"라는 앱을 만들고, 키를 .env에 넣고, Laravel Echo를 설정하고, 비공개 orders 채널로 OrderShipped를 브로드캐스트해 줘.

그다음은 에이전트가 스스로 계획하지만, 보통 이렇게 진행됩니다.

  1. get_account로 플랜과 WebSocket 호스트를 확인합니다.
  2. create_app으로 지정한 이름과 허용 오리진을 가진 앱을 만듭니다. 시크릿은 한 번만 반환되며, 도구는 git이 무시하는 .env에 바로 쓰라고 에이전트에게 알려 줍니다.
  3. get_integration_guide로 laravel 가이드를 가져옵니다. Echo 설정, .env 키, 비공개 채널 절차가 여러분의 값이 채워진 채로 돌아옵니다.
  4. .env, config/broadcasting.php, resources/js/echo.js, routes/channels.php를 수정하고 브로드캐스트 이벤트를 새로 만듭니다.

다른 변경과 마찬가지로 diff를 검토하세요. 수정 내용은 평범한 Laravel 코드이며, 이후 코드가 에이전트에 의존하는 부분은 없습니다.

3단계: 이벤트 도착 확인하기

여기서 디버그 콘솔이 제 역할을 합니다. 이렇게 물어보세요.

브라우저에서 앱을 열고, private-orders.1로 테스트 OrderShipped 이벤트를 보낸 다음 구독자가 받았는지 알려 줘.

에이전트는 send_test_event를 호출해 서버가 하듯 이벤트를 발행하고, watch_debug_events로 앱의 디버그 콘솔을 최대 30초 동안 지켜보며 연결, 구독, 메시지를 보고합니다. 아무도 구독하지 않았다면 그것도 알 수 있는데, 대개 인증 엔드포인트나 허용 오리진이 원인입니다.

무료 플랜의 디버그 콘솔에는 연결, 구독, 발행된 메시지가 표시되고, 유료 플랜에는 클라이언트 이벤트, 웹훅, 오류가 추가됩니다.

일상적인 질문에도

연결해 두면 설정 이후에도 쓸모가 있습니다.

  • "내 앱들이 일일 메시지 한도에 얼마나 가까워?"에는 get_usage를 씁니다.
  • "staging.example.com의 브라우저가 왜 거부돼?"에는 get_app으로 허용 오리진을 읽고, 동의하면 update_app으로 고칩니다.
  • "입력 중 표시가 되도록 shop-dev의 클라이언트 이벤트를 켜 줘"는 update_app 한 번이면 됩니다.

안전하게 쓰기

  • 가능하면 읽기 전용으로. 설정하는 동안에는 읽기 및 쓰기를, 평소 질문에는 읽기 전용을 허용하세요.
  • 브라우저가 없는 에이전트는 토큰으로. CI 작업과 원격 에이전트는 로그인 대신 개인 액세스 토큰을 쓸 수 있습니다. AI 에이전트 페이지에서 만들고, 앱 하나로 제한하고, 만료일을 지정하세요.
claude mcp add --transport http hibira https://hibira.io/mcp \
  --header "Authorization: Bearer hkb_pat_..."
  • 언제든 취소할 수 있습니다. AI 에이전트 페이지에 연결된 모든 에이전트와 토큰이 표시되고, 취소는 즉시 적용됩니다.
  • 테스트 이벤트도 실제 메시지입니다. 다른 발행과 똑같이 플랜의 일일 한도에 포함되며, 계정당 초당 몇 건까지만 보낼 수 있습니다.

직접 해 보기

무료 플랜에 가입하고 서버를 추가한 다음, 사용하는 프레임워크 연결을 에이전트에게 맡겨 보세요. 막히면 연동 가이드에 같은 설정을 손으로 하는 방법이 있습니다.