---
slug: desktop-binding
title: "Claude Desktop에서 프로젝트 바인딩 쓰기"
description: "`</> Code`가 곧 Claude Code다. 다만 승인 창을 안 띄워서, 미리 승인하지 않으면 조용히 Main으로 폴백한다."
lang: ko
---


# 16. Claude Desktop에서 프로젝트 바인딩 쓰기

폴더 바인딩은 **Claude Code에서 쓰는 방식**으로 알려져 있다. 그래서 Claude Desktop을
쓰는 사람은 "나는 못 쓰는 것"이라고 넘기기 쉽다. 그렇지 않다.

> **한 줄 요약.** **Desktop의 `</> Code`가 곧 Claude Code다.** 그래서 Desktop에서도
> `.mcp.json` 폴더 바인딩이 그대로 동작한다. 단, **내장 Code는 승인 창을 띄우지 않아서**
> 미리 승인해 두어야 하고, 시작 전에 **저장 대상을 반드시 확인**해야 한다.

폴더 바인딩 자체가 무엇이고 왜 필요한지는 [폴더 바인딩](folder-binding)
에 있다. 이 문서는 **Desktop에 한정된 이야기**만 다룬다.

## 왜 이게 필요한가

저장이 향하는 **Main은 계정 전역 포인터**다. 콘솔에서 한 번 바꾸면 그 계정에 붙은
**모든 클라이언트**가 따라 움직인다. PC의 Desktop도, 웹도, CLI도 같이 움직인다.
대화 도중에 바뀔 수도 있다.

거기서 **벗어나는 유일한 축이 바인딩**이다. `?project=`가 붙은 연결은 자기 프로젝트에
고정돼서, 콘솔에서 Main을 아무리 바꿔도 그 연결의 저장 대상은 움직이지 않는다.

```
계정 Main  ──(전역 포인터)──> 모든 클라이언트가 공유, 언제든 바뀔 수 있음
?project=  ──(연결에 고정)──> 이 연결만은 안 움직임
```

## 1. `</> Code`는 Claude Code다

Claude Desktop 안의 **`</> Code`** 는 별개의 도구가 아니다. **Claude Code가 그대로
들어가 있는 것**이다. 그래서 Claude Code에서 되는 것은 여기서도 된다: 폴더 바인딩도
포함해서.

## 2. 폴더는 하나 이상 고를 수 있다

Desktop은 **작업 폴더를 하나 이상 선택**할 수 있다. 선택한 폴더들이 그 세션의 작업
자리가 된다.

## 3. 고른 폴더에 `.mcp.json`을 둔다

선택한 폴더에 `.mcp.json`을 프로젝트 바인딩으로 만들어 두면 그대로 동작한다. 내용은
Claude Code와 동일하다.

```json
{
  "mcpServers": {
    "AiAkiv": {
      "type": "http",
      "url": "https://mcp.aiakiv.com/mcp?project=내-프로젝트-이름"
    }
  }
}
```

> **프로젝트 이름은 손으로 치지 말고 콘솔에서 복사한다**: **콘솔 → 프로젝트 →
> 프로젝트 관리 → ‘이 프로젝트 MCP 설정’**. 이유와 절차는
> [폴더 바인딩](folder-binding)에 있다.

**폴더를 여러 개 골랐다면 가능하면 맨 처음 폴더에 둔다.** 어느 폴더의 설정이 읽혔는지
헷갈릴 일이 줄어든다.

## 4. ⚠ 미리 승인해 두어야 한다

여기서 가장 많이 막힌다.

**Desktop 내장 Code는 `.mcp.json` 승인 창을 띄우지 않는다.** CLI에서라면 "이 폴더의
MCP 서버를 신뢰하겠습니까" 하고 물어보는데, 내장 쪽에서는 그 창이 안 뜬다. 그리고
승인되지 않은 MCP 서버는 **조용히 건너뛴다**: 오류도 경고도 없이.

그러면 어떻게 되나. AiAkiv 도구는 여전히 보인다. **계정 커넥터(Main)로 폴백**하기
때문이다. 즉 **바인딩만 조용히 사라지고 화면상으로는 멀쩡하다.** 그래서 §8의 확인이
필요하다.

