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

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

한 줄 요약. Desktop의 </> Code가 곧 Claude Code다. 그래서 Desktop에서도 .mcp.json 폴더 바인딩이 그대로 동작한다. 단, 내장 Code는 승인 창을 띄우지 않아서 미리 승인해 두어야 하고, 시작 전에 저장 대상을 반드시 확인해야 한다. 그리고 claude.ai 계정 커넥터가 함께 붙는다. 끄지 않는다(끄면 웹과 모바일 앱에서도 AiAkiv가 꺼진다). AI는 대부분 폴더 연결로 저장하지만 강제는 아니니, 저장 뒤 목적지를 확인한다.

폴더 바인딩 자체가 무엇이고 왜 필요한지는 폴더 바인딩 에 있다. 이 문서는 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와 동일하다.

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

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

서버 이름은 AiAkiv-<프로젝트 이름> 이다. 위 예시의 AiAkiv-myproject 는 프로젝트 myproject 의 폴더 연결 이름이다. 콘솔에서 복사하거나 폴더 ZIP 받기로 받으면 내 프로젝트 이름이 붙어 나온다. 계정 커넥터(AiAkiv)와 이름이 달라 "AiAkiv-myproject 로 저장해줘" 처럼 지목할 수 있다. 이름을 짓는 규칙과 바꿔 쓰는 법은 ChatGPT 연결의 §4. 이름을 바꾸면 §4의 enabledMcpjsonServers 안 이름도 똑같이 바꾼다.

폴더 ZIP 은 콘솔 ‘이 프로젝트 MCP 설정’ 의 OAuth 탭과 프로젝트 고정 API 키 탭에 있다. 풀어서 폴더를 작업 위치에 두면 .mcp.json, 이 폴더 연결을 미리 승인해 둔 .claude/settings.json, 스킬(.claude/skills/)이 다 들어 있다. API 키 탭의 ZIP 에는 Gemini CLI·Codex CLI 설정과 그쪽 스킬(.agents/skills/)도 들어 있다. 이 화면에 발급한 키가 없으면 버튼이 키를 발급해 넣는다. ZIP 을 받은 뒤 '이 프로젝트용 정적 키 발급'을 누르면 ZIP 안의 키가 폐기된다.

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

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

여기서 가장 많이 막힌다.

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

그러면 어떻게 되나. Claude Code는 폴더 .mcp.json의 서버와 별개로, claude.ai 계정에 등록한 계정 커넥터도 세션에 붙인다. 그래서 실패 모양이 두 가지다. 둘 다 화면상으로는 멀쩡하다.

• 폴더 서버가 승인되지 않았을 때: 폴더 연결은 건너뛰고 계정 커넥터만 남는다. AiAkiv 도구는 여전히 보이지만 저장은 Main으로 간다.
• 폴더 서버를 승인했을 때도: 계정 커넥터가 함께 붙어 AiAkiv가 두 개가 된다. 도구 이름이 똑같아서 어느 쪽으로 저장할지는 AI가 고른다. 서버가 폴더 연결을 우선하라고 안내해서 대부분 폴더 프로젝트로 가지만, 강제는 아니라서 가끔 Main으로 갈 수 있다.

그래서 승인이 먼저 필요하고, 시작 전과 첫 저장 뒤에 §8의 확인이 필요하다. 계정 커넥터는 끄지 않는다. 끄면 계정 전체에서 꺼져 웹과 모바일 앱에서도 AiAkiv가 사라진다(계정 커넥터와 폴더 연결이 함께 있을 때).

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

방법 A: 설정 파일에 직접

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

{
  "enableAllProjectMcpServers": true
}

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

{
  "enabledMcpjsonServers": ["AiAkiv-myproject"]
}

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

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

cd 작업폴더
claude

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

그래서 CLI에서 한 번 승인해 두면 이후 Desktop이 그 승인을 그대로 물려받는다. 방법 A와 결과가 같고, 오타 낼 일이 없다. 다만 승인과 별개로 계정 커넥터가 함께 붙는다(CLI도 마찬가지). 아래 소절을 함께 읽는다.

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

