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

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

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

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

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

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

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

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

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

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

Main 프로젝트는 “현재 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 연결.

Claude Desktop의 Code, ChatGPT의 Work처럼 CLI를 감싸는 실행 모드를 쓸 때는, 먼저 CLI로 실행해 승인과 인증까지 끝내 두어야 한다. 감싸는 쪽은 .mcp.json 승인 창을 띄우지 않아서, 승인이 없으면 그 연결을 조용히 건너뛰고 계정 커넥터(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": {
      "type": "http",
      "url": "https://mcp.aiakiv.com/mcp?project=내-프로젝트-이름"
    }
  }
}

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

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

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

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

cd 작업폴더
claude

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

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

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

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

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

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

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

제대로 붙었는지 확인하기

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

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

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

자주 겪는 문제

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

다른 클라이언트

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

관련 문서

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