승인해 두는 방법은 두 가지고, **둘 다 같은 파일에 같은 값을 쓴다.**

### 방법 A: 설정 파일에 직접

작업 폴더의 `.claude/settings.local.json` 에 넣는다.

```json
{
  "enableAllProjectMcpServers": true
}
```

이 프로젝트의 MCP 서버를 전부 자동 승인한다는 뜻이다. 서버를 하나씩 지정하고 싶으면
`enabledMcpjsonServers` 에 이름 배열로 적어도 된다.

```json
{
  "enabledMcpjsonServers": ["AiAkiv"]
}
```

### 방법 B: CLI에서 한 번 승인 (권장)

파일을 직접 고치기 싫으면, **그 폴더에서 CLI로 `claude`를 한 번 실행**한다.

```bash
cd 작업폴더
claude
```

`New MCP server found` 프롬프트가 뜬다. 여기서 승인하면 **방금 그 값이 같은
`.claude/settings.local.json` 에 기록된다**: 하나만 승인하면 `enabledMcpjsonServers`
에, 전부 승인하면 `enableAllProjectMcpServers: true` 로.

그래서 **CLI에서 한 번 승인해 두면 이후 Desktop이 그 승인을 그대로 물려받는다.**
방법 A와 결과가 같고, 오타 낼 일이 없다.

> 인증(OAuth)도 이때 같이 끝내 두면 편하다. CLI에서 `/mcp` → `AiAkiv` 선택 →
> 브라우저 로그인. 인증은 **계정 단위로 한 번**이고, 어느 프로젝트로 갈지는
> **폴더의 URL**이 정한다. 로그인은 한 번, 폴더는 여러 개 둘 수 있다
> ([연결 인증](auth)).

## 5. 승인 판정은 이렇게 이뤄진다

순서대로 본다.

| 조건 | 결과 |
|---|---|
| `disabledMcpjsonServers` 에 있음 | **거부** |
| `enabledMcpjsonServers` 에 있음 **또는** `enableAllProjectMcpServers: true` | **승인** |
| 그 외 | **보류**: CLI라면 프롬프트, 내장 Code라면 조용히 건너뜀 |

한 번 거부해 놓은 서버는 `disabledMcpjsonServers` 에 남는다. 승인했는데도 안 붙으면
이쪽에 이름이 남아 있는지 본다.

## 6. 인증이 아예 필요 없는 설정: API 키

여기까지는 **OAuth**로 붙는 설정이었다. 로그인 창이 한 번 뜨고, 그다음부터는 시스템이
알아서 신원을 확인한다.

그런데 **인증 단계 자체가 없는 설정**도 있다. 콘솔에서 **그 프로젝트에 고정된 API 키**를
발급받아 설정에 붙여넣는 방식이다.

```json
{
  "mcpServers": {
    "AiAkiv": {
      "type": "http",
      "url": "https://mcp.aiakiv.com/mcp",
      "headers": { "Authorization": "Bearer <발급받은 키>" }
    }
  }
}
```

> **이 스니펫도 콘솔에서 복사한다.** **프로젝트 관리 → ‘이 프로젝트 MCP 설정’** 에서
> 클라이언트와 형식을 고르면 키가 박힌 채로 나온다. 손으로 치지 않는다.

- **로그인 창이 없다.** 인증이 이미 키 안에 들어 있기 때문이다([연결 인증](auth)).
  `/mcp` 로 인증할 것도, 브라우저를 띄울 것도 없다. **붙여넣으면 바로 쓴다.**
- **프로젝트가 키에 고정된다.** 프로젝트마다 키를 하나씩 발급해 두면 `?project=` 를
  쓰지 않아도 각 설정이 제 프로젝트로 간다. 저장 대상 확인에서는 `binding` 이
  **`"api-key"`** 로 뜬다. 폴더 바인딩과 동형으로, 콘솔에서 Main 을 바꿔도 안 움직인다.
- **승인 프롬프트 문제와도 무관하지 않다.** §4·§5 의 승인은 `.mcp.json` 을 읽을지
  말지의 문제라 키를 쓰더라도 그대로 필요하다. 사라지는 것은 **인증 단계**다.

