MCP 서버
에이전트가 폰에 닿을 수 있도록 @zeph-to/mcp-server를 설정한다.
에이전트가 zeph_ask를 호출하면 질문이 버튼과 텍스트 입력창으로 폰에 도착하고, 답이 같은 도구
호출로 돌아와 에이전트가 하던 일을 계속한다.
@zeph-to/mcp-server는 그 왕복의 에이전트 쪽이며, 단방향 알림·클립보드·파일·채널 브로드캐스트도
함께 제공한다. 전부 Model Context Protocol 위에서 돈다. Claude
Code·Cursor·Windsurf·Gemini CLI를 비롯한 모든 MCP 클라이언트에서 동작한다.
설정
모든 에이전트를 한 번에 설정하는 가장 쉬운 방법:
npm install -g @zeph-to/cli
zeph install자격증명을 ~/.zeph/config.json에 저장하고 에이전트를 자동으로 설정한다. MCP 서버는 그 파일을
읽으므로 환경변수가 필요 없다.
zeph cc가 동작하고 hook이 npx 콜드 스타트를 건너뛰도록 전역 설치를 권한다.
npx @zeph-to/cli install은 알림 전용 대안이다.
Claude Code 수동 설정
~/.claude/settings.json에 추가한다:
{
"mcpServers": {
"zeph": {
"command": "npx",
"args": ["-y", "@zeph-to/mcp-server"]
}
}
}env 블록은 필요 없다 — 자격증명은 zeph install이 쓴 ~/.zeph/config.json에서 온다. 환경변수는
파일을 덮어쓸 때만 넣는다. 예를 들어 두 번째 계정:
"env": { "ZEPH_API_KEY": "ak_other_account" }Cursor 및 다른 MCP 클라이언트
{
"command": "npx",
"args": ["-y", "@zeph-to/mcp-server"]
}환경변수
| 변수 | 필수 | 설명 |
|---|---|---|
ZEPH_API_KEY | 예* | Settings → API Keys에서 발급한 API 키 |
ZEPH_HOOK_ID | 아니오 | Hook ID. 대화형 도구 zeph_ask·zeph_prompt·zeph_input에만 필요하다 |
ZEPH_DEVICE_ID | 아니오 | 대상 디바이스 ID. 역시 대화형 도구에만 필요하다. 비우면 모든 디바이스로 보낸다 |
ZEPH_BASE_URL | 아니오 | API 기본 URL (기본값: https://api.zeph.to/v1) |
ZEPH_WS_URL | 아니오 | hook 응답 빠른 경로용 WebSocket 엔드포인트 — 다음 폴링이 아니라 사용자가 제출하는 즉시 답이 도착한다. 설정하지 않으면 순수 폴링으로 폴백한다. ~/.zeph/config.json의 wsUrl에서도 읽는다 |
ZEPH_DISABLE_SESSION_CACHE | 아니오 | 1 또는 true로 두면 ~/.cache/zeph/ 아래 세션 id 전달 파일을 쓰지 않는다. 읽기 전용 파일시스템, 휘발성 CI 러너, 파일 쓰기를 감사하는 샌드박스에 쓸모 있다. 이것 없이도 플러그인 stop hook은 동작한다 — transcript 경로에서 UUID를 뽑는 것이 주 경로이고, 캐시는 구버전 Claude Code를 위한 폴백이다 |
ZEPH_SESSION_ID | 아니오 | 푸시에 붙는 세션 id를 덮어쓴다. 앱에서의 묶음 단위를 결정한다. 설정하지 않으면 가장 최근 Claude Code transcript에서 자동 감지한다 |
ZEPH_DISABLE_ENCRYPTION | 아니오 | 1 또는 true로 두면 계정이 암호화를 켜 두었어도 푸시 암호화를 끈다. 서버가 실제로 무엇을 받았는지 디버깅할 때 쓰는 로컬 오버라이드다 — 계정이 옵트인하지 않았다면 암호화는 이미 꺼져 있다 |
* 환경변수가 없으면 서버는 zeph install이 만든 ~/.zeph/config.json을 읽는다. 해석되지 않은
${...} 치환도 없는 것으로 취급한다.
API 키 권한
API 키에는 다음 스코프가 필요하다:
push:read—zeph_listpush:write—zeph_notify·zeph_clipboard·zeph_dismiss·zeph_dismiss_all·zeph_filehook:write—zeph_ask·zeph_prompt·zeph_inputdevice:write—zeph_session_renamechannel:read—zeph://channels리소스
올바른 권한을 받으려면 Settings → API Keys에서 MCP 프리셋으로 키를 만든다.
암호화
계정이 켜두었다면 푸시 본문과 파일 첨부는 AES-256-GCM으로 암호화된다. 암호화는 기본값이 꺼짐이고 켜려면 Zeph Pro가 필요하다. 위협 모델과 그 한계는 CLI & SDK → 암호화에 한 번만 정리해 두었다.
이 서버에만 해당하는 것이 둘 있다:
- 키쌍이
~/.zeph/device-keys.json이 아니라~/.config/zeph/device-keys.json에 있다. - 암호화 설정은 시작할 때 한 번 읽는다. 서버가 도는 중에 앱에서 켜면 재시작해야 반영된다.