> 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/claude-code.md).

# Claude Code 연동

Anthropic 의 공식 CLI 인 [Claude Code](https://code.claude.com) 에서 Hackle MCP 를 연결하는 방법입니다.

### 사전 준비

* 최신 버전의 Claude Code
* Hackle API 키 — 발급 방법은 [MCP(Model Context Protocol)](https://docs.hackle.io/external-link/model-context-protocol) 참고

### 방법 A — 인증 흐름으로 추가 (권장)

향후 API 키를 갱신할 때 다시 인증해 처리할 수 있습니다.

#### 1. MCP 서버 등록

```bash
claude mcp add --transport http hackle-mcp https://mcp.hackle.io/mcp
```

기본적으로 현재 프로젝트 로컬에만 등록됩니다. 모든 프로젝트에서 사용하려면:

```bash
claude mcp add --transport http --scope user hackle-mcp https://mcp.hackle.io/mcp
```

#### 2. 인증 트리거

Claude Code 세션 안에서:

```
/mcp
```

`hackle-mcp` 옆에 인증이 필요하다는 표시가 보입니다. 항목을 선택하면 브라우저가 열리고 Hackle 인증 화면이 표시됩니다. **API 키 입력란**에 Hackle API 키를 붙여넣고 진행합니다.

<figure><img src="/files/VcAG6IwY9HdXngzYrb4P" alt=""><figcaption></figcaption></figure>

#### 3. 연결 확인

```
/mcp
```

`hackle-mcp` 상태가 connected 로 표시되면 완료입니다. 새 프롬프트에서 도구를 사용할 수 있습니다.

### 방법 B — 헤더에 API 키 직접 박기

빠르게 구성하려면 헤더를 직접 지정할 수 있습니다. **API 키가 config 파일에 평문으로 저장**되므로 개인 환경에서만 사용하시기를 권장합니다.

```bash
claude mcp add --transport http hackle-mcp https://mcp.hackle.io/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

이 경우 별도 인증 단계 없이 즉시 도구를 사용할 수 있습니다.

### 관리 명령

```bash
claude mcp list              # 등록된 서버 목록
claude mcp get hackle-mcp    # 상세
claude mcp remove hackle-mcp # 제거
```

세션 안에서는 `/mcp` 명령으로 상태 확인과 재인증이 가능합니다.

### 로컬 서버에서 이전

기존에 로컬 MCP 서버(npm 패키지 형태)를 Claude Code 에 등록해 사용하고 계셨다면 다음 단계를 따라 원격 서버로 옮길 수 있습니다.

#### 1. 기존 로컬 서버 제거

```bash
claude mcp list                          # 등록 이름 확인
claude mcp remove hackle-mcp             # 이름이 다르면 그에 맞게 변경
```

#### 2. 원격 서버 등록

위의 **방법 A** 또는 **방법 B** 를 따라 등록합니다. API 키 값은 기존에 쓰던 것 그대로 사용하실 수 있습니다.

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

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

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


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.hackle.io/external-link/model-context-protocol/claude-code.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.