> **⚠ 키가 곧 신분증이다.** 유출은 **내 기억에 대한 접근이 통째로 넘어가는 것**을
> 뜻한다. 설정 파일을 저장소에 올리지 않는다. 지켜야 할 최소선 전체는
> [연결 인증의 *키 보안*](auth#키-보안).

정리하면 이렇다.

| | OAuth | API 키 |
|---|---|---|
| 인증 | 로그인 창 한 번 | **없음**: 키에 들어 있다 |
| 프로젝트 고정 | `?project=` 로 | **키 자체에** |
| 관리할 비밀값 | 없음 | **키**: 보관 책임이 나에게 |

## 7. ChatGPT · ChatGPT classic 은 붙는 설정이 다르다

여기까지(§1~§6)는 **Claude** 이야기다. **OpenAI 쪽은 갈래가 다르다.**

- **ChatGPT classic** 은 OAuth **계정 커넥터**로 붙는다. 웹에서 한 번 등록하면
  웹·앱 양쪽에서 쓴다.
- **ChatGPT** 는 **OAuth를 쓸 수 없다.** §6의 **프로젝트 고정 API 키**로 붙는다.
- 두 설정은 **함께 두어도 되지만**, 그때는 **MCP 서버 이름을 서로 다르게** 등록해야
  한다(전역 `AiAkiv` / 폴더 `AiAkiv-proj`). 이름이 같으면 어느 쪽을 쓰라고 지목할
  수가 없다.

절차와 주의는 따로 정리해 두었다 → **[ChatGPT 연결](chatgpt)**

## 8. ⚠ 실행 전 반드시 저장 대상을 확인한다

앞서 말한 대로 **바인딩 실패는 소리를 내지 않는다.** 확인하는 것 말고는 알아챌 방법이
없다. 일을 시작하기 전에 AI에게 물어보자.

```
지금 어디에 저장돼?
```

AI가 `get_save_target` 을 부르고 결과를 알려준다. 볼 것은 두 가지다.

- **`binding` 이 `"folder"`**: `?project=` 로 고정됐다는 뜻.
  API 키로 붙였다면 **`"api-key"`** 로 뜬다. 이쪽도 고정된 것이다.
- **프로젝트 이름에 `(Main)` 접미사가 없다**: 접미사가 붙어 있으면 전역 Main을
  따라가는 중이라 **바인딩이 안 걸린 것**이다.

`binding: "main"` 이거나 이름에 `(Main)` 이 붙어 있으면 §4의 승인부터 다시 본다.

> `binding` 이 가질 수 있는 값 전체와 각각의 뜻은
> [폴더 바인딩](folder-binding)의 *제대로 붙었는지 확인하기* 에 있다.

## 자주 겪는 문제

- **도구는 보이는데 엉뚱한 프로젝트에 저장된다.** 승인이 안 돼서 계정 커넥터로
  폴백한 상태다. §4를 확인한다.
- **CLI에서는 되는데 Desktop에서는 안 된다.** CLI는 프롬프트로 승인을 받고 Desktop은
  못 받는다. 바로 이 차이다. CLI에서 한 번 승인해 두면(방법 B) 양쪽 다 된다.
- **폴더를 여러 개 골랐더니 어느 설정이 읽혔는지 모르겠다.** §3대로 최초 폴더에 두고,
  §8로 실제 저장 대상을 확인한다.
- **ChatGPT·ChatGPT classic 에서는 이 절차가 안 맞는다.** 붙는 설정이 달라서다. §7 을 보고
  [ChatGPT 연결](chatgpt) 로 간다.
- **프로젝트 이름을 못 찾는다고 나온다.** 이름은 **본인 소유 프로젝트 중에서만**
  찾는다. 오타이거나 다른 계정의 프로젝트를 적었을 수 있다. 콘솔에서 복사해 넣는다.

## 관련 문서

- 폴더 바인딩이 무엇이고 다른 클라이언트는 어떻게 하나 → [폴더 바인딩](folder-binding)
- ChatGPT·ChatGPT classic 에 연결하기 → [ChatGPT 연결](chatgpt)
- Main·프로젝트·저장 대상의 개념 → [팀과 프로젝트](teams-and-projects)
- 인증(OAuth·API 키) → [연결 인증](auth)
- 콘솔에서 MCP 설정 복사하기 → [콘솔 안내](console)