---
slug: folder-binding
title: "폴더 바인딩: 작업 폴더마다 저장 대상을 고정하기"
description: "폴더에 프로젝트를 못 박으면 전환 사고가 구조적으로 사라진다. 클라이언트별 절차와 `binding` 값 읽는 법."
lang: ko
---


# 12. 폴더 바인딩: 작업 폴더마다 저장 대상을 고정하기

프로젝트를 여러 개 오가며 일하면 **전환을 잊고 엉뚱한 프로젝트에 저장하는 사고**가
가장 흔하다. 폴더 바인딩은 그 사고를 구조적으로 없앤다. **작업 폴더에 프로젝트를
못 박아 두면**, 그 폴더에서 실행한 AI는 언제나 그 프로젝트로만 읽고 쓴다.

> 개념(프로젝트 · Main · 폴더 프로젝트)부터 클라이언트별 설정 절차까지 모은다.
> 단계별 절차는 지금 **Claude** 편이 가장 자세하고, 나머지는 콘솔의 “이 프로젝트
> MCP 설정” 안내를 따르면 된다. 앱 화면은 버전마다 바뀌지만 **콘솔이 주는 설정은
> 항상 지금 것**이다.

## 먼저: 프로젝트 · Main · 폴더 프로젝트

폴더 바인딩을 이해하려면 **세 층**을 순서대로 잡아야 한다.

### 1층. 프로젝트 = 메모리로 들어가는 통로

프로젝트는 기억을 따로 담는 창고가 **아니다.** 이미 팀이 소유한 메모리에 **읽고
쓰기 위해 지나가는 문**이다([팀과 프로젝트](teams-and-projects)).

여기서 두 가지가 따라 나온다.

- **다른 메모리에 쓰려면 프로젝트도 달라야 한다.** 통로가 곧 목적지를 정하기
  때문이다. 프로젝트 하나로 이 메모리 저 메모리를 골라 쓸 수는 없다.
- **한 메모리에 프로젝트를 여러 개 둘 수 있다.** 메모리 안을 서브 파트(도메인·그룹)
  로 나눠 뒀다면, 같은 팀 메모리를 향하되 **들어가는 칸이 다른 통로**를 여러 개
  만들 수 있다. 통로마다 **페르소나**(그 통로에서 AI가 맡을 역할)도 따로 줄 수 있다.

### 2층. Main = 지금 내 AI가 쓰고 있는 통로

**Main 프로젝트는 “현재 AI가 사용하는 프로젝트”** 다. 계정에 **하나뿐**이고, 바꾸는
것은 **사람이 콘솔에서만** 한다. AI는 스스로 바꾸지 못한다(프롬프트 인젝션으로
저장 위치가 납치되는 것을 막는 불변식).

폴더에 묶이지 않은 모든 연결(웹 앱 등)은 이 **하나의 Main을 함께 따라간다.**

### 3층. 폴더 프로젝트 = 폴더에 통로를 못 박기

프로젝트를 여러 개 오가며 일하면 **Main을 계속 바꿔 가며 써야 해서 불편하고, 전환을
잊으면 엉뚱한 프로젝트에 저장되는 사고**가 난다.

**클라이언트가 지원한다면**, 작업 폴더에 프로젝트를 **못 박아 둘 수 있다.** 그
폴더에서 실행한 AI는 언제나 그 프로젝트로만 읽고 쓴다. Main을 건드리지 않고, Main이
바뀌어도 이 폴더는 그대로다. 전환 사고가 **구조적으로** 사라진다.

## 메인 프로젝트(Main)와 무엇이 다른가

| | 메인 프로젝트(Main) | 폴더 바인딩 |
|---|---|---|
| 범위 | 계정당 하나: 바인딩 없는 모든 클라이언트가 공유 | 그 폴더의 연결 하나만 |
| 바뀌는 시점 | 콘솔에서 전환하면 즉시, 대화 도중에도 | 설정 파일을 고치기 전까지 안 바뀜 |
| 전환 사고 | 잊으면 엉뚱한 곳에 저장 | 구조적으로 안 생김 |

둘은 **서로 간섭하지 않는다.** 폴더 바인딩은 그 연결의 저장 경로만 정할 뿐,
계정의 Main을 건드리지 않는다. 반대로 콘솔에서 Main을 바꿔도 바인딩된 폴더는
그대로다.

---

## 어떤 클라이언트가 되나

폴더 바인딩은 **클라이언트가 폴더 설정을 읽어야** 가능하다. 웹 앱은 폴더라는 개념
자체가 없어 언제나 Main을 따라간다.

