🔌 레슨

관리·공유 — .mcp.json과 스코프

나만 쓸 건지 팀이 쓸 건지. MCP 설정이 어디 저장되고 어떻게 공유되는지.

① 오늘의 미션

전화선이 너무 많아졌어요

지난 레슨에서 반찬가게 작업방에 Slack·Gmail·Notion 커넥터를 줄줄이 연결했죠. 그런데 옆자리 동료가 묻습니다 — "그 연결, 나도 똑같이 써야 하는데… 내 컴퓨터엔 왜 없어?"

오늘은 이 전화선들의 가설 대장(臺帳)을 정리합니다. 어디에 적어두면 나만 쓰고, 어디에 적으면 팀 전체가 쓰는지 — MCP의 스코프(scope) 이야기예요.

설명을 따라 진행하면, 여기서 직접 쳐보게 돼요 👇

~/my-shop

$ _

📚 「관리·공유 — .mcp.json과 스코프」 레슨 내용 전체 텍스트로 훑어보기

전화선이 너무 많아졌어요

내 노트북에서 반찬가게 폴더에 Notion 커넥터를 추가했어요. 같은 깃 저장소를 받은 동료의 노트북에도 그 연결이 저절로 생길까요?

정답이에요. 핵심은 스코프예요. 연결을 추가할 때 어느 칸에 적느냐에 따라 나만 쓰기도 하고, 동료에게도 공유되기도 해요. 그 세 칸을 지금 봅니다.

MCP 연결을 적어두는 장부엔 세 개의 칸이 있어요. 누가 보게 되느냐가 다 달라요.

세 스코프

· local (기본) — 나만, 이 반찬가게 폴더에서만. 다른 폴더로 가면 없음
· project — 팀 공유. 폴더 안 .mcp.json 파일에 적혀 깃으로 함께 배포됨
· user — 나만, 단 내 모든 폴더에서. 가게든 블로그든 어디서나 따라옴

한 줄로: local=여기 나만 / project=여기 팀 모두 / user=어디서나 나만. 고를 땐 명령에 --scope local|project|user를 붙여요(안 붙이면 local).

Notion은 가게 폴더뿐 아니라 어디서든 쓰고 싶어요. 그럼 user 스코프로 추가해요. 명령 옵션은 서버 이름 앞에 옵니다.

claude mcp add --scope user notion --transport http https://mcp.notion.com/mcp — 내 모든 폴더에서 쓸 Notion 연결을 user 스코프로 추가해요

이제 가게 폴더를 벗어나 다른 작업을 해도 Notion 연결이 따라와요. 나 개인용이라 동료에겐 공유되지 않아요.

이번엔 팀 모두가 쓸 연결을 만들려고 --scope project로 추가했어요. 이 정보는 어디에 저장될까요?

맞아요. project 스코프는 폴더 루트의 .mcp.json에 기록돼요. 이 파일을 깃에 커밋하면, 저장소를 받은 동료의 Claude Code가 같은 연결을 그대로 갖게 돼요. 이게 '팀 공유'의 정체예요.

같은 Slack 연결도 어느 칸에 넣느냐로 운명이 갈려요.

🔒 local (나만): 내 노트북에만 남아요. 동료가 같은 가게 저장소를 받아도 그 사람 화면엔 Slack 연결이 없어요. 혼자 잠깐 쓸 실험용에 좋아요.

👥 project (.mcp.json): 폴더 안 .mcp.json에 적혀 깃으로 함께 배포돼요. 새 팀원이 저장소만 받으면 설명 없이도 같은 연결을 써요. 팀 표준을 한 번에 맞추죠.

팀 공유 연결은 결국 그냥 파일 하나예요. 가게 폴더의 .mcp.json을 열어 무엇이 적혀 있는지 봐요.

cat .mcp.json — 팀 공유 연결이 적힌 파일이 있는지 확인해요

보이죠? 사람이 읽을 수 있는 평범한 텍스트예요. 그래서 여기에 비밀번호나 API 키를 적으면 그대로 깃에 올라가 큰일 나요 — 바로 다음 칸의 주의사항입니다.

.mcp.json은 깃으로 모두에게 퍼져요. 그러니 가게 결제 API 키 같은 비밀값을 파일에 직접 적으면 안 돼요. 대신 비밀은 각자의 컴퓨터에 있는 ___(환경 변수)로 넘기고, 파일엔 '그 변수를 읽어라'만 적어요. 빈칸의 영어 단어는?

정답! env(환경 변수)예요. 추가할 때 --env API_KEY=...처럼 넘기면, 키는 각자 기계에만 남고 깃에 올라가는 파일엔 안 들어가요. 팀엔 연결을 공유하되 비밀은 공유하지 않는다 — 이게 핵심 규칙이에요.

동료가 "Slack 연결이 안 돼요"라고 합니다. 무작정 지우지 말고 점검 → 해제 순서로 차분히 접근해요. 올바른 순서로 정렬해보세요.

list로 보기 → 상태 확인 → remove로 해제 → 다시 add. 무엇이 있는지 모르고 지우면 멀쩡한 연결까지 날려요. 먼저 보고, 그다음 손대기가 안전한 순서예요.

실험용으로만 켰던 local 연결 하나를 깔끔히 정리해봐요. claude mcp remove로 끊습니다.

claude mcp remove slack — 더 안 쓰는 연결을 이름으로 해제해요

깔끔하게 끊겼어요. 해제는 이렇게 가벼워요 — 그래서 부담 없이 켜보고, 안 맞으면 지우면 돼요. 가설 대장은 늘 정돈된 상태로.

한 줄로

MCP 연결은 어디 적느냐(스코프)가 곧 누가 쓰느냐예요. local=여기 나만 · project(.mcp.json)=깃으로 팀 모두 · user=어디서나 나만. 팀 공유 땐 키는 env로, 점검은 list로 보고 → remove로 해제.

다음 레슨에서

그런데 연결을 자꾸 늘리다 보면 도구가 수십, 수백 개가 돼요. 그래도 Claude는 왜 안 느려질까요? 'Tool Search — 도구 100개여도 안 무거운 이유'를 다음 레슨에서 풉니다. 가게의 작업방은 계속 정돈됩니다. 🌱