계정 커넥터가 함께 붙을 때

Claude Code(터미널 CLI와 Desktop의 </> Code)는 폴더 .mcp.json의 서버와 별개로 claude.ai 계정 커넥터도 세션에 붙인다. 그래서 폴더 바인딩을 쓰는 세션에는 AiAkiv가 두 개가 된다.

• 계정 커넥터는 끄지 않는다. 입력창의 + 메뉴 → Connectors 에서 끄면 계정 전체에서 꺼져, claude.ai 웹 채팅과 모바일 앱에서도 AiAkiv가 사라진다.
• 두 개인 채로 두면 AI가 폴더 연결을 우선해서 저장한다. 서버가 그렇게 안내한다. 대부분 폴더 프로젝트로 가지만 강제는 아니다.
• 그래서 저장 뒤 목적지를 확인한다(§8). 저장 응답에는 매번 목적지가 들어 있다.
• 저장이 반드시 폴더로만 가야 하면 AiAkiv 콘솔에서 Main을 잠시 꺼 둘 수도 있다. 꺼 둔 동안에는 계정 커넥터가 요청을 거절하고 폴더 연결만 동작한다. 휴대폰과 웹의 AiAkiv도 함께 거절하니, 그쪽에서 쓸 때는 다시 켠다.

Main으로 잘못 갔을 때 할 일, Main 끄기, 터미널에서 그 폴더에서만 계정 커넥터를 막는 설정은 → 계정 커넥터와 폴더 연결이 함께 있을 때.

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

순서대로 본다.

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

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

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

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

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

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

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

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

정리하면 이렇다.

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

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

• ChatGPT와 ChatGPT classic 은 둘 다 앱 안의 플러그인 디렉터리에서 AiAkiv Memory 를 설치해 붙인다. OAuth 로 로그인하고, 한 번 설치하면 계정 전체에 적용돼 웹과 두 앱에서 보인다. 저장은 Main을 따라간다.
• 폴더마다 프로젝트를 고정하려면 ChatGPT 앱에서 폴더의 .codex/config.toml 에 §6과 같은 프로젝트 고정 API 키를 둔다. OAuth 로는 폴더마다 프로젝트를 고정하지 못한다.
• 앱 기능(AI에게 콘솔 관리 같은 앱 일을 시키는 기능)은 공식 ChatGPT 플러그인에서 지원하지 않는다. 쓰려면 Codex 에 설치 프롬프트로 연결하거나 폴더에 API 키로 연결한다.
• 두 설정은 함께 두어도 된다. MCP 서버 이름이 서로 다르기 때문이다(전역 AiAkiv / 폴더 AiAkiv-<프로젝트 이름>, 예: AiAkiv-k2g). 이름이 다르니 어느 쪽을 쓰라고 지목할 수 있다. 이름이 같으면 지목할 수가 없다.
• 폴더 연결 이름은 Claude에서도 같은 규칙(AiAkiv-<프로젝트 이름>)으로 나온다. 다만 Claude는 이름을 달리해도 AI가 계정 커넥터 쪽을 쓸 수 있으니, 계정 커넥터는 그대로 두고 저장 뒤 목적지를 확인한다 → 계정 커넥터와 폴더 연결이 함께 있을 때.
• ChatGPT 데스크톱 앱에서는 두 연결이 함께 보인다. 계정 쪽 연결(AiAkiv 플러그인, Main을 따름)과 폴더 .codex/config.toml 의 폴더 연결을 동시에 인식한다. 폴더 쪽 이름(예: AiAkiv-k2g)을 지목하면 그 프로젝트에 고정된 채로 동작한다. Codex CLI 는 폴더 연결로 동작하고, 폴더를 신뢰해야 설정을 읽는다.

절차와 주의는 따로 정리해 두었다 → ChatGPT 연결

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

앞서 말한 대로 바인딩 실패는 소리를 내지 않는다. 확인하는 것 말고는 알아챌 방법이 없다. 두 가지를 순서대로 확인한다.