| 클라이언트 | 폴더 바인딩 | 설정 파일 |
|---|---|---|
| **Claude Code** | ✅ | `.mcp.json` |
| **Gemini CLI** | ✅ | `.gemini/settings.json` (정적 키 권장: 아래 참고) |
| **Cursor** | ✅ | `.cursor/mcp.json` |
| **Claude Desktop** | ✅ (`</> Code` = Claude Code) | `.mcp.json`: [Claude Desktop](desktop-binding) 참고 |
| **ChatGPT** | ✅ **API 키로만** (OAuth 불가) | `.codex/config.toml`: [ChatGPT 연결](chatgpt) 참고 |
| ChatGPT classic · Claude Web · Grok | ❌ (Main을 따라감) | - |

> **Gemini CLI는 정적 키(API 키)를 권장한다.** OAuth refresh 버그로 프로젝트 전환이
> 불안정해서다. 콘솔에서 이 프로젝트에 바인딩된 정적 키를 발급해 넣으면 OAuth 없이
> 이 프로젝트로 고정 저장된다 → [연결 인증](auth).
>
> **ChatGPT 는 이 장의 OAuth 폴더 바인딩을 쓸 수 없다.** `?project=` 로도,
> `X-K2G-Project` 헤더로도 붙지 않는다. 폴더에 고정하는 설정은 **프로젝트 고정 API 키**
> 하나이고, 그러면 위 표대로 폴더 바인딩과 똑같이 동작한다. 절차는
> → [ChatGPT 연결](chatgpt). 예전 자료의 **Codex** 가 지금의
> ChatGPT 다.
>
> 참고로 예전에는 **OAuth 로컬 MCP를 계정 커넥터와 겹쳐 두었을 때** 세션 도중 도구가
> 0개로 떨어지는 현상이 있었다. 지금은 그 조합 자체가 성립하지 않는다(OAuth가 안
> 되므로). **키 방식은 계정 커넥터와 함께 두어도 되며**, 그때는 서버 이름만 서로
> 다르게 등록한다 → [ChatGPT 연결](chatgpt).
>
> **Claude Desktop의 Code, ChatGPT의 Work처럼 CLI를 감싸는 실행 모드**를 쓸 때는,
> **먼저 CLI로 실행해 승인과 인증까지 끝내 두어야** 한다. 감싸는 쪽은 `.mcp.json`
> 승인 창을 띄우지 않아서, 승인이 없으면 그 연결을 **조용히 건너뛰고 계정
> 커넥터(Main)로 폴백**한다. Desktop 절차는 → [Claude Desktop](desktop-binding).

## 콘솔이 시키는 대로 하면 된다

설정 내용을 손으로 쓸 필요가 없다. **콘솔 → 프로젝트 관리 → “이 프로젝트 MCP 설정”**
에 형식별 탭이 있고, 각 탭이 **어떤 AI에 쓰는지·어디에 저장하는지**를 함께 알려준다.

1. 콘솔에서 바인딩할 **프로젝트**를 연다.
2. **“이 프로젝트 MCP 설정”** 에서 내 클라이언트에 맞는 **형식 탭**을 고른다.
3. 내용을 복사해 **작업 폴더 루트**에 그 파일 이름으로 저장한다.
4. **그 폴더에서 AI를 실행하고 인증**한다.
   **API 키 방식이면 인증 단계가 없다**: 키에 이미 인증이 들어 있기 때문이다
   ([연결 인증](auth)).

프로젝트 이름을 직접 타이핑하지 않는 것이 중요하다. 이름에 공백·한글이 들어가면 URL
인코딩이 필요한데, 복사한 설정에는 그것이 이미 반영돼 있다.

## ⚠ 시작 전에 저장 대상을 확인한다

폴더 바인딩을 쓴다면, **작업을 시작하기 전에 AI에게 먼저 물어보는 습관**을 들이자.

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

