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

`</> Code`가 곧 Claude Code다. 다만 승인 창을 안 띄워서, 미리 승인하지 않으면 조용히 Main으로 폴백한다.

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

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

폴더 바인딩 자체가 무엇이고 왜 필요한지는 폴더 바인딩 에 있다. 이 문서는 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": {
      "type": "http",
      "url": "https://mcp.aiakiv.com/mcp?project=내-프로젝트-이름"
    }
  }
}

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

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

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

여기서 가장 많이 막힌다.

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

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

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

방법 A: 설정 파일에 직접

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

{
  "enableAllProjectMcpServers": true
}

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

{
  "enabledMcpjsonServers": ["AiAkiv"]
}

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

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

cd 작업폴더
claude

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

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

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

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

순서대로 본다.

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

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

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

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

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

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

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

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

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

정리하면 이렇다.

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

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

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

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

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

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

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

지금 어디에 저장돼?

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

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

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

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

자주 겪는 문제

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

관련 문서

전체 목차 → 문서 이 문서를 마크다운으로