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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

어떤 클라이언트가 되나

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

Gemini CLI는 정적 키(API 키)를 권장한다. OAuth refresh 버그로 프로젝트 전환이 불안정해서다. 콘솔에서 이 프로젝트에 바인딩된 정적 키를 발급해 넣으면 OAuth 없이 이 프로젝트로 고정 저장된다 → 연결 인증.

ChatGPT 는 이 장의 OAuth 폴더 바인딩을 쓸 수 없다. ?project= 로도, X-K2G-Project 헤더로도 붙지 않는다. 폴더에 고정하는 설정은 프로젝트 고정 API 키 하나이고, 그러면 위 표대로 폴더 바인딩과 똑같이 동작한다. 절차는 → ChatGPT 연결. 예전 자료의 Codex 가 지금의 ChatGPT 다.

참고로 예전에는 OAuth 로컬 MCP를 계정 커넥터와 겹쳐 두었을 때 세션 도중 도구가 0개로 떨어지는 현상이 있었다. 지금은 그 조합 자체가 성립하지 않는다(폴더 설정에서는 OAuth 방식이 걸리지 않으므로). ChatGPT의 계정 전체 연결은 플러그인 설치이고 OAuth 로 붙는다. 키 방식은 플러그인 설치와 함께 두어도 되며, 그때는 서버 이름만 서로 다르게 등록한다 → ChatGPT 연결. Claude(Claude Code·Desktop)는 다르다. 이름을 달리해도 AI가 계정 커넥터 쪽을 쓸 수 있다. 그래도 계정 커넥터는 끄지 않는다(끄면 웹과 모바일 앱에서도 꺼진다). AI는 대부분 폴더 연결로 저장하니, 저장 뒤 목적지를 확인한다 → 계정 커넥터와 폴더 연결이 함께 있을 때.

Claude Desktop의 Code, ChatGPT의 Work처럼 CLI를 감싸는 실행 모드를 쓸 때는, 먼저 CLI로 실행해 승인과 인증까지 끝내 두어야 한다. 감싸는 쪽은 .mcp.json 승인 창을 띄우지 않아서, 승인이 없으면 그 연결을 조용히 건너뛰고 계정 커넥터만 남아 Main으로 저장된다. 그리고 Claude는 승인해 둔 상태에서도 계정 커넥터를 함께 붙여서 AiAkiv가 두 개가 된다. 이때 AI는 대부분 폴더 연결로 저장하지만 강제는 아니라서, 가끔 Main으로 갈 수 있다. Desktop 절차는 → Claude Desktop.

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

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

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

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

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

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

지금 어디에 저장돼?

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

Claude에서 폴더 바인딩하기

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

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

{
  "mcpServers": {
    "AiAkiv-myproject": {
      "type": "http",
      "url": "https://mcp.aiakiv.com/mcp?project=myproject"
    }
  }
}

AiAkiv-myproject 는 프로젝트 myproject 의 폴더 연결 이름이다. 폴더 연결은 AiAkiv-<프로젝트 이름> 으로 이름을 붙인다. 계정 커넥터(AiAkiv)와 이름이 달라 "AiAkiv-myproject 로 저장해줘" 처럼 지목할 수 있다. 영문이 아닌 글자가 든 프로젝트 이름을 어떻게 바꾸는지는 ChatGPT 연결의 §4.

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

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

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

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

cd 작업폴더
claude

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

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

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

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

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

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

• Claude CLI: 같은 폴더에서 다시 띄우면 바인딩이 그대로 살아 있다.
• Claude Desktop: 작업 폴더를 여는 방식으로 열면 같은 .mcp.json을 읽는다. 다만 내장 </> Code는 승인 창을 안 띄우므로 미리 승인해 두어야 한다. 계정 커넥터도 함께 붙는데, 끄지 말고 저장 뒤 목적지를 확인한다(→ 계정 커넥터와 폴더 연결이 함께 있을 때). 승인 절차와 확인 방법은 → Claude Desktop.

제대로 붙었는지 확인하기

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

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

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

자주 겪는 문제

• 도구를 부를 때마다 오류가 난다 → URL의 프로젝트 이름이 실제 프로젝트와 다를 때 이렇게 된다. 연결 자체는 성립하지만 모든 도구 호출이 막힌다. 콘솔에서 이름을 다시 복사해 넣는다. (콘솔에서 프로젝트 이름을 바꿨다면 .mcp.json도 같이 고쳐야 한다.)
• 같은 이름의 도구가 두 벌 보인다 → 폴더 바인딩과 계정 단위 커넥터가 동시에 붙은 경우다. 둘은 서로 다른 프로젝트를 가리킨다. 서버가 AI에게 폴더 바인딩 쪽으로 저장하라고 안내해서 대부분 폴더 프로젝트로 가지만, 강제는 아니다. 계정 커넥터는 끄지 말고(끄면 웹과 모바일 앱에서도 꺼진다) 저장 뒤 목적지를 확인한다. 반드시 폴더로만 가야 하면 AiAkiv 콘솔에서 Main을 잠시 꺼 둘 수도 있다(꺼 둔 동안에는 폴더 연결만 동작한다) → 계정 커넥터와 폴더 연결이 함께 있을 때.
• 바인딩을 다른 프로젝트로 바꿨는데 예전 프로젝트로 저장된다 → .mcp.json을 고친 뒤 Claude를 재시작한다. 그래도 그대로면 /mcp에서 다시 인증한다.

다른 클라이언트

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

관련 문서

• 팀·프로젝트가 무엇이고 왜 나누나 → 팀과 프로젝트
• 기대한 기억이 안 보일 때 → 자주 겪는 문제
• 콘솔에서 프로젝트 만들기·연결 URL 복사 → 콘솔 안내
• OAuth와 API 키의 차이·키 보안 → 연결 인증
• Claude에서 AiAkiv가 두 개로 보일 때 → 계정 커넥터와 폴더 연결이 함께 있을 때