팀·프로젝트를 그대로 알려준다. 바인딩은 **조용히 어긋나 있어도 화면에 티가 나지
않기** 때문에, 확인하고 시작하는 한 번이 잘못 쌓인 기억을 나중에 찾아내는 비용보다
훨씬 싸다. 확인 방법은 아래 [제대로 붙었는지 확인하기](#제대로-붙었는지-확인하기)
참고.

---

## Claude에서 폴더 바인딩하기

### 1. 폴더에 `.mcp.json`을 만든다

작업 폴더 최상단에 `.mcp.json` 파일을 만들고, 바인딩할 프로젝트 이름을 URL의
`project=` 뒤에 적는다.

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

이미 `.mcp.json`이 있다면 `mcpServers` 안에 `"AiAkiv"` 항목만 추가하면 된다.

> 위 내용을 손으로 쓰지 말고 **콘솔 → 프로젝트 → 프로젝트 관리**에서 복사한다
> (이유는 [콘솔이 시키는 대로 하면 된다](#콘솔이-시키는-대로-하면-된다)).

### 2. 그 폴더에서 Claude CLI를 실행한다

`.mcp.json`은 **실행한 폴더** 기준으로 읽힌다. 다른 곳에서 띄우면 이 설정이 안
잡힌다.

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

처음 실행하면 이 폴더의 MCP 설정을 신뢰할지 한 번 물어본다. 승인해야 연결된다.

### 3. `/mcp`로 AiAkiv에 로그인한다

Claude CLI 안에서 **`/mcp`** 를 입력하면 연결된 MCP 서버 목록이 나온다. 거기서
`AiAkiv`를 골라 인증하면 브라우저가 열리고, 로그인하면 연결이 끝난다.

인증은 **계정 단위로 한 번**이지만, 어떤 프로젝트로 갈지는 **폴더의 URL**이
정한다. 즉 로그인은 한 번, 폴더는 여러 개 둘 수 있다.

> **화면 문구는 버전에 따라 다르다.** 메뉴 항목 이름이나 순서가 위와 달라도, 할 일은
> 언제나 같다. **`/mcp` → `AiAkiv` 선택 → 브라우저 로그인.** 이 세 걸음만 맞으면 된다.

### 4. 이후에는 그냥 쓰면 된다

- **Claude CLI**: 같은 폴더에서 다시 띄우면 바인딩이 그대로 살아 있다.
- **Claude Desktop**: 작업 폴더를 여는 방식으로 열면 같은 `.mcp.json`을 읽는다.
  다만 내장 `</> Code`는 **승인 창을 안 띄우므로 미리 승인**해 두어야 한다. 절차와
  확인 방법은 → [Claude Desktop](desktop-binding).

---

## 제대로 붙었는지 확인하기

**저장 대상 확인** 도구에게 물어보면 된다("지금 어디에 저장돼?"). 응답의 **`binding`**
한 값이 지금 무엇에 고정돼 있는지를 말해 준다.

| `binding` | 뜻 | 콘솔에서 Main을 바꾸면 |
|---|---|---|
| **`folder`** | `?project=` 폴더 바인딩 | **안 움직인다** |
| **`api-key`** | 프로젝트 고정 키: 좌표가 키에 동결 → [연결 인증](auth) | **안 움직인다** |
| `main` | 바인딩 없음. 계정 전역 Main을 따라간다 | **따라 움직인다** (대화 도중에도) |
| `public-read` | 공개 메모리를 읽는 중: **저장이 막힌다** → [공개 메모리](public-memory) | - |
| `link-read` | 연결된 상대 팀을 읽는 문맥 → [연결](links) | - |
| (없음) | 자체 호스팅 단일 사용자: 판정 대상이 아니다 | - |

위 두 줄이면 바인딩이 걸린 것이다. **프로젝트 이름도 단서다**: 이름 뒤에
**`(Main)`이 붙어 있으면** 바인딩이 아니라 계정 Main을 따라가는 중이다.

이 확인은 읽기 전용이고 값이 싸다. 대화를 시작할 때, 저장하기 전에, 저장 위치를
말하기 전에 **자주 물어보는 편이 낫다**: 엉뚱한 프로젝트에 쌓인 기억을 나중에
찾아내는 비용이 훨씬 크다.

## 자주 겪는 문제

- **도구를 부를 때마다 오류가 난다** → URL의 프로젝트 이름이 실제 프로젝트와 다를
  때 이렇게 된다. 연결 자체는 성립하지만 모든 도구 호출이 막힌다. 콘솔에서 이름을
  다시 복사해 넣는다. (콘솔에서 프로젝트 이름을 바꿨다면 `.mcp.json`도 같이 고쳐야
  한다.)
- **같은 이름의 도구가 두 벌 보인다** → 폴더 바인딩과 계정 단위 커넥터가 동시에
  붙은 경우다. 둘은 서로 다른 프로젝트를 가리킬 수 있으니 **한 대화에서 섞어 쓰지
  않는다.** 폴더 바인딩 쪽이 더 구체적인 의도이므로 그쪽을 쓴다.
- **바인딩을 다른 프로젝트로 바꿨는데 예전 프로젝트로 저장된다** → `.mcp.json`을
  고친 뒤 Claude를 재시작한다. 그래도 그대로면 `/mcp`에서 다시 인증한다.

## 다른 클라이언트

지원 여부는 위 [어떤 클라이언트가 되나](#어떤-클라이언트가-되나) 표를 따른다.
클라이언트별 상세 절차는 확인되는 대로 이 문서에 추가한다. 그전까지는 콘솔의
**“이 프로젝트 MCP 설정”** 탭 안내가 가장 정확하다(형식·저장 위치가 함께 나온다).

## 관련 문서

- 팀·프로젝트가 무엇이고 왜 나누나 → [팀과 프로젝트](teams-and-projects)
- 기대한 기억이 안 보일 때 → [자주 겪는 문제](faq)
- 콘솔에서 프로젝트 만들기·연결 URL 복사 → [콘솔 안내](console)
- OAuth와 API 키의 차이·키 보안 → [연결 인증](auth)