> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/external-link/model-context-protocol/migration.md).

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

기존에 로컬 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 — 로컬 서버**:

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

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

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

**After — 로컬 서버**: 

```json
{
  "mcpServers": {
    
  }
}
```

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

* **claude.ai 웹**: 좌측 사이드바 **사용자 지정** → **커넥터** → **+** → **커스텀 커넥터 추가** → 원격 MCP 서버 URL `https://mcp.hackle.io/mcp` → 인증 화면에서 Hackle API 키 입력. 자세한 절차는 [claude.ai 웹 연동](https://docs.hackle.io/external-link/model-context-protocol/claude-ai-web) 참고.\
  [바로연결](https://claude.ai/customize/connectors?modal=add-custom-connector)
* **Claude Desktop**: 동일한 흐름.

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

#### 3. 연동 확인

새 대화에서:

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

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

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

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

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

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

```bash
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 키를 그대로 써도 되나요?** 네, 기존 키를 그대로 사용할 수 있습니다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hackle.io/external-link/model-context-protocol/migration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.