로컬 서버에서 마이그레이션

기존에 로컬 MCP 서버(npm 패키지 형태)를 사용하고 계셨다면 이 가이드를 따라 원격 서버로 옮길 수 있습니다.

왜 옮겨야 하나요?

• 설치 / 업데이트가 필요 없습니다. npm 패키지 관리, Node.js 버전, 의존성 충돌에서 자유로워집니다.

• 신규 도구는 원격 서버에만 추가됩니다. CRM 통계 분석 등 최근 툴은 로컬 서버에서 사용할 수 없습니다.

• 항상 최신 상태입니다. 서버 측 개선과 버그 수정이 클라이언트 업데이트 없이 즉시 적용됩니다.

핵심 변화

원격 서버는 클라이언트 내 커스텀 커넥터 UI 로 추가합니다. 로컬 서버처럼 claude_desktop_config.json 에 command / args 를 적는 방식이 아니며, 같은 파일에 url 키를 적는 것도 동작하지 않습니다.

항목	로컬 서버	원격 서버
추가 방식	claude_desktop_config.json 의 mcpServers 에 command / args / env 등록	클라이언트의 커스텀 커넥터 추가 UI
API 키 위치	환경 변수 (env.API_KEY)	클라이언트의 인증 화면에 입력

마이그레이션 절차

1. 기존 로컬 서버 설정 제거 (Claude Desktop)

Claude Desktop -> 설정 -> 개발자 -> 구성 편집

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

claude_desktop_config.json 파일을 문서 편집기에서 열고 로컬 Hackle 서버 항목을 제거합니다.

Before — 로컬 서버:

{
  "mcpServers": {
    "hackle-mcp": {
      "command": "npx",
      "args": ["-y", "@hackle-io/hackle-mcp@latest"],
      "env": {
        "API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

위 hackle-mcp 항목을 삭제하고 저장합니다. mcpServers 객체에 다른 서버가 있다면 그것들은 유지합니다.

claude.ai 웹만 사용해오셨다면 이 단계는 해당 없음.

After — 로컬 서버:

{
  "mcpServers": {
    
  }
}

2. 원격 서버를 커넥터로 추가

• claude.ai 웹: 좌측 사이드바 사용자 지정 → 커넥터 → + → 커스텀 커넥터 추가 → 원격 MCP 서버 URL https://mcp.hackle.io/mcp → 인증 화면에서 Hackle API 키 입력. 자세한 절차는 claude.ai 웹 연동 참고. 바로연결

• Claude Desktop: 동일한 흐름.

API 키 값은 기존에 쓰던 것 그대로 사용하실 수 있습니다.

3. 연동 확인

새 대화에서:

사용 가능한 Hackle 도구를 알려줘

응답에 도구 이름이 포함되면 마이그레이션 완료입니다.

로컬 서버 패키지 정리 (선택)

전역 설치한 npm 패키지가 있다면 제거합니다.

npm uninstall -g @hackle-io/hackle-mcp

npx -y 로 실행하던 경우는 캐시 정리만 해도 됩니다.

npx clear-npx-cache

도구 호환성

원격 서버는 로컬 서버의 모든 도구를 포함하며, 신규 도메인이 추가되어 있습니다.

도메인	로컬 서버	원격 서버
Experiment (A/B 테스트)	✅	✅
In-App Message	✅	✅
Push Message	✅	✅
Auto Metrics (DAU / Retention / Stickiness)	✅	✅
Analytics (데이터 리포트 / 차트)	✅	✅
Remote Config	✅	✅
Text Message	—	✅
Kakao Message	—	✅
In-App Message 통계	—	✅
Push Message 통계	—	✅
Text Message 통계	—	✅
Kakao Message 통계	—	✅

기존 프롬프트는 그대로 사용할 수 있습니다. 도구 이름은 변경되지 않았습니다.

자주 묻는 질문

로컬 서버는 언제까지 동작하나요? 신규 기능과 도구는 원격 서버에만 추가되므로 가능한 시점에 이전하시기를 권장합니다. 로컬 MCP 서버는 더이상 업데이트 되지 않으므로 2026년 하반기내에 지원이 종료될 예정입니다.

원격 서버로 옮기면 데이터가 외부로 전송되나요? 원격 서버는 Hackle 인프라에서 운영됩니다. AI 클라이언트의 요청은 Hackle MCP 서버를 통해 워크스페이스 데이터를 조회하고 응답하며, 별도의 외부 시스템을 거치지 않습니다.

기존 API 키를 그대로 써도 되나요? 네, 기존 키를 그대로 사용할 수 있습니다.