먼저, 일을 시작하기 전에 폴더 연결이 붙었는지 본다. /mcp 목록에 폴더 .mcp.json 의 AiAkiv가 있는지 보거나, 저장 대상을 물어본다.

지금 어디에 저장돼?

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

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

계정 커넥터가 함께 붙어 AiAkiv가 두 개라면, 이 답은 어느 연결에 물었느냐에 따라 folder 로도 main 으로도 나온다. 두 개인 것 자체는 문제가 아니다. 다만 목록에 폴더 쪽 AiAkiv가 아예 없고 답이 늘 binding: "main" 이거나 (Main) 이면, 폴더 연결이 붙지 않은 것이니 §4의 승인부터 다시 본다.

그다음, 첫 저장 뒤에 목적지를 본다. 저장 응답에는 매번 목적지 (팀·프로젝트·binding)가 들어 있다. AI가 알려 주는 프로젝트 이름을 보거나 물어본다.

방금 어디에 저장됐어?

binding 이 "folder"(또는 "api-key")이고 이름에 (Main) 이 없으면 폴더 프로젝트로 간 것이다. AI는 대부분 폴더 연결로 저장하지만 강제는 아니라서, 이 확인이 마지막 안전장치다. Main으로 갔다면 → 계정 커넥터와 폴더 연결이 함께 있을 때의 Main으로 잘못 갔을 때.

binding 이 가질 수 있는 값 전체와 각각의 뜻은 폴더 바인딩의 제대로 붙었는지 확인하기 에 있다.

자주 겪는 문제

• 도구는 보이는데 엉뚱한 프로젝트에 저장된다. 두 경우 중 하나다. 폴더 서버가 승인되지 않아 계정 커넥터만 남았거나(§4의 승인을 확인한다), 승인은 됐지만 계정 커넥터가 함께 붙어 AI가 그쪽을 쓴 경우다. 뒤의 경우는 폴더 연결로 다시 저장하고 목적지를 확인한다(→ 계정 커넥터와 폴더 연결이 함께 있을 때).
• CLI에서는 되는데 Desktop에서는 안 된다. CLI는 프롬프트로 승인을 받고 Desktop은 못 받는다. CLI에서 한 번 승인해 두면(방법 B) Desktop도 그 승인을 물려받는다. 다만 CLI에서 폴더별로 계정 커넥터를 막아 둔 설정은 Desktop에 통하지 않는다. Desktop에서는 두 연결이 함께 붙은 채로 쓰고 저장 뒤 목적지를 확인한다(§8).
• Connectors 에서 AiAkiv를 껐더니 웹과 모바일에서도 사라졌다. + 메뉴 → Connectors 는 계정 전체 설정이다. 같은 메뉴에서 다시 켠다.
• 폴더를 여러 개 골랐더니 어느 설정이 읽혔는지 모르겠다. §3대로 최초 폴더에 두고, §8로 실제 저장 대상을 확인한다.
• ChatGPT·ChatGPT classic 에서는 이 절차가 안 맞는다. 붙는 설정이 달라서다. §7 을 보고 ChatGPT 연결 로 간다.
• 프로젝트 이름을 못 찾는다고 나온다. 이름은 본인 소유 프로젝트 중에서만 찾는다. 오타이거나 다른 계정의 프로젝트를 적었을 수 있다. 콘솔에서 복사해 넣는다.

관련 문서

• 폴더 바인딩이 무엇이고 다른 클라이언트는 어떻게 하나 → 폴더 바인딩
• 계정 커넥터가 함께 붙을 때 저장 확인과 바로잡기 → 계정 커넥터와 폴더 연결이 함께 있을 때
• ChatGPT·ChatGPT classic 에 연결하기 → ChatGPT 연결
• Main·프로젝트·저장 대상의 개념 → 팀과 프로젝트
• 인증(OAuth·API 키) → 연결 인증
• 콘솔에서 MCP 설정 복사하기 → 콘솔 안내