MCP 서버

에이전트가 hwip_ask를 호출하면 질문이 버튼과 텍스트 입력란으로 폰에 도착하고, 답장은 같은 도구 호출로 돌아와 에이전트가 작업을 이어간다.

@hwip/mcp-server는 이 왕복의 에이전트 쪽이다. 여기에 단방향 알림, 클립보드, 파일, 채널 브로드캐스트, 다른 에이전트 세션으로 보내는 메시지가 더해진다. 전부 Model Context Protocol 위에서 동작하며 Claude Code, Cursor, Windsurf, Gemini CLI와 모든 MCP 클라이언트에서 쓸 수 있다.

iPhone에 Hwip 앱이 로그인되어 있어야 한다. 로그인된 앱이 없으면 아무것도 전송하지 않고 도구가 그렇게 알려준다.

설정

컴퓨터에 있는 에이전트를 한 번에 설정하는 가장 쉬운 방법:

npm install -g @hwip/cli
hwip install

자격 증명을 ~/.hwip/config.json에 저장하고 에이전트를 자동으로 설정한다. MCP 서버는 이 파일을 읽으므로 환경 변수가 필요 없다. Node 18.17 이상이 필요하다. Node 22 이상에서는 hwip_ask가 답이 나오는 즉시 WebSocket으로 받고, 그보다 낮은 버전에서는 폴링한다.

CLI는 전역으로 설치한다. 그래야 hwip cc가 동작하고 훅이 npx 콜드 스타트를 건너뛴다. npx @hwip/cli install은 알림만 쓰는 대안이다. 전체 설치는 CLI를 본다.

Claude Code 수동 설정

서버를 한 번 설치해 두면 세션마다 hwip-mcp 바이너리를 바로 띄운다.

npm install -g @hwip/mcp-server

그다음 ~/.claude/settings.json에 추가한다.

{
  "mcpServers": {
    "hwip": {
      "command": "hwip-mcp"
    }
  }
}

전역 설치 없이 "command": "npx", "args": ["-y", "@hwip/mcp-server"]도 동작한다. 세션마다 패키지를 먼저 해석하므로 시작만 느리다.

env 블록은 필요 없다. 자격 증명은 hwip install이 쓴 ~/.hwip/config.json에서 온다. 파일 값을 덮어쓸 때만 환경 변수를 추가한다. 예를 들어 두 번째 계정:

      "env": { "HWIP_API_KEY": "ak_other_account" }

Cursor와 다른 MCP 클라이언트

{
  "command": "hwip-mcp"
}

전역 설치 없이는 "command": "npx", "args": ["-y", "@hwip/mcp-server"]를 쓴다.

환경 변수

변수	필수	설명
`HWIP_API_KEY`	예*	Settings → API Keys의 API 키
`HWIP_HOOK_ID`	아니오	Hook ID. `hwip_ask`에만 필요
`HWIP_DEVICE_ID`	아니오	`hwip_notify`, `hwip_clipboard`, `hwip_file`의 기본 대상 기기. 호출마다 지정한 `targetDeviceId`가 우선한다. 생략하면 모든 기기로 보낸다. `hwip_ask`는 쓰지 않는다
`HWIP_BASE_URL`	아니오	API 기본 URL (기본값: `https://api.hwip.app/v1`). 리디렉션으로 응답하는 URL은 거부한다. API 키가 실린 요청은 리디렉션을 따라가지 않기 때문이다
`HWIP_WS_URL`	아니오	지원 중단 예정. WebSocket 엔드포인트. `~/.hwip/config.json`의 `wsUrl`이 우선하며 값은 그쪽에 두는 것이 맞다. 파일에 값이 없을 때만 읽는다. 언젠가 읽지 않게 된다
`HWIP_DISABLE_SESSION_CACHE`	아니오	`1` 또는 `true`로 두면 `~/.cache/hwip/`의 세션 ID 인계 파일을 쓰지 않는다. 읽기 전용 파일 시스템, 임시 CI 러너, 파일 쓰기를 감사하는 샌드박스에서 유용하다. 이 값이 없어도 플러그인의 stop 훅은 동작한다
`HWIP_SESSION_ID`	아니오	푸시에 붙는 세션 ID를 덮어쓴다. 앱의 그룹핑을 좌우한다. 비워 두면 가장 최근 Claude Code 트랜스크립트에서 자동 감지한다

* 환경 변수가 없으면 서버는 hwip install 또는 hwip login이 만든 ~/.hwip/config.json을 읽는다. 해석되지 않은 ${...} 치환도 설정되지 않은 것으로 본다.

API 키가 없으면 서버는 시작 시점에 이유를 알리고 멈춘다.

설정 파일

~/.hwip/config.json에는 apiKey, baseUrl, wsUrl, hookId, deviceId가 들어간다. wsUrl을 제외한 모든 키는 환경 변수가 우선한다. 서버는 파일을 읽기 전에 먼저 검사한다.

다른 사용자가 소유했거나 누구나 쓸 수 있으면 파일을 무시하고 stderr에 한 줄 알린다. chmod 600 ~/.hwip/config.json을 실행한다.
그룹이 읽거나 쓸 수 있거나 다른 사용자가 읽을 수 있으면 경고와 함께 사용한다.
파일의 키는 다른 HWIP_BASE_URL을 따라가지 않는다. 변수가 다른 origin을 가리키면 서버는 시작 시 멈추고, HWIP_API_KEY도 함께 설정하거나 변수를 해제하면 진행한다.

API 키 권한

API 키에는 다음 스코프가 필요하다.

push:read — hwip_list
push:write — hwip_notify, hwip_clipboard, hwip_dismiss, hwip_dismiss_all, hwip_file, hwip_agent_send
hook:write — hwip_ask
device:write — hwip_session_rename
channel:read — hwip_channels와 hwip://channels 리소스

hwip_agent_list와 hwip_agent_read는 스코프가 필요 없다. 로컬 hwip CLI를 실행할 뿐 API를 부르지 않는다.

Settings → API Keys에서 MCP 프리셋으로 키를 만들면 알맞은 권한이 붙는다.

암호화

종단간 암호화는 항상 켜져 있고 끄는 스위치가 없다. hwip_notify와 hwip_file은 보내는 내용을 봉인하고, hwip_ask는 질문과 답을 봉인하며, hwip_agent_send는 대상 컴퓨터용으로 메시지를 봉인한다. hwip_clipboard와 hwip_broadcast는 봉인하지 않으므로 비밀 값에 쓰지 않는다.

평문으로 되돌아가는 경로는 없다. 봉인할 수 없는 전송은 아무것도 보내지 않고 이유를 밝힌 오류를 돌려준다. 위협 모델과 한계는 CLI → 암호화에 한 번만 적혀 있다.

이 서버에만 해당하는 두 가지:

키 쌍은 ~/.hwip/device-keys.json에 있고 hwip listener와 공유한다.
이 컴퓨터가 계정의 기기 목록에 없으면, 서버가 첫 봉인 전송 전에 공개 키를 목록에 올린다.